Track Events Configuration

Last Updated: August 01, 2023 21:12

This article outlines the different methods for configuring Track Events. For more general information about this feature, see the Track Events article.

Track Events allow you to record your Visitors' actions. Each action is known as an event. Each event has a name and properties. For example, a "Registered" event may have properties like "plan" or "accountType."

There are three ways to send Track Events to Pendo:

Segment.com
Server Side
Client Side

Track Event Limits

There are several hard and soft limitations to consider when implementing Track Events. Some are fixed restrictions enforced by the Pendo platform while others are best practice recommendations for optimal performance.

Keys

Your subscription can have up to 10,000 unique custom event property keys, including Click Event properties.

Types

Pendo supports up to 5000 different Track Event types per Pendo application.

Field Names

There are no restrictions on the server-side"event":or client-sidependo.track("name"value used to name the track event.

Property names:

Must only use letters, numbers, or underscores.
Can't begin and end with double underscores __*__.
Must be 32 characters or fewer.
Can't begin with a number.

Properties with an unsupported format don't display in Pendo. We recommend using a unique name for each property across the subscription to avoid confusion when viewing data in Pendo.

Values

Values with more than 512 bytes appear as event properties JSON too large in the Pendo UI. This limit applies to the whole properties JSON, not a single event property value.

Property values must be categorized as string or boolean to use Group By in Data Explorer. There is no limit to the number of values that can be grouped in Data Explorer.

Notice: Track event properties are not intended for use when the total number of unique values for the property may exceed 10,000. While we don't set a hard limit on this, very high property cardinality is likely to cause performance issues with track events and aggregations.

Volume

Pendo can handle a high volume of inbound Track Events.

There is no hard limit for the number of properties that can be passed with a single Track Event type but, depending on the size of the data in the properties, a large number can cause degradation in performance.

As a general guideline, 20 properties may cause performance issues if the strings are large, and 50 properties will likely cause performance issues. Strings should be less than 500 bytes.

Segment.com

For more information on Pendo’s integration with Segment, see the Segment.com Integrations Overview.

Server Side

The Track Event Shared Secret Key is required to set up the integration. This key is different from the subscription key that appears in your Pendo installation or integration keys. A Pendo Admin can access this key in Subscription Settings > Applications. Find and open your app, and then select Show on the Track Event Shared Secret row.

API Requirements

For a technical explanation and code examples for the https://app.pendo.io/data/track endpoint, refer to the Track endpoint API documentation.

Access Level: Track Event Shared Secret key
Method: POST
API Endpoint: https://app.pendo.io/data/track
Parameters: N/A

Request Headers

x-pendo-integration-key : Track event shared secret key (required)
content-type : Formats the input from raw text to JSON for the server to properly process the request

Request Body

type : Must be "track"(required)
event : Name of the action that a user has performed (required)
visitorId : Unique string identifier for the visitor (required)
accountId : Unique string identifier for the account to which the visitor belongs (highly recommended)
timestamp : time (int64 in milliseconds after the epoch - epoch converter) that the event occurred (required)
properties : Free-form dictionary of properties of the event (optional)
context: Browser context provides useful context about the event. Required for a request, but can be left blank ("context":{})

If the Track Event of the Visitor ID or Account ID doesn't already exist in Pendo, a new record is created from the first visit that Pendo receives the event. The setting, Count Track Events Received for a Visitor as Time in Application, can be reviewed in your subscription settings in the application's details.

If the Count Track Events Received for a Visitor as Time in Application setting is enabled, the newly created Visitor or Account appears as a metric displayed in tables, reports, dashboards, and track events, and counts as time on the application. This setting isn't retroactive and doesn't impact track events that Pendo has already received. It does affect events going forward.
If the Count Track Events Received for a Visitor as Time in Application setting is disabled, the newly created Visitor or Account doesn't appear as a metric in tables, reports, dashboards, and track events, and doesn't count as time on the application.

To learn more about the Count Track Events Received for a Visitor as Time in Application setting, see this Tech Note.

Note: Any Track Event with a timestamp over 7 days isn't processed. Any Track Event with a time stamp before the creation of the Track Event Type isn't processed. Any Track Event with a timestamp before the subscription creation isn't processed.

Browser Context

Browser context provides useful context about the event.

ip : Current user’s IP address
userAgent : User agent of the device making the request (recommended)
url : URL of the current page in the browser (optional)
title : Title of the current page in the browser (optional)

Note: If you have remote IP or title blocked during Pendo install, browser context isn't collected even if you set it here.

Responses:

200 : Track event was sent as requested

Sample Payload

{
    "type": "track",
    "event": "Registered",
    "visitorId": "unique-string-id",
    "accountId": "account-id-of-visitor",
    "timestamp": 1524069206000,
    "properties": {
        "plan": "Pro Annual",
        "accountType": "Facebook"
    },
    "context": {
        "ip": "76.253.187.23",
        "userAgent": "Chrome/65.0.3325.181",
        "url": "https://mypage.com/admin",
        "title": "My Page - Admin"
    }
}

Client Side/Agent

This method allows you to pass Track Event information using the Pendo client/agent. This format is supported in Code Block Building Blocks in Guides built with Visual Design Studio.

Note: Agent/Client side Track Events are only available in agent version 2.14.3 and later.

Input Format

pendo.track("NAME", {
  PROPERTY1: "PROPERTY1VALUE",
  PROPERTY2: "PROPERTY2VALUE",
  PROPERTYN: "PROPERTYNVALUE", 
  BROWSERPROPERTY: "BROWSER.VARIABLE",
  ...
});

Input Example

pendo.track("Registered", {
  plan: "Pro Annual",
  accountType: "Facebook",
  activeGuide: pendo.getActiveGuide().guide.name,
  width: JSON.stringify(window.innerWidth),
  height: JSON.stringify(window.innerHeight)
});

Output Example

 "props": {
    “plan”: "Pro Annual",
    “accountType”: "Facebook",
    "activeGuide": "Resource Center Targeted Guide",
    "width": "776",
    "height": "1009"
  },

Mobile Track Events

This method allows you to pass Track Event information using the Pendo SDK.

Note: Mobile Track Events are only available in SDK version 2.1 and later. For earlier versions see Mobile Custom Events article.

iOS

[[PendoManager sharedManager] track:@"event_name" properties:@{ @"key1" : @"val1" , @"key2" : @"val2"}];

Swift

PendoManager.shared().track("event_name", properties: ["key1":"val1", "key2":"val2"])

Android

HashMap<String, String> properties = new HashMap<>();
properties.put("item", view.toString());
properties.put("index", String.valueOf(i));
Pendo.track("item_selected", properties);

See here for Mobile Track Events examples.

Troubleshooting

I sent my Track Event but it doesn’t appear on the Track Events page.

It can take up to 15 minutes for the Track Event to appear on the Track Events page. Ensure the timestamp of the event is a date after your Pendo subscription was created.

`pendo.track` isn't a function in the console and the Track Event isn't appearing on the Track Events page.

This is due to the Track Event function running before the Pendo agent loaded. To check if the agent has loaded before the Track Event function is run, use example below:

function pendoTrack(name, data) {
    if (pendo && pendo.isReady && pendo.isReady()) {
        return pendo.track(name, data);
    }
    setTimeout(function() {
      pendoTrack(name, data);
    }, 500);
}

pendoTrack("NAME", { PROPERTY1: "PROPERTY1VALUE", ... });

I sent my Track Event and I can see the Track Event Type on the Track Events page, but the actual event isn't showing up.

Pendo processes the previous hour’s data at the top of the hour and it can take up to 15 minutes for the data to appear in the UI. If you're looking for data from the current day, ensure that you're using the "Today" date range or that your date range includes the current day.

The timestamp of the event must be after the Track Event Type was created.

Some example timestamp issues that would cause this situation include:

Timestamp set to before the subscription was created.
Timestamp set to hours before the initial event was sent to create the track type. For example, event time of 5 a.m. but event was sent/track type was created at 3 p.m.
Timestamp set the day before the initial event was sent to create the track type. For example, event date of 7/18 but event was sent and track type was created on 7/19.