Intempt Android SDK API Documentation

Overview

Intempt Android SDK is a Kotlin SDK for tracking user events, managing user identification, and handling consent management in Android applications. This document describes all public methods available in the Intempt object.

Initialization

`initialize(context: Context)`

Initializes the Intempt SDK with the application context. This method must be called before using any other SDK methods, typically in your Application class's onCreate() method.

Parameters:

Parameter	Type	Required	Description
`context`	`Context`	Yes	Application context

Example:

Configuration:

The SDK requires a configuration file intempt-config.json in your assets folder with the following structure:

{
    "auth": {
        "INTEMPT_API_KEY": "username.password",
        "INTEMPT_SOURCE_ID": "your-source-id",
        "INTEMPT_ORGANIZATION_ID": "your-organization-id",
        "INTEMPT_PROJECT_ID": "your-project-id"
    },
    "options": {
        "isLoggingEnabled": false,
        "isTouchEnabled": true,
        "isTextCaptureEnabled": true,
        "isQueueEnabled": true,
        "isAutoCaptureEnabled": true,
        "itemsInQueue": 5,
        "timeBuffer": 5000
    }
}

Configuration Options:

Option	Type	Default	Description
`isLoggingEnabled`	`Boolean`	`false`	Enable SDK logging
`isTouchEnabled`	`Boolean`	`true`	Enable automatic touch event tracking
`isTextCaptureEnabled`	`Boolean`	`true`	Enable automatic text capture
`isQueueEnabled`	`Boolean`	`true`	Enable event queuing
`isAutoCaptureEnabled`	`Boolean`	`true`	Enable automatic event capture
`itemsInQueue`	`Int`	`5`	Number of events to queue before sending
`timeBuffer`	`Long`	`5000`	Time buffer in milliseconds for event batching

Note: If initialization fails, an error message will be printed to the console, but the app will continue to run.

User Tracking Control Methods

`Tracking.start()`

Enables tracking for the current user.

Returns: void

Example:

`Tracking.stop()`

Disables tracking for the current user.

Returns: void

Example:

`Tracking.isTrackingEnabled()`

Checks if the user has opted in to tracking.

Returns: Boolean - true if tracking is enabled, false otherwise

Example:

Logging Control Methods

`Logging.start()`

Enables SDK logging.

Returns: void

Example:

`Logging.stop()`

Disables SDK logging.

Returns: void

Example:

`Logging.isLoggingEnabled()`

Checks if logging is currently enabled.

Returns: Boolean - true if logging is enabled, false otherwise

Example:

User Identification Methods

`identify(userId: String, eventTitle: String? = null, userAttributes: Map<String, String>? = null, data: Map<String, String>? = null)`

Identifies a user and associates them with a user ID. This method is used to link user actions to a specific user identity.

Parameters:

Parameter	Type	Required	Description
`userId`	`String`	Yes	Unique identifier for the user
`eventTitle`	`String?`	No	Custom event title (default: "Identify")
`userAttributes`	`Map<String, String>?`	No	User attributes map (requires `eventTitle` if provided)
`data`	`Map<String, String>?`	No	Additional event data

Returns: void

Validation:

userId must not be empty

If userAttributes is provided, eventTitle must also be provided

Forbidden event titles: "auto-track", "view page", "leave page", "change on", "click on", "submit on", "identify", "consent"

Example:

`alias(userId: String, anotherUserId: String)`

Creates an alias between two user IDs. Used when a user is identified with different IDs (e.g., anonymous ID and authenticated ID).

Parameters:

Parameter	Type	Required	Description
`userId`	`String`	Yes	Primary user ID
`anotherUserId`	`String`	Yes	Secondary user ID to alias

Returns: void

Example:

Group/Account Methods

`group(accountId: String, eventTitle: String? = null, accountAttributes: Map<String, String>? = null)`

Associates a user with a group or account.

Parameters:

Parameter	Type	Required	Description
`accountId`	`String`	Yes	Unique identifier for the account/group
`eventTitle`	`String?`	No	Custom event title (default: "Identify")
`accountAttributes`	`Map<String, String>?`	No	Account attributes map (requires `eventTitle` if provided)

Returns: void

Validation:

accountId must not be empty

If accountAttributes is provided, eventTitle must also be provided

Forbidden event titles: same as identify method

Example:

Event Tracking Methods

`track(eventTitle: String, data: Map<String, String>)`

Tracks a custom event with associated data.

Parameters:

Parameter	Type	Required	Description
`eventTitle`	`String`	Yes	Name of the event
`data`	`Map<String, String>`	Yes	Event data map (must not be empty)

Returns: void

Validation:

eventTitle is required and must not be empty

data must be provided and non-empty

Forbidden event titles: same as identify method

Example:

`record(eventTitle: String, accountId: String? = null, userId: String? = null, accountAttributes: Map<String, String>? = null, userAttributes: Map<String, String>? = null, data: Map<String, String>? = null)`

Records an event with optional user and account information.

Parameters:

Parameter	Type	Required	Description
`eventTitle`	`String`	Yes	Name of the event
`accountId`	`String?`	No	Account identifier
`userId`	`String?`	No	User identifier
`accountAttributes`	`Map<String, String>?`	No	Account attributes
`userAttributes`	`Map<String, String>?`	No	User attributes
`data`	`Map<String, String>?`	No	Additional event data

Returns: void

Validation:

eventTitle is required

Forbidden event titles: same as identify method

Example:

`consent(action: String, validUntil: Long, email: String? = null, message: String? = null, category: String? = null)`

Records user consent preferences.

Parameters:

Parameter	Type	Required	Description
`action`	`String`	Yes	Consent action (`"accept"` or `"reject"`)
`validUntil`	`Long`	Yes	Timestamp when consent expires (Unix timestamp in milliseconds)
`email`	`String?`	No	User email address
`message`	`String?`	No	Consent message
`category`	`String?`	No	Consent category

Returns: void

Validation:

action must be either "accept" or "reject"

validUntil is required (Unix timestamp in milliseconds)

Example:

Product Tracking Methods

`productAdd(productId: String, quantity: Int)`

Tracks when a product is added to cart.

Parameters:

Parameter	Type	Required	Description
`productId`	`String`	Yes	Product identifier
`quantity`	`Int`	Yes	Quantity added

Returns: void

Example:

Event Title: "Added to cart"

`productOrdered(products: List<Map<String, Any>>)`

Tracks when products are ordered (purchased).

Parameters:

Parameter	Type	Required	Description
`products`	`List<Map<String, Any>>`	Yes	List of product maps, each containing `productId` (String) and `quantity` (Int)

Returns: void

Validation:

Each product map must contain:

productId: String (required, non-empty)

quantity: Int (required, must be > 0)

Example:

Event Title: "Product ordered"

`productView(productId: String)`

Tracks when a product is viewed.

Parameters:

Parameter	Type	Required	Description
`productId`	`String`	Yes	Product identifier

Returns: void

Example:

Event Title: "Product viewed"

Session Management

`logOut()`

Handles user logout by clearing session data and refreshing the auto tracker.

Returns: void

Example:

Note: This method only executes if the user has opted in to tracking. The profile ID is preserved after logout.

Recommendation API

`recommendation(id: String, quantity: Int, fields: List<String>, productId: String?): JsonObject?`

Fetches product recommendations from the Intempt API. This is a suspend function and must be called from a coroutine.

Parameters:

Parameter	Type	Required	Description
`id`	`String`	Yes	Feed ID for recommendations
`quantity`	`Int`	Yes	Number of recommendations to return
`fields`	`List<String>`	Yes	Fields to include in the response
`productId`	`String?`	No	Optional product ID for context

Returns: JsonObject? - Recommendation data or null on error

Example:

API Details:

Endpoint: {api}/{organization}/projects/{project}/feeds/{id}/data

Method: POST

Authentication: Basic Auth (derived from API key in config)

Error Handling:

Returns null if the request fails

Errors are logged if logging is enabled

Experiments and Personalization

`experiment: ModificationProvider`

Provides access to server-side experiments. Use this to fetch experiment variations.

Methods:

`getByGroup(data: List<String>): JsonElement?` (suspend)

Fetches experiments by group names.

Example:

`getByName(data: List<String>): JsonElement?` (suspend)

Fetches experiments by experiment names.

Example:

`getByGroupAsync(data: List<String>): CompletableFuture<JsonElement?>`

Asynchronous version of getByGroup for Java interop.

`getByNameAsync(data: List<String>): CompletableFuture<JsonElement?>`

Asynchronous version of getByName for Java interop.

`personalization: ModificationProvider`

Provides access to server-side personalization campaigns. Use this to fetch personalized content.

Methods:

Same as experiment - getByGroup, getByName, getByGroupAsync, getByNameAsync.

Example:

Privacy and Data Capture

`doNotCaptureText(view: View)`

Marks a view to exclude its text content from automatic capture. This is useful for sensitive data like passwords or personal information.

Parameters:

Parameter	Type	Required	Description
`view`	`View`	Yes	View to exclude from text capture

Returns: void

Supported View Types:

EditText

Spinner

ToggleButton

CheckBox

RadioButton

CompoundButton

TextView

SeekBar

RatingBar

TimePicker

DatePicker

ListView

Example:

Note: If an unsupported view type is passed, an error will be logged.

Common Behavior

Opt-In Requirement

Most tracking methods (identify, group, track, record, alias, consent, productAdd, productOrdered, productView, logOut) will silently return without executing if the user has opted out of tracking. Use Tracking.isTrackingEnabled() to check the current status.

Automatic IDs

The following IDs are automatically included in all tracking events:

profileId: Generated/retrieved from storage

sessionId: Current session identifier

pageId: Current page identifier

Automatic Event Capture

The SDK automatically captures:

Screen views (Activity lifecycle events)

Touch events (clicks, taps)

Form changes (text input changes)

Fragment transitions

App install/upgrade events

Session start events

This behavior can be controlled via configuration options in intempt-config.json.

Forbidden Event Titles

The following event titles are forbidden and will cause validation errors:

"auto-track"

"view page"

"leave page"

"change on"

"click on"

"submit on"

"identify"

"consent"

Error Handling

All validation errors are logged using the SDK's logging system. Common errors include:

Configuration errors: Missing or invalid configuration file

Parameter validation errors: Missing required parameters or invalid values

Field-specific errors: Specific field validation failures

Forbidden event titles: Attempting to use reserved event titles

Errors are logged but do not throw exceptions, allowing your app to continue running. Enable logging with Intempt.Logging.start() to see error messages.

Best Practices

Initialize early: Call Intempt.initialize() in your Application.onCreate() method before any other SDK calls.

Check tracking status: Before tracking, check if the user has opted in:

Use coroutines for async operations: Methods like recommendation() and modification providers are suspend functions. Use coroutines:

Protect sensitive data: Use doNotCaptureText() for views containing sensitive information like passwords or credit card numbers.

Configure appropriately: Set up your intempt-config.json file with appropriate options for your use case.

Respect user consent: Always respect user consent preferences and use the consent() method to record consent decisions.

Handle null results: Async methods like recommendation() and modification providers can return null on error. Always check for null before using results.

Type Definitions

Configuration File Structure

{
    "auth": {
        "INTEMPT_API_KEY": "string",      // Format: "username.password"
        "INTEMPT_SOURCE_ID": "string",
        "INTEMPT_ORGANIZATION_ID": "string",
        "INTEMPT_PROJECT_ID": "string"
    },
    "options": {
        "isLoggingEnabled": boolean,
        "isTouchEnabled": boolean,
        "isTextCaptureEnabled": boolean,
        "isQueueEnabled": boolean,
        "isAutoCaptureEnabled": boolean,
        "itemsInQueue": number,
        "timeBuffer": number
    }
}

ModificationProvider Interface

Version Information

SDK Version: See BuildConfig.sdkVersion in your build

Documentation Version: 1.0.0

Last Updated: 2024

Additional Resources

Android SDK Documentation

Intempt Platform

Android SDK

Intempt Android SDK API Documentation#

Overview#

Initialization#

initialize(context: Context)#

User Tracking Control Methods#

Tracking.start()#

Tracking.stop()#

Tracking.isTrackingEnabled()#

Logging Control Methods#

Logging.start()#

Logging.stop()#

Logging.isLoggingEnabled()#

User Identification Methods#

identify(userId: String, eventTitle: String? = null, userAttributes: Map<String, String>? = null, data: Map<String, String>? = null)#

alias(userId: String, anotherUserId: String)#

Group/Account Methods#

group(accountId: String, eventTitle: String? = null, accountAttributes: Map<String, String>? = null)#

Event Tracking Methods#

track(eventTitle: String, data: Map<String, String>)#

record(eventTitle: String, accountId: String? = null, userId: String? = null, accountAttributes: Map<String, String>? = null, userAttributes: Map<String, String>? = null, data: Map<String, String>? = null)#

Consent Management#

consent(action: String, validUntil: Long, email: String? = null, message: String? = null, category: String? = null)#

Product Tracking Methods#

productAdd(productId: String, quantity: Int)#

productOrdered(products: List<Map<String, Any>>)#

productView(productId: String)#

Session Management#

logOut()#

Recommendation API#

recommendation(id: String, quantity: Int, fields: List<String>, productId: String?): JsonObject?#

Experiments and Personalization#

experiment: ModificationProvider#

getByGroup(data: List<String>): JsonElement? (suspend)#

getByName(data: List<String>): JsonElement? (suspend)#

getByGroupAsync(data: List<String>): CompletableFuture<JsonElement?>#

getByNameAsync(data: List<String>): CompletableFuture<JsonElement?>#

personalization: ModificationProvider#

Privacy and Data Capture#

doNotCaptureText(view: View)#

Common Behavior#

Opt-In Requirement#

Automatic IDs#

Automatic Event Capture#

Forbidden Event Titles#

Error Handling#

Best Practices#

Type Definitions#

Configuration File Structure#

ModificationProvider Interface#

Version Information#

Additional Resources#

Intempt Android SDK API Documentation

Overview

Initialization

`initialize(context: Context)`

User Tracking Control Methods

`Tracking.start()`

`Tracking.stop()`

`Tracking.isTrackingEnabled()`

Logging Control Methods

`Logging.start()`

`Logging.stop()`

`Logging.isLoggingEnabled()`

User Identification Methods

`identify(userId: String, eventTitle: String? = null, userAttributes: Map<String, String>? = null, data: Map<String, String>? = null)`

`alias(userId: String, anotherUserId: String)`

Group/Account Methods

`group(accountId: String, eventTitle: String? = null, accountAttributes: Map<String, String>? = null)`

Event Tracking Methods

`track(eventTitle: String, data: Map<String, String>)`

`record(eventTitle: String, accountId: String? = null, userId: String? = null, accountAttributes: Map<String, String>? = null, userAttributes: Map<String, String>? = null, data: Map<String, String>? = null)`

Consent Management

`consent(action: String, validUntil: Long, email: String? = null, message: String? = null, category: String? = null)`

Product Tracking Methods

`productAdd(productId: String, quantity: Int)`

`productOrdered(products: List<Map<String, Any>>)`

`productView(productId: String)`

Session Management

`logOut()`

Recommendation API

`recommendation(id: String, quantity: Int, fields: List<String>, productId: String?): JsonObject?`

Experiments and Personalization

`experiment: ModificationProvider`

`getByGroup(data: List<String>): JsonElement?` (suspend)

`getByName(data: List<String>): JsonElement?` (suspend)

`getByGroupAsync(data: List<String>): CompletableFuture<JsonElement?>`

`getByNameAsync(data: List<String>): CompletableFuture<JsonElement?>`

`personalization: ModificationProvider`

Privacy and Data Capture

`doNotCaptureText(view: View)`

Common Behavior

Opt-In Requirement

Automatic IDs

Automatic Event Capture

Forbidden Event Titles

Error Handling

Best Practices

Type Definitions

Configuration File Structure

ModificationProvider Interface

Version Information

Additional Resources