Track Events Configuration

Overview

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

Track Events allow you to record any actions your users perform, along with any properties that describe the action. 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 different ways to send Track Events to Pendo - Segment.com, Server Side, and 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 general recommendations that should be followed for the best performance.

Types

Pendo supports up to 5,000 different Track Event types. 

Field Names

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

Property names must use lowercase letters, numbers, or underscores only. They cannot begin and end with double underscores __*__. Properties with an unsupported format will not 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 1,024 characters will appear as property too big, sha1={hash of the value} in the Pendo UI.

Properties with more than 200 different values received by Pendo cannot use Group By in Data Explorer. This is typically an issue when the property is collecting a number or free text field.

Volume

Pendo can handle a high volume of inbound Track Events. The only limit is one Track Event per Visitor per second.

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 have performance issues. Strings should be less than 500 bytes.

Segment.com

More information on Pendo’s integration with Segment can be found in this article.

Server Side

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 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":{})

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)

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.

Input Format

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

Input Example

pendo.track("Registered", {
  plan: "Pro Annual",
  accountType: "Facebook"
});

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

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

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

FAQ/Troubleshooting

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

It may take up to 15 minutes for the Track Event to appear on the Track Events page. You will also want to ensure the timestamp of the event is a date after your Pendo subscription was created.

I see pendo.track is not a function in the console and the Track Event is not appearing on the Track Events page

This is due to the Track Event function running before the Pendo Agent has loaded. To check if the agent has loaded before the Track Event function is run, see 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 although I can see the track type on the Track Events page, the actual event is not showing up.

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

The timestamp of the event needs to be after the Track Type was created.

Some example timestamp issues that would cause this situation:

1. Timestamp set to before the subscription was added
2. Timestamp set to hours before the initial event was sent to create the track type – event time of 5 AM but event was sent/track type was created at 3 PM
3. Timestamp set to day before the initial event was sent to create the track type - event date of 7/18 but event was sent/track type created on 7/19