This article outlines each method for configuring Track Events, specifically for developers responsible for implementing these configurations. For more general information about Track Events, see Track Events.
Track Events are snippets of code added to your website that allow you to record specific visitor actions that might not be captured through click events. Each action generates an event, and each event has properties associated with it. For example, a "Registered" event might include properties like "plan" or "accountType."
There are three ways to send Track Events to Pendo:
- Through our Twilio Segment integration. This method is implemented through Segment using webhooks.
- As a server-side integration. This involves configuring an API call to Pendo for actions occurring on your backend that aren't part of user interactions on your site.
- As a client-side integration. This can be implemented for web or mobile applications to capture events that aren't considered Feature clicks within your app.
Understand Track Event structure and data
Before configuring Track Events, it's important to understand the structure and limitations of the data you plan to send to Pendo. This includes fixed restrictions enforced by the Pendo platform and best practice recommendations for optimal performance.
Name
Pendo supports up to 5,000 different named Track Events per Pendo app.
Timestamp
The timestamp should reflect the current time whenever possible. Events with past timestamps won't be processed during the regular hourly intervals and will only appear in the UI after Pendo's daily and weekly event reprocessing.
Pendo can't process data associated with a Track Event if:
- The timestamp exceeds seven days.
- The timestamp occurred before the name was defined.
- The timestamp occurred before the subscription was created.
Event properties
You can capture a variety of data as event properties attached to Track Events. This could include window size, text on the page, server-side information that doesn't exist on your website, and more.
Event properties consist of key-value pairs, where you define the field name as the key and the event property value as the value. Your subscription can have up to 10,000 unique custom event property values, including click event properties.
If event properties exceed 512 bytes, event properties JSON too large displays in the Pendo UI. The entire "properties": {} line, including "properties", its quotes, the JSON object, and its brackets and values can't exceed 512 bytes.
Event property names
When naming event properties, follow these requirements:
- Use only letters, numbers, and underscores.
- Don't begin or end with double underscores.
- Keep names under 32 characters.
- Don't start with a number.
Properties with unsupported formats don't display in Pendo. To avoid confusion when viewing data in Pendo, we recommend using a unique name for each property across your subscription.
Event property values
Property values must be categorized as string or boolean to use Group By in Data Explorer and funnels.
Track Event properties aren't intended for use when the total number of unique values might exceed 10,000. Although there's no hard limit, very high property cardinality can cause performance issues with Track Events and aggregations.
Volume and throughput
Pendo can handle a high volume of inbound Track Events. There's no hard limit on the number of properties that can be passed with a single Track Event type. However, large amounts of data can degrade performance.
As a general guideline, 20 properties can cause performance issues if the strings are large, and 50 properties are likely to cause performance issues. Strings should be less than 500 bytes.
Visitor and account records
If the Visitor ID or Account ID from a Track Event doesn't already exist in Pendo, a new record is created upon the first event received for that visitor and account. Whether this event counts toward visitor activity is controlled by the Count Track Events as time in app application setting. Admins can find this setting by navigating to Settings > Subscription Settings > Applications and opening the relevant app.
- If Count Track Events as time in app is turned on, the newly created visitor or account is counted as time spent in the application and reflected in tables, reports, dashboards, and Track Events. This setting isn't retroactive and doesn't impact Track Events that Pendo has already received.
- If the Count Track Events as time in app setting is turned off, the newly created visitor or account isn't counted as time spent in the application and isn't reflected in tables, reports, dashboards, and Track Events.
For more information about the Count Track Events as time in app setting, see Track Events in our Time on page and app calculations article.
Configure through Twilio Segment
If you have a Twilio Segment integration, Track Event configuration is handled through server-side webhooks. For instructions, see Twilio Segment integration overview.
Configure on the server side
To set up Track Events on the server side, you need the Track Event shared secret key, which is different from the subscription key found in your Pendo installation or integration keys.
A Pendo Admin can access the shared secret key by navigating to Settings > Subscription Settings > Applications, selecting the relevant app, then selecting Show next to Track Event shared secret.
After you have your shared secret key, see our Track endpoint API documentation for technical details on how to format your API request and code examples.
Here's a sample payload for a server-side Track Event:
{
"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"
}
}Configure on the client side
Client-side Track Events are collected in the same manner as regular events, automatically recording the time and URL at which the event was generated.
The client-side configuration allows you to pass Track Event data through the Pendo web agent or through the mobile SDK.
Note: Client-side Track Events are only available in agent version 2.14.3 and later, and SDK version 2.1 and later.
Web agent
For client-side Track Events, you can pass variables accessible to the browser as strings. This format is also supported in guide code blocks built in the Visual Design Studio.
Here's the Track Event input format:
pendo.track("NAME", {
PROPERTY1: "PROPERTY1VALUE",
PROPERTY2: "PROPERTY2VALUE",
PROPERTYN: "PROPERTYNVALUE",
BROWSERPROPERTY: "BROWSER.VARIABLE",
...
});Here's an 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)
});Here's an output example based on the input:
"props": {
“plan”: "Pro Annual",
“accountType”: "Facebook",
"activeGuide": "Resource Center Targeted Guide",
"width": "776",
"height": "1009"
},
Mobile SDK
This method allows you to pass Track Event information using the Pendo SDK. The format you use to send Track Events varies depending on the operating system and programming language your mobile app uses, each detailed below.
iOS: Objective-C
[[PendoManager sharedManager] track:@"event_name" properties:@{ @"key1" : @"val1" , @"key2" : @"val2"}];
iOS: 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);
For more examples, see Mobile Track Events Example.
Troubleshoot Track Event issues
If you experience issues with Track Event data not populating in Pendo as expected, see Track Event data is missing in the UI for a list of solutions.