Tracking code

Website session tracking allows you to:

• Track both anonymous and known activity on your website and store, and
• Display capture widgets to visitors.

Configure the tracking code in your data source

By default a website session tracking code is created for all Ortto accounts. This can be found by navigating to Data sources and selecting the tracking code data source (it will usually be named after your account/instance).

You can find installation instructions by clicking on the tracking code data source. There is an option to copy the code or email the instructions to a developer.

If you have more than one tracking subdomain enabled in your account, you will have the option to select the subdomain to include in the tracking code. Learn more about tracking subdomains in Custom domains.

If you’re using one of the data sources listed above, the tracking code will automatically be installed (e.g. into your theme.liquid file for Shopify) and will work automatically. No additional setup is required.

The website session tracking works similar to Google Analytics. We recommend adding this code using Google Tag Manager (GTM) or in the  …​  section of the HTML on your website.

User session association

User sessions are identified using activities that help with identification, for example:

• Email clicks,
• Capture forms,
• Session association in the tracking code.

To associate a known user session by email address replace the default:

javascript
 
ap3c.track({v: 0});

with the following to your tracking code:

javascript
 
ap3c.track({"v":0,"email":"user@emaildomain.com","first":"John","last":"Apple"});

To associate a known user session by external ID replace the default ap3c.track({v: 0}); with the following in your tracking code:

javascript
 
ap3c.track({"v":0,"ei":"ID4674","first":"John","last":"Apple"});

Set the merge and find strategies for user session association

When sending a person's data via the ap3c.track method, you can set a merge strategy and a find strategy to determine how the data is ingested.

You may also wish to set a custom field as a merge key.

Skip non-existing contacts

If you have configured your tracking code to identify a person/contact by their email addresses but you only want to associate user sessions with contacts that already exist in your CDP (not create new contacts), you can add a skipNonExisting parameter set to true.

For example:

javascript
 
ap3c.track({email: "contact@example.com", skipNonExisting: true});

Add a callback for user association

You can add a callback function to ensure that user session association does not get interrupted by other actions or activities. For example, a person performs an action on your website that triggers a custom activity, such as submitting a donation which creates an event for your "Donation received" custom activity.

Adding a callback function will ensure that Ortto can capture both the user association and the custom activity event. Without the callback you may encounter a race condition where the activity function is called before the user association can occur, which may result in contacts missing the custom activity event.

So instead of structuring the track and custom activity functions like this:

javascript
 
ap3c.track({v: 0});
ap3c.activity(act);

structure it like this to ensure that user association has been achieved when the activity function is called:

javascript
 
ap3c.track({email: "contact@example.com"}, function(){
  ap3c.activity(act);
});

Activities created from the website session tracking code

There are two activities that come from the website session tracking:

• Website session, and
• User session.

A website session is an activity for both anonymous and known sessions. It can be used to report on all website sessions. Each session is limited to 50 pages per session and has a maximum 12 hour session time out. We automatically suppress the website session activity in people and organization contact profiles, so you will only see user sessions because they are associated. Website session activities can be used in reports and for filtering people based on activity in your customer data platform (CDP).

A user session is activity of known sessions. It is a duplicate of a website session activity but associated with a known user (contact) in your database. It has the same limitations of 50 pages per session and has a maximum 12 hour session time out.

If a user association happens during an anonymous session, anonymous activities that occurred within the last 15 minutes will be recorded against the known user (contact). For example, a person who browses your site (anonymously) then signs in will have their anonymous session (web session) data prior to sign-in backfilled (as a user session) once their identifying data has been provided and they become a known user.

Both website session and user session activities will appear in your CDP after a short delay (usually around 15 minutes). The session must conclude and timeout before the activity will be generated.

Tracking across multiple domains

If you use the same tracking code in multiple domains, we recommend sharing the tracking code’s session ID across domains. Doing so will track an individual user (known or anonymous) as they navigate across your domains, such as from your .com domain to your .app domain. This will help avoid a break in the UTM tracking or avoid separate sessions being created for the user.

Sharing the session ID across domains is important if you are sending push notifications to ensure that a user who has accepted to receive notifications on both your .com and .app domains, for example, does not receive the same notification twice.

Usually, Ortto stores session data inside the website cookies to identify and associate the current browsing session with a user. As cross-domain cookies are generally prohibited by modern browsers, you’ll need to use a query parameter to share the session ID between sites.

Configure your tracking code to support cross-domain tracking

To share the session ID between domains, you’ll need to configure your tracking code’s initialize function (at ap3c.init) to enable cross-domain tracking.

In your tracking code, list the domain cookies you want to track (e.g. your root domain "mybrand.com" and your subdomain "mybrand.app") and the link type you prefer --h or g at cookieDomains. Read below for a description of how each link type will work.

Here is an example of what this will look like in your tracking code:

Configured ap3c.init function with cookieDomains specified and link type h

javascript
 
ap3c.init('<Your capture key>', 'https://capture-api.autopilotapp.com/', {cookieDomains: ['.mybrand.com', '.mybrand.app'], link: 'h'});

Configured ap3c.init function with cookieDomains specified and link type g

javascript
 
ap3c.init('<Your capture key>', 'https://capture-api.autopilotapp.com/', {cookieDomains: ['.mybrand.com', '.mybrand.app'], link: 'g'});

Once you have configured your tracking code, Ortto will automatically append the query parameter ap3c=${ap3c.getCookie()} to your website’s redirect function, according on the link type you used in the tracking code (h or g):

• For link type h: When this is passed, our capture script will go through all anchor tags () in the current webpage and append the current session ID (string) to it.
  For example, a link like <a href="https://mybrand.com" rel="nofollow">My Brand</a> will be appended like so <a href="https://mybrand.com#ap3c=<Ortto capture session string>"
• For link type g: When this is passed, our capture script will append the session ID (string) in the URL params.
  For example, a link like <a href="https://mybrand.com" rel="nofollow">My Brand</a> will be appended like so <a href="https://mybrand.com?ap3c=<Ortto capture session string>"

This will ensure that the cookie from site 1 (mybrand.com) is appended as a query parameter in the page redirect. So when the user visits site 2 (mybrand.app) the tracking code will automatically detect and use the session from site 1 available in the query parameter and continue to track the user’s session (all session activities will be counted within the same session).

Tracking multiple subdomains

If you wish to track an individual user (known or anonymous) as they navigate across your subdomains, you can set the domain cookie on your root domain and it will include any subdomains of the root.

For example, you have a root domain "mybrand.com" and subdomains "app.mybrand.com" and "developer.mybrand.com". If you set the cookieDomains value in your tracking code as ".mybrand.com", it will allow "app.mybrand.com" and "developer.mybrand.com" to receive the user's session cookie.

Here is an example of what this will look like in your tracking code:

javascript
 
ap3c.init('<Your capture key>', 'https://capture-api.autopilotapp.com/', {cookieDomains: ['.mybrand.com']});

Hide the Talk widget when enabled

If you have the Talk messenger widget enabled (turned ON), it will display on any page which has the tracking code installed.

You have the option to hide the widget on selected pages (but keep it enabled for other pages). To do so, on the pages where you want the widget hidden, add disableTalk: true to the initialize function (ap3c.init) of the tracking code.

Example section of tracking code with Talk widget disabled

javascript
 
ap3c.init('<Your capture key>', 'https://capture-api.autopilotapp.com/', {disableTalk: true});

Domain whitelisting

You have the option to limit the domains for which your tracking code can be used. Creating a domain whitelist will ensure that if another party scrapes your site’s HTML to make a copy of your site, you won’t receive web session activities that result from that other party having your tracking code. 

If another party does end up using a copy of your site that contains your tracking code and you have a domain whitelist, Ortto will ignore any session activities originating from domains that are not whitelisted. 

By default, all domains are permitted to use the tracking code, so it’s a good idea to whitelist your domains if you have previously experienced your site being scraped or copied.

To create a domain whitelist:

1. On your tracking code data source page, under Domains, click Edit.
2. Click Add domain and enter a domain into the field.
3. To add more domains, click Add domain again and populate the additional entries.
4. Click Save to finish.

Allowed custom field as merge key

You can set a custom field as a merge key for user session association. Learn about tracking code merge keys and adding a custom field.

Clear session data

If you need to clear or reset the session ID for a browsing session (de-associate a session from the current browsing session), such as when a user logs out of your app, you can call ap3c.clearSession(). The clearSession method will clear, for the current session, the session cookie, the capture widget cache, and the Talk messenger cache (if enabled).