Technical Docs WebView Tracking Tag implementation

WebView Tracking Tag implementation

Use this document to enable WebView tracking in your mobile app. You'll need to implement the Contentsquare WebView JavaScript Tracking Tag in the web pages called in your mobile app to build a JavaScript Bridge between your WebView content and the native SDK.

Get Started

The WebView JavaScript Tracking Tag is responsible to establish communication with the SDK in the parent app.

To set up, you just need to add the following lines of code on every page that will be called in a WebView of your app, either at the end of the body marker, or via a TMS.

<script type="text/javascript">
  (function () {
    var mt = document.createElement("script");
    mt.type = "text/javascript";
    mt.async = true;
    mt.src = "//t.contentsquare.net/wvt/web-view.js";
    document.getElementsByTagName("head")[0].appendChild(mt);
  })();
</script>

This code creates a function which will add an asynchronous call to a script and then execute the function. This is a way to avoid other elements loading being blocked on the page. This reduces the impact of the tag on the page's performances.

Privacy

Even though Contentsquare only collects usage data on your app, the SDK will consider every new user to be opted-out. To start tracking, the SDK Opt-in API must be called.

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 functions (opt-in or opt-out).

Opt-in

Use the Opt-in API to get user consent. Calling this API will generate a user ID and initiate tracking.

window.cs_wvt = window.cs_wvt || [];
window.cs_wvt.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 directory regarding to Contentsquare are deleted. This means that the user ID is deleted. The SDK will never track and collect any data from the user's phone unless the Opt-in API is called again.

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

Track Pageviews

Contentsquare aggregates user behavior and engagement at the screen/page level. To do so, it is required to track page transitions by calling a dedicated command. When the command is called, the WebView Tracking Tag logs a pageview event that identifies the new page with the Page Title provided.

window.cs_wvt = window.cs_wvt || [];
window.cs_wvt.push(["trackPageview", "My Custom Page Title"]); // triggers a pageview event with "My Custom Page Title" as the page title

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.cs_wvt = window.cs_wvt || [];
window.cs_wvt.push([
  "trackTransaction",
  { value: 1000, currency: "EUR", id: "my-transaction-id" },
]);
// 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 passed doesn't match the supported currencies, the SDK will send 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 recorded.
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 maximums length 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.cs_wvt = window.cs_wvt || [];
window.cs_wvt.push([
  "trackDynamicVariable",
  { key: "my-string-dvar", value: "my-awesome-string-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, long press, swipes (with finger direction), pinches (in and out)
  • HTML DOM when a snapshot of the screen is triggered by the SDK (see section on Enable Snapshot Mode in the iOS/Android SDK docs).

Conflict with Contentsquare Web Tracking Tag

If the pages called in your app's WebViews are also part of your main website and you are using the main Web Tracking Tag, ensure that:

  • When the page is loaded in your app's webView: only the WebView Tracking Tag is loaded (and not the main Web Tracking Tag)
  • When the page is NOT loaded in your app's webView: only the main Web Tracking Tag is loaded (and not the WebView Tracking Tag)

Changelog

1.3.0 - 2022.05.17

Versions 1.1.0 and 1.2.0 were not deployed

1.0.0 - 2021.01.19

  • Initial release

📚 iOS SDK WebView tracking

📚 Android SDK WebView tracking