Go to ortto.com
Home Data sources Configuring a new data source Tracking code Tracking code

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.

NOTE: If you have configured any of the e-commerce data source integrations through the Data sources page, then Ortto session tracking functionality is configured automatically. Therefore, you do not need to configure the tracking code below for these types of data sources.

Configure the tracking code in your data source

Here’s how to set up and install your website session tracking code with Ortto.

  • Locate your tracking code: Access your tracking code by navigating to Data sources and selecting the tracking code data source, typically named after your account/instance.
  • Installation instructions: Click on the tracking code data source to find installation instructions. You can either copy the code directly or email the instructions to your developer for implementation.
  • Select tracking subdomain (if applicable): If you have multiple tracking subdomains enabled, choose the subdomain you want to include in the tracking code. Learn more about tracking subdomains in Custom domains.
  • Automatic installation: When using supported data sources, such as Shopify’s theme.liquid file, the tracking code installs automatically and starts working immediately. No additional setup is needed.
  • Integration recommendations: For optimal functionality, integrate this code using tools like Google Tag Manager (GTM) or directly in the <head> section of your website’s HTML.

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"});

NOTE: This is a template. The placeholder values provided in this template will need to be replaced with the intended contact values.

TIP: If a user visits a page that includes email= as a query parameter in the URL (e.g. www.example.com?email=help@ortto.com), our system will automatically identify and track that user based on the email provided. In this case, you don't need to identify the user using the method mentioned above.

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 sessions

  • A website session tracks activity for both anonymous and known users.
  • It can be used to report on all website sessions.
  • Each session allows up to 50 pages and lasts a maximum of 12 hours.
  • Website session activities are automatically hidden in people and organization profiles to prioritize user sessions.

User sessions

  • User sessions mirror website sessions but are tied to known users in your database.
  • They also support up to 50 pages per session and expire after 12 hours.
  • User sessions can be used in reports and for filtering based on customer activity in your system.
  • User sessions remain active when contacts visit a new page within 15 minutes of their current page. If users stay on a page for longer than 15 minutes, their current session ends. A new session starts when they visit another page.

Anonymous to known user transition

  • When an anonymous user signs in, any activities from their anonymous session within the last 15 minutes are linked to their user profile.
  • For example, previous anonymous browsing data will be merged into the user session once they become a known user by providing identifying information.

NOTE: The Duration in minutes attribute for these activities is recorded under the following conditions: if a user visits more than one page during their session, and those visits are spaced more than one minute apart.

TIP: Activities from both website sessions and user sessions will appear in your CDP with a slight delay, typically around 15 minutes. The session must end and timeout before the activity is recorded.

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.

NOTE: 

  • You can whitelist up to 60 domains.
  • Once a domain is added (and you’ve clicked Save), it is whitelisted immediately; you do not need to re-upload your tracking code to your website.

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). 

NOTE: Usually, if a user association happens during an anonymous session, anonymous activities that occurred will be recorded against the known user (contact).

However, if clearSession is called between an anonymous session and an associated session, the anonymous activities will not be able to be associated with the known user (because the anonymous session ID has been reset and can no longer be matched to the associated session ID). 

NOTE: After clearSession has run, a new session ID will be assigned the next time the page is loaded, or a user navigates to the page URL.