Prerequisites

• You must have Company or App Administrator permissions in Engage.

Definition

Key benefits

Key details

Usage tracking

Engage usage tracking lets you track individual consumption of the value-creating elements of your app or site.

A trait is an individual user attribute or behavior that you can target, such as device, location, or even business metrics (for example, lifetime value or satisfaction score). Engage lets you track traits based on how often a user has engaged with a specific feature or section of your app, and target users by frequency and recency of engagement for maximum impact. By default, usage traits automatically track visits and minutes, but you can configure them to track additional behaviors in your apps, such as specific pages or screens visited or buttons clicked.

Usage traits can be normalized on a 0–10 scale, with the lowest value in the dataset normalized to 0 and the highest value normalized to 10. Normalization happens in real time as new low and high values are recorded. This lets business teams define “Heavy users” as users whose minutes per visit are growing by 30% or more week over week, without needing to understand site-wide averages or highs and lows.

Understanding usage tracking

Below are the types of usage trackers that are available. A newly added tracker begins collecting information immediately, and it may take up to 24 hours before it can produce meaningful targeting options.

Visit duration

Time spent by the user in the app in MM:SS. Visit duration is recorded at the user level on a daily, weekly, and monthly basis.

Visits

The number of times a user visits your site or app. Visits are recorded on a daily, weekly, and monthly basis. The default visit length is 10 minutes, which is extended in 10-minute increments for as long as the user is using the app.

For day-over-day comparison, Engage compares data from midnight to midnight on one day versus the previous day. For week-over-week comparison, Engage compares data from midnight Sunday to midnight Sunday.

Traits tracked automatically

In addition to visits and minutes, Engage automatically tracks or creates:

• Churn Score — A number between 0–1 indicating the probability that a user will churn, derived using machine learning.
• Device Type — Phone, tablet, laptop, desktop, TV, watch. Also includes full user agent string.
• Device OS — iOS, Android, Windows, MacOS, other. Also includes full user agent string.
• Device Browser — Chrome, Chrome Mobile, Safari, Edge, other. Also includes full user agent string.
• Device Manufacturer — Apple iPhone, Apple iPad, Nexus, Samsung, other. Also includes full user agent string.
• Device SDK — Android Phone, Android Tablet, Google TV, Roku, other. Also includes full user agent string.

The following optional items require processing the end user's IP address. Engage never stores IP addresses.

• Fraud score — A number between 0–10 ranking the user's likelihood of being a fraudulent user, derived using machine learning.

See data privacy for more information on how we process end-user information.

In addition, you can customize the tracker to collect information on specific pages or button clicks.

Concurrent logins and password sharing

The Concurrent logins segment logic identifies when a single user account is actively logged in from multiple locations simultaneously.

• Detection: Generally, our proprietary, privacy-preserving algorithm detects concurrent logins from different locations within a single session.
• Logic basis: The system primarily uses different IP addresses (locations) to detect multiple concurrent logins. Multiple sessions originating from the same IP address are currently treated as a single concurrent login.
• Segment setup: You can set the number of concurrent logins you want to track in the Concurrent logins segment. It's one of our default segments, giving you a ready-made way to detect and prompt users who might be sharing their account credentials.
• Security and compliance: Helps flag potentially suspicious behavior, such as credential sharing or account takeover attempts, by monitoring access from geographically distinct locations.
• Usage control: Allows a merchant to enforce policies on where and how many times an account can be simultaneously active.

Page tracker

A page tracker lets you track specific pages or groups of pages by using wildcards or regex. Here are two examples:

Button tracker (web only)

A button tracker lets you track specific elements that a user clicks using Cascading Style Sheets (CSS):

Custom tracker

A custom tracker lets you send tracking information from any external system to Engage via API or software development kit (SDK), available on Roku, Apple TV, Android, and iOS. For example, if a user's payment has failed, you can send an event from your backend and target that user to update their credit card via Engage.

Set up a tracker

Engage tracks your users' behaviors across your applications. By default, we automatically track user visits and minutes, but you can also add other trackers, such as button clicks and views. Once you've added a tracker, you can use it to target segments, such as the top 20% of users who have downloaded a video.

Here's how to set up a new tracker. Start by going to Settings > Usage Tracking > Add New Tracker:

Web usage

For web apps, you can create two types of trackers: page and track.

• page — Refers to visits to a particular page, such as /settings or /signup
• track — Refers to a CSS id such as #download-btn or a CSS class such as .download-btn

Page example

To track a user's visits to the Settings page:

Track example

To track a user's clicks on a particular button:

Device usage (Roku, Apple TV, Android, iPhone, iPad, or web)

For TVs, tablets, and phones, you can create one type of tracker — custom. You'll likely need your app developer's help to integrate a snippet of code that we provide directly from Pulse.

Custom example

This example shows you how to add a custom tracker. You can use it to track anything on your client, such as a button click, visits to different screens, or a payment.

cURL

Can be used in any system. Provide the associated ENDUSER_ID in your system. Make sure rf-app is set to the actual app ID (from Pulse URL).

[TODO: Dev/PO review — possible issue: the rf-app placeholder's last group has 8 characters, while a standard UUID's last group has 12.]

curl -H 'rf-app: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx' \
     -H 'user-id: ENDUSER_ID' \
     'https://conduit.redcurly.com/ping/?type=custom&custom_field_id=fc4ccd34-7876-430b-8b64-65ac7c19a505'

More on the cURL (server-to-server) method

Optional headers, only needed if your account is configured for them:

Query parameters

A few things to know before you integrate:

• The tracker referenced by custom_field_id must already exist as a usage-type tracker (created via Add New Tracker in Settings > Usage Tracking). Reporting against an ID that isn't configured this way is silently ignored — you won't see an error, but no usage will be recorded.
• An incorrect app ID or tracker ID also won't raise an error — the request still returns 200 OK, but nothing is recorded. Double-check both values when setting this up.
• Processing happens shortly after the request is accepted, not synchronously in the response — don't expect the usage event to be immediately reflected.
• The app ID can also be supplied as part of the URL path instead of a header, but the header form shown above is recommended for server-to-server integrations.

JavaScript

For web or JavaScript clients.

RecurlyEngage.customTrack("fc4ccd34-7876-430b-8b64-65ac7c19a505");

External Web Tracker

For third-party websites. Tutorial: Usage Tracking → External.

HTML

Tracking pixel for emails, web, or JavaScript clients.

<img src="https://conduit.redcurly.com/ping/?type=custom&custom_field_id=fc4ccd34-7876-430b-8b64-65ac7c19a505" />

Swift

For Apple devices.

PromotionManager.customTrack("fc4ccd34-7876-430b-8b64-65ac7c19a505")

Kotlin

For Android devices.

PromotionManager.customTrack("fc4ccd34-7876-430b-8b64-65ac7c19a505")

Roku

For Roku devices.

m.promoMgr.callFunc("customTrack", { custom_field_id: "fc4ccd34-7876-430b-8b64-65ac7c19a505" })

Tracking web actions from other sites

A common example of tracking external conversions is the need to track links that refer users off-site. In many cases, it's difficult to see whether the user actually converted (for example, signed up or paid) after they land on the partner page. The following method requires you to add your user ID to the URL when you redirect to your partner. The partner site should save the user ID. Then, on completion of the conversion, the partner needs to notify Engage. Here's how to configure it.

Custom website action

// https://example.com?campaign_id=456&rf_uid=123
// rf_uid=123 is the important piece
if (RecurlyEngage.anonymousUserId) {
  return window.location.href = "https://example.com?campaign_id=456&rf_uid=" + RecurlyEngage.anonymousUserId;
} else if (RecurlyEngage.userId) {
  return window.location.href = "https://example.com?campaign_id=456&rf_uid=" + RecurlyEngage.userId;
}

External custom tracker

Using events in Google Tag Manager

In some cases, you can use Google Tag Manager (GTM) events to trigger actions with the Engage SDK. Here's a quick primer.

GTM setup

Testing

To test, send an event via the GTM dataLayer. The contents of the Custom HTML tag will execute:

> dataLayer.push({ event: 'test' });

// Test Event for anon user: c7c02a061db6aba3adae5263523005b57a8f90f16cf59d46fe036191213be5dd, user: 123