Technical Docs Mobile Apps WebView tracking

Mobile Apps WebView tracking

Last updated on

To enable WebView tracking in your mobile app, you need to implement the Contentsquare Web Tracking Tag in every web page called in your mobile app for the WebView to communicate with our native SDK.

WebView tracking relies on:

Earlier versions of the WebView tracking feature relied on a dedicated WebView Tracking tag.

Getting Started

The Web Tracking Tag is responsible for establishing communication with the SDK in the parent app.

To set it up, add the following code on every page that will be called in a WebView of your app.

Add it either at the end of the body marker or via a TMS.

Replace YOUR_TAG_ID with the tag ID of your project provided by Contentsquare.

<script type="text/javascript">
  (function () {
    window._uxa = window._uxa || [];
    window._uxa.push(["setOption", "isWebView", true]);
    var mt = document.createElement("script");
    mt.type = "text/javascript";
    mt.async = true;
    mt.src = "https://t.contentsquare.net/uxa/YOUR_TAG_ID.js";
    document.getElementsByTagName("head")[0].appendChild(mt);
  })();
</script>

Handling Web & Webview contexts

This code creates a function that adds an asynchronous call to a script and then executes it. This helps to prevent other elements on the page from being blocked, reducing the impact of the tag on the page's performance.

To use the same tracker for both the Web and WebView use cases, include a conditional statement:

if (aConditionThatTellsYouWeAreInAWebview())
   window._uxa.push(['setOption', 'isWebView', true]);
else
   // do nothing if it's a web browser

Privacy

Our mobile SDK considers every new user to be opted-out by default.

You are responsible for creating the UI asking users for their consent and allowing them to manage their privacy settings and then calling the appropriate Contentsquare following methods (optin or opt-out).

If you think securing user consent is not required for your app, discuss it during the implementation process with your main Contentsquare contact.

Opt-in

Use the Opt-in API to get user consent. Calling this API generates a user ID and initiates tracking.

window._uxa = window._uxa || [];
window._uxa.push(["optin"]);

Opt-Out

Permanently breaking the link and stopping all data collection.

When this API is called, tracking stops immediately, all settings are reset (Session number, Page number...) and all files and directories regarding Contentsquare are deleted. This means that the user ID is deleted. The SDK will never track or collect any data from the user's phone unless the Opt-in API is called again.

window._uxa = window._uxa || [];
window._uxa.push(["optout"]);

Track Pageviews

To aggregate user behavior and engagement at the screen/page level, track page transitions by calling the trackPageview command.

window._uxa = window._uxa || [];
window._uxa.push(["trackPageview", "PAGE_TITLE"]);

The Web Tracking Tag logs a pageview event that identifies the new page with the page title that you provide.

Track Transactions

To associate a user's session with their potential purchases (and corresponding revenue), you must send the transaction via a dedicated API. For each transaction, we send:

  • Price (mandatory)
  • Currency (mandatory)
  • Transaction ID (optional)
window._uxa = window._uxa || [];
window._uxa.push([
  "ec:transaction:create",
  {
    id: "123" /* Transaction ID (string, up to 40 chararacters) */,
    revenue:
      "9.99" /* Transaction's total cost (integer or string, up to 12 digits and 2 decimals - extra decimals are truncated) */,
    currency:
      "usd" /* optional - Currency value (string, numeric or alphanumeric ISO 4217 value) */,
  },
]);
window._uxa.push(["ec:transaction:send"]);
// value is a float
// currency is a string that must be inferior to 10 characters
// id is a string or null

Currency

The currency is conforming to the ISO 4217 standard.
The currency must be passed as an "alphanumeric code".

If the currency doesn't match the supported currencies, the SDK sends a currency value of -1.
It will be processed as the default currency of the project.

Track Dynamic Variables

General principles

Usage

Dynamic variables are additional information on the session that can be used to segment sessions.

For example, they can include information on the A/B Test variations displayed to the current user.

Limits

On the server side
  • It is possible to save up to 40 distinct dynamic variable keys per screenview. If more are received, only the first 40 keys will be kept.
  • If you are using the same key twice on the same screenview, the last value associated with the key will be collected.
On the SDK side
  • Every dynamic variable is composed of a pair of key (max. 50 characters) and value (max. 255 characters string or number of type Long between 0 and 232 - 1). In case these maximum lengths are reached, the SDK will automatically trim the exceeding characters.
  • If key or value are empty, the SDK will instead send the literal string "cs-empty".

Defining dynamic variables

To define and send a dynamic variable, directly use the key and String/Long value once a first screenview has been triggered:

window._uxa = window._uxa || [];
window._uxa.push(["trackDynamicVariable", { key: my_key, value: my_value }]);
// key is a string
// value is either a string or an integer

Type of the value — The value can be either a whole number or a string. For each case, available features won't be the same in the Contentsquare app:

  • For whole numbers, you will be able to do some algebra. Example: sessions with dynamic variable key = "numberOfFriends" and value >= 10_
  • For strings, auto-completion and Regular Expression will be available. Example: sessions with dynamic variable key = "accountType" and value = "Premium"

Collected data

Once communication is established, the tag will start tracking the following events and pass them over to the SDK:

  • Pageviews manually triggered (with the dedicated command)
  • Transactions manually triggered (with the dedicated command)
  • Dynamic variables manually triggered (with the dedicated command)
  • Gestures automatically detected: tap, double tap, swipes (with finger direction), pinches (in and out)
  • HTML DOM and DOM Mutation when session replay is activated
  • HTML DOM when a snapshot of the screen is triggered by the SDK (see Enable Snapshot Mode in iOS and Android docs).

Personal Data Handling

See Personal Data Handling.

Choosing a Data Collection Strategy

There are multiple options for collecting data, and the strategy that is best for you will depend on various factors.

Some questions to consider include:

  • Is the WebView page also visited by web browsers, or is it only used within a WebView context?
  • Are the same teams responsible for these pages in both contexts (on the website and within a mobile app webview), or do different teams work closely together and share a lot of code?
  • Does most of the tracking customization need to apply in both contexts (with little to no differences), such as session replay anonymization/masking rules and event handling?

Migration from the WebView Tracking Tag

To migrate from the WebView Tracking Tag to the Web Tracking Tag, follow these steps:

  1. Update the Tag

    Replace the WebView Tracking Tag:

    //t.contentsquare.net/wvt/web-view.js

    With the Web Tracking tag of your project (either a new tag or the one from a Web project):

    //t.contentsquare.net/uxa/YOUR_TAG_ID.javascript

  2. Update pageview tracking

    Replace the current trackPageview command:

    window.cs_wvt.push(["trackPageview", "My Custom Page Title"]);

    With:

    window._uxa.push(["trackPageview", "My Custom Page Title"]);

    📚 See more about the trackPageView command.

  3. Update the transaction tracking

    Replace the legacy WebView Tracking Tag transaction command:

    window.cs_wvt.push([
  "trackTransaction",
  { value: 1000, currency: "EUR", id: "my-transaction-id" },
]);

    With the transaction commands from the Web Tracking Tag:

    //Create the transaction
window._uxa.push([
  "ec:transaction:create",
  {
    id: "123" /* Transaction ID (string, up to 40 chararacters) */,
    revenue:
      "9.99" /* Transaction's total cost (integer or string, up to 12 digits and 2 decimals - extra decimals are truncated) */,
    currency:
      "usd" /* optional - Currency value (string, numeric or alphanumeric ISO 4217 value) */,
  },
]);
//Send the complete transaction
window._uxa.push(["ec:transaction:send"]);

  4. Update the dynamic variable tracking

    Replace the legacy WebView Tracking Tag dynamic variables command:

    window.cs_wvt.push([
  "trackDynamicVariable",
  { key: "my_key", value: "my_value" },
]);

    With the dvar command from the Web Tracking Tag:

    window._uxa.push(["trackDynamicVariable",
  { key: my_key, value: my_value }
]);

Changelog

📚 Web Tracking Tag Changelog