Behavioral tracking is the data foundation of Constructor. Each search, click, add to cart, and purchase on your site or app is sent to Constructor as an event. Constructor's AI models learn from these events to rank results, personalize them for each user, and measure A/B tests. If tracking is incomplete or inaccurate, Constructor cannot optimize results for your users. This guide explains the tracking approach for each platform.

Tracking approaches

Beacon

The beacon is a JavaScript file that Constructor builds for your site. You load it with one script tag. Loading the beacon shows the tag.

The beacon does not know which element on your page is a search result or an add to cart button. You tell it with data-cnstrc-* attributes (HTML attributes that label an element for Constructor). For example, data-cnstrc-item-id on a product tile gives the ID of that item. When the page loads or the user clicks, the beacon reads these attributes and sends the correct event.

Use these guides to set up tracking requirements for web:

1. Loading the beacon shows the script tag, the pages that must load it, and the other ways to load it.
2. Data-driven event tracking lists the attributes for each page type, for example search results, browse pages, product pages, and the cart.
3. Data Attributes Validator Extension (DAVE) is a Chrome extension. It shows the attributes on a live page to validate the surfaced data attributes.

The beacon also sets the identification parameters for the browser: the client ID i and the session ID s. Identification parameters explains how they are assigned and stored.

Native apps

Why an app does not use the beacon

The beacon runs in a web browser. It reads attributes from the HTML of the page and listens for clicks on those elements. A native app does not render HTML, so the beacon has nothing to read and no place to run.

The SDKs

• iOS: iOS / Swift. In the repository documentation, see the Instrument Behavioral Events section for the tracking methods.
• Android: Android / Kotlin. In the repository documentation, see the Instrument Behavioral Events section for the tracking methods.

Each SDK also requests results, so one SDK can do both jobs in your app. Frontend integration options explains how to request results.

What the SDK handles

When your app starts the SDK for the first time, the SDK creates the client ID i and stores it on the device. The ID stays the same until the user removes the app or clears its data.

The SDK also manages the session ID s. It starts at 1 and increments after 30 minutes without activity. The SDK sends the session start event for you.

The SDK adds i and s to every event and every results request. You do not send them yourself.

What your app must do

• Call a tracking method for each event. The SDK does not detect user actions. If your code does not send an event, Constructor does not receive it.
• Set the user ID for a signed-in user. Only your app knows who is signed in. When the user signs in, set the user ID on the SDK. When the user signs out, clear it. The repository documentation linked above shows how. See Omnichannel personalization for how Constructor uses this value.
• Pass the identifiers to your backend. If your servers request results for the app, read i and s from the SDK. Send them with each request. The repository documentation linked above shows how to read them. Required parameters lists the other values that the request needs.

React Native

A React Native app uses the JavaScript client (version 2.20.0 or later), not the iOS or Android SDK. The client runs in DOM-less mode (a mode for code that runs without a browser page). The client wiki shows how to create the client in DOM-less mode.

In a browser, the client stores i and s in cookies and local storage. React Native has neither, so the client cannot create or keep these IDs. Your app does the work that the iOS and Android SDKs do for you.

What your React Native app must do

1. When the app starts for the first time, create the client ID. Use a random UUID (a random, unique ID string).
2. Save the client ID in persistent device storage, for example @react-native-async-storage/async-storage, so that a restart does not clear it.
3. Keep the session ID as a number. Start it at 1, and add 1 after 30 minutes without activity. The client does not measure this time, so your app does it:
   1. Save the time of the last user action.
   2. Before you send each event or request, compare the current time with the saved time. If the gap is more than 30 minutes, add 1 to the session ID. Then call setClientOptions with the new session ID, and then call trackSessionStart.
   3. After you send each event or request, save the current time as the time of the last user action.
4. When you create the client, pass clientId, sessionId, and sendTrackingEvents: true. If clientId or sessionId is missing, the client throws an error.
5. On the first visit, after you create the client, call trackSessionStart. Step 3 covers the other case, when the session ID goes up. The client does not send this event for you.
6. When the user signs in, set userId. When the user signs out, clear it.
7. When the user ID changes, call setClientOptions with the new userId. You do not need to create a new client.
8. Call a tracking method for each event, for example trackSearchSubmit or trackPurchase.

constructorio-identity is the code that the browser uses to create these IDs. You can use it as a model for your own code.

The tracker module documentation lists each tracking method and its parameters.

What to test

• Close the app and open it again. Make sure that the client ID stays the same. If the client ID changes on each start, Constructor counts one user as many users. This is the first failure to look for.
• Make sure that results requests and tracking events send the same i and s values.

In a React Native app, the JavaScript client reports itself as ciojs-client-domless- followed by its version. A React Native app sends this value on both iOS and Android. If you need separate iOS and Android reports, agree with Constructor how to identify each platform before your release. Constructor cannot add the platform to events that the app already sent.