Getting Started

Welcome to the SDK implementation guide!

This guide is designed to help you seamlessly integrate our SDK into your application. By following the outlined steps, you’ll be able to collect and analyze data from your app, within just a few minutes.

The Contentsquare Plugin for Cordova is a plugin between the Contentsquare SDKs for iOS and Android, and your Cordova JavaScript code. It allows for the use of our solution both in native and JavaScript parts of your app. The Contentsquare functionality is provided through an NPM package including only the plugin and dependencies to specific versions of the SDKs.

See Compatibility for more information.

Install the plugin as follows, specifying the exact version you want to install if needed:

cordova plugin add @contentsquare/cordova-plugin

If your app is written in TypeScript, you can also install the types definitions package.

npm install -D @contentsquare/cordova-plugin-types

The plugin defines a ContentsquarePlugin object.

Although the object is in the global scope, features provided by this plugin are not available until after the deviceready event.

document.addEventListener("deviceready", onDeviceReady, false);

function onDeviceReady() {
  // ContentsquarePlugin is now available
}

You do not need to do anything to start the SDK. Now that the SDK is a dependency of your app, it will autostart itself when your application starts.

Start your application, and check logs for this output:

CSLIB: Contentsquare SDK 0.3 starting in app: com.example.testapp

CSLIB ℹ️ Info: Contentsquare SDK v0.3 starting in app: com.example.testapp

Contentsquare provides logging capabilities that allow you to inspect the raw event data logged by your app in Android Studio, Xcode, or on the Contentsquare platform.

To view all logs, you must enable in-app features: logging is linked to in-app features being enabled or disabled.

In-app features are essential for your implementation, as it includes key functionalities like snapshot creation and replay configuration.

To allow Contentsquare users to enable in-app features, perform these tasks:

1. Install the Cordova plugin to handle URL schemes
2. Call the SDK when your app is opened with the custom URL

In order for your application to open when you scan the QR code or enter the URL we provide in a web browser, you have to install a Cordova plugin which will handle the URL scheme.

cordova plugin add cordova-plugin-customurlscheme --variable URL_SCHEME=cs-{package-id}
// Example:
// my package id is 'com.mycompany.myapp'
// cordova plugin add cordova-plugin-customurlscheme --variable URL_SCHEME=cs-com.mycompany.myapp

Then, you will need to link your app with our SDK. When your application is started via a deeplink, a specific global JavaScript function, handleOpenURL(), is automatically called in your App. You will have to define this function in the ‘window’ global scope and you will need to call a function of our API via the Contentsquare Cordova Plugin.

window.handleOpenURL = function (url) {
    console.log("received url: " + url);
    ContentsquarePlugin.handleURL(url);
}

To enable in-app features within your app, you have to first make sure your app is launched in the background. Then, follow the appropriate method described as follows.

• Android
• iOS

In Contentsquare, select the Mobile icon in the menu top bar and scan the QR code with your phone.

Log Visualizer is a feature integrated into the Contentsquare SDK. As you navigate and interact with your app, it provides a live view of events detected by the SDK, visible directly on the Contentsquare platform ↗.

1. Start your app.
2. Select the Mobile icon in the menu top bar then select Log Visualizer.
3. Select the device to inspect.

At this stage, you should see an ‘App start’ or ‘App show’ event being logged.

• Android
• iOS

Contentsquare collects usage data from your app users. To start tracking, you need your users’ consent for being tracked.

The SDK treats users as opted-out by default.

To start tracking, use optIn(). The optIn() API enables tracking via Contentsquare by generating a user ID and initiating tracking. This method should be called after receiving consent from the user.

For example, call optIn() when the user accepts your app’s privacy policy or tracking terms:

import React, { useState } from "react";
import { View, Text, Button } from "react-native";
import Contentsquare from "@contentsquare/react-native-bridge";

const PolicyConsentScreen = () => {
  const [isTrackingAccepted, setIsTrackingAccepted] = useState(false);

  const handleAcceptPolicy = () => {
    setIsTrackingAccepted(true);
    Contentsquare.optIn(); // Opt-in for CS Tracking
  };

  return (
    <View>
      <Text>Please accept our privacy policy to proceed.</Text>
      <Button title="Accept Policy" onPress={handleAcceptPolicy} />
    </View>
  );
};

export default PolicyConsentScreen;

Contentsquare aggregates the user behavior and engagement at the screen level. Start your SDK implementation by tracking key screens like the home screen, product list, product details, or conversion funnel.

Screen tracking is achieved by sending a screenview event each time a new screen is displayed on the user’s device.

import { ContentsquareCDVPlugin } from '@contentsquare/cordova-plugin-types';

declare var ContentsquarePlugin: ContentsquareCDVPlugin;

ContentsquarePlugin.sendScreenName("ScreenName", (result)=>{
    // Success
}, (err)=>{
    // Handle error
});

From a functional perspective, a screenview should be triggered in the following cases:

• When the screen appears on the device
• When a modal or pop-up is displayed
• When a modal or pop-up is closed, returning the user to the screen
• When the app is brought back to the foreground (after being minimized)

It is necessary to provide a name for each screen when calling the screenview API.

As a general rule, keep distinct screen names under 100. As they are used to map your app in Contentsquare, you will want something comprehensive. The screen name length is not limited on the SDK side. However, the limit is 2083 characters on the server side.

More on screen name handling.

Testing your SDK implementation is essential to make sure data is being accurately captured and reported.

To test your setup, simulate user interactions in your app and check that the events are logged correctly in our analytics platform.

You can also use debugging tools such as Android Studio, Xcode, or Log Visualizer to monitor data transmission and ensure everything is running smoothly.

Use Log Visualizer to view incoming events within the Contentsquare pipeline. This allows you to monitor the stream in real time.

By simulating user activity, you see incoming screenview and gesture events.

• Android
• iOS

Open Journey Analysis ↗ in Contentsquare and visualize the user journeys main steps across your app, screen by screen.

See how to use Journey Analysis on the Help Center ↗.

Open Session Replay ↗ in Contentsquare and replay the full user session across your app.

See how to use Session Replay on the Help Center ↗

To explore some of these features in context, check our Cordova sample apps.

While screen tracking gives an overview of user navigation, capturing session, screen, or user metadata provides a deeper understanding of the context behind user behavior.

Our SDK offers a wide range of features to enhance your implementation, including Session Replay, Error Monitoring, extended tracking capabilities, and personal data masking.

Proceed with these how-to’s to refine your implementation.