SDK API reference

Get user consent.
Calling this API generates a user ID and initiates tracking.

Call optIn after start.

CSQ.optIn(Context)

CSQ.optIn(Context);

• Context   object  

  Android Context object ↗

Revoke user consent, remove stored userId.
Stop CSQ SDK, flush, and clear all data.

CSQ.optOut()

CSQ.optOut();

• Context   object  

  Android Context object ↗

Assigns an identity to be associated with the current user.

This assigns the identity to all events for the user ID and lets the analysis module merge multiple user IDs with the same identity.

CSQ.identify(identity: String)

CSQ.identify(String identity);

• identity   String (<= 100 chars)  

  Identity to be associated with the current user.

If the user was previously identified with identify(), this creates a new unidentified user and session. This is technically equivalent to calling optOut() then optIn().

CSQ.resetIdentity()

CSQ.resetIdentity();

No parameters.

Get all information relative to the user.

CSQ.metadata.userId;

CSQ.metadata.getUserId();

CSQ.metadata.sessionId

CSQ.metadata.getSessionId();

CSQ.metadata.projectId

CSQ.metadata.getProjectId();

CSQ.metadata.environmentId;

CSQ.metadata.getEnvironmentId();

CSQ.metadata.sessionReplayUrl

CSQ.metadata.getSessionReplayUrl();

Trigger a callback whenever user information is updated.

CSQ.metadata.onChanged { metadata ->
    // Handle information change
}

CSQ.metadata.setOnChanged(new new OnMetadataChanged() {
    @Override
    public void invoke(@NonNull Metadata metadata) {
        // Handle information change
    }
});

• onMetadataChanged   OnMetadataChanged  

  Callback triggered each time a metadata data change.

Sets the current log level.

CSQ.debug.logLevel = loglevel

CSQ.debug.setLogLevel(level);

• level   Enum (CSQ.Log.Level)  

  Possible values: none, trace, debug, info, warn or error.

Add a LogChannel to which send log messages.

CSQ.debug.logChannel = channel

CSQ.debug.setLogChannel(channel);

• LogChannel   interface  

  The interface where log messages will be routed.

Routes SDK logs to another location such as Timber, Arbor, or similar logging libraries. The default implementation routes all logs through Logcat.

LogChannel.printLog()

LogChannel.printLog();

No parameters.

Experience Analytics | Added in: 1.0.0

Adds one or multiple dynamic variables to the session properties. This method allows you to pass a DynamicVar object, representing a key-value pair that is scoped to the session.

val var1 = DynamicVar("key1", "value1")
val var2 = DynamicVar("key2", 10L)
CSQ.addDynamicVar(var1)
CSQ.addDynamicVar(var2)

DynamicVar var1 = new DynamicVar("key1", "value1");
DynamicVar var2 = new DynamicVar("key2", 10L);
CSQ.addDynamicVar(var1);
CSQ.addDynamicVar(var2);

• DynamicVar   object  

  The dynamic variable

  key   String (<= 512 chars)  

  Dynamic variable key

  value   String/Long  

  Dynamic variable value

Product Analytics | Added in: 1.0.0

Add a collection of properties to be associated with the current user.

CSQ.addUserProperties(properties: Map<String, Any>)

CSQ.addUserProperties(Map<String, Object> properties);

• properties   Map<String, Any>  

  A map of user properties.

Product Analytics | Added in: 1.0.0

Add a collection of properties to be associated with all future events.

CSQ.addEventProperties(properties: Map<String, Any>)

CSQ.addEventProperties(Map<String, Object> properties);

• properties   Map<String, Any>  

  A map of event properties.

  key   String  

  the UserProperty key

  value   Any  

  values can be any combination of any Number, Boolean, String or Java/Kotlin object that implements Property

Product Analytics | Added in: 1.0.0

Removes a single property from the collection of event-wide properties.

CSQ.removeEventProperty(property: String)

CSQ.removeEventProperty(String property);

• property   String  

  The key of the property to remove.

Product Analytics | Added in: 1.0.0

Removes all event-wide properties.

CSQ.clearEventProperties()

CSQ.clearEventProperties();

Experience Analytics | Added in: 1.0.0

Exclude a scrollable view or subclass from Exposure Metric computations.

CSQ.excludeFromExposureMetric(View)

CSQ.excludeFromExposureMetric(View);

• View   View  

  The view to exclude from exposure metrics.

Register a webview for tracking.

CSQ.registerWebView(webView)

CSQ.registerWebView(webView);

• webView   WebView  

  The webview to register for tracking.

Unregister a webview for tracking.

CSQ.unregisterWebView(webView)

CSQ.unregisterWebView(webView);

• webView   WebView  

  The webview to unregister from tracking.

Experience Analytics | Added in: 1.0.0

Send a transaction.

CSQ.trackTransaction(Transaction)

CSQ.trackTransaction(Transaction);

• Transaction   Transaction  

  The transaction object to be sent.

Send a screen view with or without custom variables.

CSQ.trackScreenview(name: String, cvars: List<CustomVar> = emptyList())

CSQ.trackScreenview(String name, List<CustomVar> cvars);

• name   String  

  The name of the screen.

• cvars   List<CustomVar> (optional)  

  A list of custom variables to attach to the screen view.

  index   Int (@IntRange(from = 0, to = 20))  

  A number identifying a CustomVar

  name   String (<= 512 chars)  

  Custom variable key

  value   String  

  Custom variable value

Product Analytics | Added in: 1.0.0

Creates an event message to be tracked and sent to the API.

CSQ.trackEvent(name: String, properties: Map<String, Any> = mapOf())

CSQ.trackEvent(String name , Map<String, Object> properties);

• name   String  

  The name of the event to be tracked.

• properties   Map<String, Any> (optional)  

  Optional properties to associate with the event.

Experience Analytics | Added in: 1.0.0

Track a gesture manually.

CSQ.trackMotionEvent(motionEvent: MotionEvent)

CSQ.trackMotionEvent(MotionEvent motionEvent);

• motionEvent   MotionEvent  

  The MotionEvent ↗ to be tracked.

Experience Analytics | Added in: 1.0.0

Helper function for Jetpack Compose to ensure only one screen view is triggered when a given screen is presented to the user.

@Composable
TriggeredOnResume(block: () -> Unit)

• block   Function  

  The block of code to run when the screen is resumed.

Experience Analytics Voice of Customer | Added in: 1.0.0

Triggers a survey by referencing a predefined trigger name.

This method allows your mobile app to trigger surveys at specific moments in the user journey. Triggers act as flexible placeholders that are not bound to individual surveys, enabling your business team to assign or update surveys later without requiring code changes.

CSQ.triggerSurvey(triggerName: String)

CSQ.triggerSurvey(String triggerName);

• triggerName   String  

  The name of the trigger associated with the survey. This should match the trigger name configured in the Contentsquare platform.

// Trigger a survey after a purchase is completed
CSQ.triggerSurvey("purchase-complete")

// Trigger a survey after a purchase is completed
CSQ.triggerSurvey("purchase-complete");

Experience Analytics | Added in: 1.0.0

Sets URL masking patterns.

CSQ.setUrlMaskingPatterns(patterns: List<String>)

CSQ.setUrlMaskingPatterns(List<String> patterns);

• patterns   List<String>  

  A list of URL patterns to mask.

Experience Analytics | Added in: 1.0.0

Track network metrics.

CSQ.trackNetworkMetric(networkMetric: NetworkMetric)

CSQ.trackNetworkMetric(NetworkMetric networkMetric);

• networkMetric   NetworkMetric  

  The network metric to be tracked.

Ignore interactions for a specific view.

CSQ.ignoreInteractions(view: View)

CSQ.ignoreInteractions(View view);

Kotlin extension function to ignore interactions for a specific view.

View.csqIgnoreInteractions()

Jetpack Compose composable function to ignore interactions for a specific view.

@Composable
fun CsqIgnoreInteraction(ignore: Boolean, block: @Composable () -> Unit)

• ignore   Boolean  

  indicating whether interactions should be ignored or not

• block   @Composable () -> Unit  

  composable lambda function representing the UI content to apply ignore condition

Experience Analytics | Added in: 1.0.0

Set the default masking state.
All Android View elements, their subclasses and Jetpack Compose components are fully masked by default.

CSQ.setDefaultMasking(masked: Boolean)

CSQ.setDefaultMasking(Boolean masked);

• masked   Boolean  

  The masking state to be set.

Mask a view’s content.

CSQ.mask(view: View)

CSQ.mask(View view);

• View   View  

  The view which content will be masked.

Kotlin extension function to mask the content of a view.

View.csqMaskContents(enable: Boolean)

• enable   Boolean  

  Whether to mask the content of the view.

Jetpack Compose composable function that applies masking to Compose UI content This will mask both Session Replay and analytics event..

@Composable
CsqMask(enable: Boolean, block: @Composable () -> Unit)

• enable   Boolean  

  Whether to mask the content of the view.

• block   @Composable () -> Unit  

  composable lambda function representing the content to apply masking condition

Unmask a view’s content.

CSQ.unmask(view: View)

CSQ.unmask(View view);

• View   View  

  The view whose content will be unmasked.

Experience Analytics | Added in: 1.0.0

Mask content for views of a specific type.

CSQ.mask(type: Class<*>)

CSQ.mask(Class<?> type);

• type   Class<?>  

  The class type of the view whose content will be masked.

Experience Analytics | Added in: 1.0.0

Unmask content for views of a specific type.

CSQ.unmask(type: Class<*>)

CSQ.unmask(Class<?> type);

• type   Class<?>  

  The class type of the view whose content will be unmasked.

Mask text input fields.

CSQ.maskTexts(mask: Boolean)

CSQ.maskTexts(Boolean mask);

• mask   Boolean  

  Whether to mask text.

Product Analytics | Added in: 1.0.0

Product Analytics is configured using this method. Must be called before the start of the SDK.

CSQ.configureProductAnalytics(
  context = this,
  envId = "YOUR_ENVIRONMENT_ID",
  options = ProductAnalyticsOptions(
    uploadInterval = 5.0,
    baseUri = URI.create("https://example.com/"),
    captureVendorId = true,
    captureAdvertiserId = false,
    clearEventPropertiesOnNewUser = false,
    disablePageviewAutocapture = false,
    enableViewAutocapture = true,
    enablePushNotificationAutocapture = true,
    enablePushNotificationTitleAutocapture = true,
    enablePushNotificationBodyAutocapture = false,
    maximumDatabaseSize = 10000000L,
    messageBatchMessageLimit = 100,
    maximumBatchCountPerUpload = 5,
    resumePreviousSession = true,
    pruningLookBackWindow = 6,
    disableScreenviewForwardToDXA = false,
    disableScreenviewForwardToPA = false
  )
)

ProductAnalyticsOptions options = new ProductAnalyticsOptions.Builder()
  .uploadInterval(5.0)
  .baseUri(URI.create("https://example.com/"))
  .captureVendorId(true)
  .captureAdvertiserId(false)
  .clearEventPropertiesOnNewUser(false)
  .disablePageviewAutocapture(false)
  .enableViewAutocapture(true)
  .enablePushNotificationAutocapture(true)
  .enablePushNotificationTitleAutocapture(true)
  .enablePushNotificationBodyAutocapture(false)
  .maximumDatabaseSize(10000000L)
  .messageBatchMessageLimit(100)
  .maximumBatchCountPerUpload(5)
  .resumePreviousSession(true)
  .pruningLookBackWindow(6)
  .disableScreenviewForwardToDXA(false)
  .disableScreenviewForwardToPA(false)
  .build();

CSQ.configureProductAnalytics(this, "YOUR_ENVIRONMENT_ID", false, options);

• context   Context  

  Android Context object ↗

• envId   string  

  Your Product Analytics environment ID.

• ProductAnalyticsOptions()    

  Product Analytics initialization options.

Manually start the SDK.

CSQ.start(context)

CSQ.start(context);

• context   Context  

  Android Context object ↗

Stop all activity from the SDK.
Once run no requests, telemetry collection, or logs will be generated.

CSQ.stop()

CSQ.stop();

Pause all tracking features.

CSQ.pauseTracking()

CSQ.pauseTracking();

Resume all tracking features.

CSQ.resumeTracking()

CSQ.resumeTracking();

CSQ SDK options for Product Analytics passed to CSQ.configureProductAnalytics().

CSQ.configureProductAnalytics(
  envId = "YOUR_ENVIRONMENT_ID",
  options = ProductAnalyticsOptions(
    uploadInterval = 5.0,
    baseUri = URI.create("https://example.com/"),
    captureVendorId = true,
    captureAdvertiserId = false,
    clearEventPropertiesOnNewUser = false,
    disablePageviewAutocapture = false,
    enableViewAutocapture = true,
    enablePushNotificationAutocapture = true,
    enablePushNotificationTitleAutocapture = true,
    enablePushNotificationBodyAutocapture = false,
    maximumDatabaseSize = 10000000L,
    messageBatchMessageLimit = 100,
    maximumBatchCountPerUpload = 5,
    resumePreviousSession = true,
    pruningLookBackWindow = 6,
    disableScreenviewForwardToDXA = false,
    disableScreenviewForwardToPA = false
  )
)

ProductAnalyticsOptions options = new ProductAnalyticsOptions.Builder()
  .uploadInterval(5.0)
  .baseUri(URI.create("https://example.com/"))
  .captureVendorId(true)
  .captureAdvertiserId(false)
  .clearEventPropertiesOnNewUser(false)
  .disablePageviewAutocapture(false)
  .enableViewAutocapture(true)
  .enablePushNotificationAutocapture(true)
  .enablePushNotificationTitleAutocapture(true)
  .enablePushNotificationBodyAutocapture(false)
  .maximumDatabaseSize(10000000L)
  .messageBatchMessageLimit(100)
  .maximumBatchCountPerUpload(5)
  .resumePreviousSession(true)
  .pruningLookBackWindow(6)
  .disableScreenviewForwardToDXA(false)
  .disableScreenviewForwardToPA(false)
  .build();

CSQ.configureProductAnalytics(this, "YOUR_ENVIRONMENT_ID", false, options);

Product Analytics Environment ID.

Interval at which event batches should be uploaded to the API. Defaults to 15 seconds.

URI object specifying the base URI for the desired API endpoint. The Heap SDK resolves paths using this base URI and ignores any pre-existing path elements.

Whether or not the vendor ID should be included in tracked events if made available by the device. Defaults to false.

Whether or not the advertiser ID should be included in tracked events if made available by the device. Defaults to false.

Whether or not to clear event properties when a new user is created. Defaults to false.

Whether or not source pageview events will be auto-captured. Defaults to false.

Whether or not the SDK will auto captureUI interactions and source pageviews. Only for Android View system, no Compose support. Defaults to false.

Whether or not the SDK will auto capture interaction events on notifications. Defaults to false.

Whether or not capture the title of the notification where an interaction was performed. enablePushNotificationAutocapture must be to true. Defaults to false.

Whether or not capture the body text of the notification where an interaction was performed. enablePushNotificationAutocapture must be to true. Defaults to false.

The maximum size, in bytes, to allocate for the local event storage database. Defaults to -1, meaning there is no limit on database size. Must be greater than or equal to 200KB.

The maximum number of messages to be included in each batch sent to Heap. Setting a lower limit can help reduce network traffic in situations where bandwidth is limited. Defaults to 100.

The maximum number of batches to send per upload cycle. This can be used in conjunction with messageBatchMessageLimit to control the amount of data that is uploaded in a given cycle.

Enables Contentsquare behavior of persisting non-expired sessions across app launch.

The number of days to look back when pruning old data in days. Defaults to 6 days. Requires an entitlement to use.

Instead of starting a new session with a new user, metadata can be passed in to specify initial metadata. Doing this causes all session expiration logic to be suspended. Defaults to null. Requires an entitlement to use.

Disable forwarding of Product Analytics Pageviews to Experience Analytics.

Disable forwarding of Experience Analytics Screenviews to Product Analytics.