API Reference

Pageview and Heartbeat Events

By default, we send three events to query.petametrics.com/__activity.gif associated with every pageview.

  • pageview: This is sent immediately upon our Javascript being loaded.
  • stuck_10s: This is sent after you have been on the page for 10 seconds.
  • stuck_3m: This is sent after you have been on the page for 3 minutes.

When you start pulling and showing recommendations from us, there’ll be additional activity events recording when our recommendations get shown, seen, and clicked. We’ll talk about those activities in the next section.
The timers that we use for heartbeat events are configurable. The default timers (10 seconds and 3 minutes) are chosen to achieve a balance between controlling the amount of data sent and getting a sense of user time on site. Depending on your use case, we can add timers for other amounts of time spent.

1. Understand what's getting sent

You can access all events sent to query.petametrics.com using the Network panel.

Request URL: https://query.petametrics.com/v3/999gba4qphtjrmpe/0EMKw_ItTo9Dt37kPEV0Yw/__activity.gif?e=pageview&sppx=0&sppc=0&dh=8783&iwid=1271&ihei=726&ct=Fair+Housing+Act&ccu=https%3A%2F%2Fwww.history.com%2Ftopics%2Fblack-history%2Ffair-housing-act&tspl=24770&blst=20738&ist=24719&iet=24755&ts=1592168127236&jsk=999gba4qphtjrmpe&jsv=20200609&cu=https%3A%2F%2Fwww.history.com%2Ftopics%2Fblack-history%2Ffair-housing-act&uid=0EMKw_ItTo9Dt37kPEV0Yw&sid=a13fa484-82d3-41c3-9e69-af30a67b635c&pvid=6af7e825-7bef-488f-c7ef-4a4103d193ca&ua=Mozilla%2F5.0+(Macintosh%3B+Intel+Mac+OS+X+10_15_2)+AppleWebKit%2F537.36+(KHTML%2C+like+Gecko)+Chrome%2F83.0.4103.97+Safari%2F537.36&l=en-US&os=MacIntel&scd=30&scrh=900&scrw=1440&tzo=420&site_name=HISTORY&sdk=bc-pixel
Request Method: GET
Status Code: 200 
Remote Address: 35.190.14.224:443
Referrer Policy: unsafe-url
alt-svc: clear
content-length: 35
content-type: image/gif
date: Sun, 14 Jun 2020 20:55:27 GMT
server: openresty/1.13.6.2
status: 200
via: 1.1 google
:authority: query.petametrics.com
:method: GET
:path: /v3/999gba4qphtjrmpe/0EMKw_ItTo9Dt37kPEV0Yw/__activity.gif?e=pageview&sppx=0&sppc=0&dh=8783&iwid=1271&ihei=726&ct=Fair+Housing+Act&ccu=https%3A%2F%2Fwww.history.com%2Ftopics%2Fblack-history%2Ffair-housing-act&tspl=24770&blst=20738&ist=24719&iet=24755&ts=1592168127236&jsk=999gba4qphtjrmpe&jsv=20200609&cu=https%3A%2F%2Fwww.history.com%2Ftopics%2Fblack-history%2Ffair-housing-act&uid=0EMKw_ItTo9Dt37kPEV0Yw&sid=a13fa484-82d3-41c3-9e69-af30a67b635c&pvid=6af7e825-7bef-488f-c7ef-4a4103d193ca&ua=Mozilla%2F5.0+(Macintosh%3B+Intel+Mac+OS+X+10_15_2)+AppleWebKit%2F537.36+(KHTML%2C+like+Gecko)+Chrome%2F83.0.4103.97+Safari%2F537.36&l=en-US&os=MacIntel&scd=30&scrh=900&scrw=1440&tzo=420&sdk=bc-pixel
:scheme: https
accept: image/webp,image/apng,image/*,*/*;q=0.8
accept-encoding: gzip, deflate, br
accept-language: en-US,en;q=0.9
referer: https://www.history.com/topics/black-history/fair-housing-act
sec-fetch-dest: image
sec-fetch-mode: no-cors
sec-fetch-site: cross-site
user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.97 Safari/537.36
e: pageview
sppx: 0
sppc: 0
dh: 8783
iwid: 1271
ihei: 726
ct: Fair Housing Act
ccu: https://www.history.com/topics/black-history/fair-housing-act
tspl: 24770
blst: 20738
ist: 24719
iet: 24755
ts: 1592168127236
jsk: 999gba4qphtjrmpe
jsv: 20200609
cu: https://www.history.com/topics/black-history/fair-housing-act
uid: 0EMKw_ItTo9Dt37kPEV0Yw
sid: a13fa484-82d3-41c3-9e69-af30a67b635c
pvid: 6af7e825-7bef-488f-c7ef-4a4103d193ca
ua: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.97 Safari/537.36
l: en-US
os: MacIntel
scd: 30
scrh: 900
scrw: 1440
tzo: 420
sdk: bc-pixel

The "Query String Parameters" section includes the parameters in the query in a human-readable form. The parameters are described below.

Parameters that vary with each event:

  • e is the type of event. In the example above, it is "pageview". The other possibilities are stuck_10s and stuck_3m (for heartbeat events) and some types associated with widget tracking.
  • sppx (not sent by default, but can be turned on) is the pixels scrolled by the user so far. It is 0 if the user has not scrolled at all. For the event of type pageview this is likely to be 0, since it is fired immediately upon the page loading.
  • sppc (not sent by default, but can be turned on) is the percentage of the page the user has scrolled.

Parameters that are the same for all events within the same pageview, but differ across pageviews:

  • pvid is a unique ID generated for each pageview. It is common between all events within a pageview, but different across pageviews.
  • cu is the current URL of the page.
  • ccu is the current canonical URL of the page.
  • ct is the current title of the page.
  • ref is the referrer to the current pageview.

Cookie-based parameters that are the same for all events within the same session (i.e., until the user closes the browser) (see our Cookies and Local Storage section for more):

  • sid is the session ID, and corresponds to the value _igt in the cookie.

Cookie-based user-level parameters (see our section on cookies for more):

  • uid is the user ID, and corresponds to the value _ig in the cookie.

We may additionally tracking other IDs in collaboration with the customer for syncing with othre services, only in collaboration with the customer.
Parameters that are based on browser, device, and system settings. These are generally constant for a given user.

  • ua is user agent.
  • l is the language set by the user in his or her browser.
  • os is the user’s operating system.
  • scd (not sent by default, but can be turned on) is the user’s screen color depth.
  • scrh (not sent by default, but can be turned on) is the user’s screen height.
  • scrw (not sent by default, but can be turned on) is the user’s screen width.
  • iwid (not sent by default, but can be turned on) is the window's inner width.
  • ihei (not sent by default, but can be turned on) is the window's inner height.
  • dh (not sent by default, but can be turned on) is the document height.

Parameters that are based on the loading and timing details:

  • ts is the timestamp from the client's side, as an epoch timestamp.
  • tspl is the time since page load, in milliseconds.
  • blst is the start time of the loading of the LiftIgniter JS file.
  • ist is the start time of the execution of the initialization of the LiftIgniter JS file.
  • iet is the end time of the execution of the initialization of the LiftIgniter JS file.
  • tzo is the timezone offset of the user from UTC.

The parameter jsv is the version of LiftIgniter JS file in the form of the date that the JS file was released.
Although the user’s IP address is not passed as a query string parameter, it is included with the request. We use the IP address to extract information about the user’s location (country, city, and postal code). We do not store the IP address in logs after extracting the user's location.
Additionally, any petametrics.com cookies are sent with the request, but no petametrics.com cookies should be getting set for users who do not directly visit subdomains under petametrics.com.

2. Check that the fields being sent are correct

Based on the descriptions above, you have an idea of what should get sent with each request. You can verify that the right field values are getting sent. Here are a few tips for verification:

  • You might want to test with different device types using the Emulator. When you change the device type using the Emulator, and reload the page, you should see the user agent parameter change. The operating system parameter will not change, because the Emulator does not spoof this variable.
  • For customers who have scroll pixel and scroll percentage turned on: To check that the scroll pixel and scroll percentage work correctly, look at the values sent with the heartbeat events (stuck_10s and stuck_3m) and make sure to actually scroll before these heartbeat events get sent.
  • For the query string parameters that correspond to our cookies, check the values against the cookies, as discussed in our section on cookies.
  • To keep the requests made across multiple pageviews in the Network panel, check the "Preserve log" option.
  • Open a new incognito window to start a new session and a new user. Note that Google Chrome supports only one incognito state at a time, so you need to close existing incognito windows before opening a new incognito window in order to make sure that a new user and new session are created.
  • To start a new session but keep the existing user, quit and restart your browser. Note that on Windows and Linux systems, closing all windows of Chrome or Firefox automatically closes the process. However, on Macs, closing all windows does not close the process, and you need to explicitly quit the process.

3. Report response errors

It is highly unlikely that your query will receive any response other than a 200 OK. if you receive a different response, contact Support. In your email, include as much detail as possible about the error.