React Native





Unreal Engine



SDK Installation
SDK Conceptual
SDK API reference
API reference
SDK Cookbooks
SDK Integrations

Lifecycle & Recording

SDK setup (on application start)

Smartlook SDK setup needs to be called only once during an application’s lifetime and it should be called on application startup. There is no need to stop recording explicitly on application closure, SDK will stop itself automatically.

The best place to setup the SDK is in onCreate() method of your Application class:

SDK can be set up later than in Application class, typically when the Application is fetching an API key, please take a look here.

The easiest way of setting up the SDK is with setupAndStartRecording() method:

It will set the SDK up and also start the recording. SDK can be setup without starting the recording using the following:

Smartlook SDK needs to be initialized with an API key that can be acquired in the Smartlook Dashboard.

And then the recording can be started by calling:

Setup configuration

Some recording parameters can be configured on setup:

ParameterRequiredDescriptionDefault value
apiKeyyesUnique 40-character key identifying your app (can be found in the dashboard).""
fpsnoRecorded video frame rate (allowed values between 2 and 10). Note that by setting this value settings from the dashboard will be overridden!2
experimentalnoIf set to true it enables some experimental features such as TextureView/Maps/MapBox recording, etc.false
activitynoActual activity reference is required when setting the SDK outside of the Application class.null
renderingModenoDefines the way SDK is going to capture screen image data.RenderingMode.NATIVE
renderingModeOptionnoFurther customization of the rendering mode.null
eventTrackingModesnoEvent tracking modes can be used to disable some automatically detected events.EventTrackingMode.FULL_TRACKING
useAdaptiveFrameratenoAdaptive frame rate is an optimization that keeps the SDK from capturing redundant screenshots when the application is idle.true

Full SDK setup configuration can be done with SetupOptionsBuilder, that provides methods for setting any of the setup parameters shown above.

Last line can be replaced with Smartlook.setup( so the recording can be started later.

Start and stop recording

Recording can be started or stopped at any time, the only requirement is that the SDK is set up.

stopRecording() doesn't need to be called on application closure. Recording is stopped automatically.

Check if SDK is recording

Check if SDK is currently recording can be handy when using startRecording() and stopRecording() methods. Simply call:

Check if SDK is currently recording can be handy when using startRecording() and stopRecording() methods. Simply call:

Reset session

Current session can be ended and a new session created by calling:

If resetUser is set to true, SDK will create a new visitor during the reset. This is especially beneficial when a new user needs to be identified (typically after logout).

A new session can be created on SDK setup:

A new visitor can also be created on SDK setup:

Sensitive data hiding

When using native rendering mode, SDK can record sensitive data in your application.

In order to protect user privacy, Smartlook can be configured so that the sensitive data is not recorded.

Smartlook attempts to hide selected sensitive UI element automatically. It can be also instructed to hide or show particular UI components. Alternatively, using one of the wireframe rendering modes records screen in a schematic way, showing no user data. The last possibility is to stop screen capturing altogether by using no rendering mode.

Sensitive elements are hidden locally on the device; no sensitive data are transferred over the network and stored in the dashboard.

Any view can be hidden in the recording by marking it as a blacklisted view. A specific view can be marked as blacklisted by calling:

Or can be tagged directly in an xml layout file:

If a specific view no longer needs to be blacklisted:

A blacklisted view is hidden on recording by a single color rectangle. The color of this rectangle can be configured by calling:

This is applied for all blacklisted objects.

Sometimes it can be beneficial to blacklist all instances of a given Class that extends a View rather than blacklisting a specific View’s instances:

Any blacklisted classes can be removed:

Note that EditText and WebView are blacklisted by default and can be removed using Smartlook.unregisterBlacklistedClass().

A specific view can be whitelisted so it is recorded even if it is an instance of a blacklisted class:

Or it can be tagged as whitelisted directly in an xml layout file:

A specific view can be removed from a whitelist by calling:

No Rendering

Sometimes the whole screen consists of sensitive data. In these cases it is beneficial to not record any screen data. This can be done by switching to no rendering rendering mode:

SDK provides rendering modes that hide sensitive information by simplifying the rendered screen for recording. This can be advantageous because all user interaction is still being recorded, but all sensitive data are not rendered by design. Read more about rendering modes in conceptual documentation.

Some screens can leak sensitive data even through automatically detected touch events. More about this issue in secure custom keyboard example.

When an application is no longer displaying sensitive data, the screen rendering mode can be set back to the preferred variant:

When an application has some parts displayed using WebView and theese parts should be recorded, then the WebView recording needs to be enabled by removing WebView from the list of blacklisted classes:

If WebView is being recorded, all sensitive elements on the displayed web page should be marked as sensitive so that they are hidden. This can be done by marking sensitive HTML elements with .smartlook-hide css class:

<div class='smartlook-hide'>
This will be hidden.

All inputs are hidden by default except for button and submit types. If some hidden inputs should be recorded they can be marked with .smartlook-show css class:

<input type="text" class='smartlook-show'>

User Identification

User identifier can be specified by calling:

Identifiers can be found in the Dashboard and are very useful for finding specific user’s recordings.

User properties

Additional user information such as name, email, etc., can be set using UserProperties helper class and its methods.

Note that email or name property will be displayed in the list of visitors in the Smartlook Dashboard. Otherwise the identifier is used.

If there is no suitable helper method for specific properties, put() method can be used. This method accepts a combination of key and value.

All helper and put() methods have optional parameters immutable if set to true, the value that has been set for the key is going to be immutable. This means it cannot be set again (a new value will not override the old one).


Some analytic events are recorded out-of-box:

  • Activity/Fragment changes
  • Focus changes
  • Clicked views
  • Application crashes
  • For everything else, custom events can be used

Names of some automatically detected events can be customized.

Custom event

A simple custom event can be created by calling:

Additional data serialized as JSONObject, Bundle, String with valid json format or key/value pair can be added to a custom event:

A simple custom event can be created by using:

Event properties will effectively use only flat objects. In case an object that includes objects or arrays as a child elements is used, these elements are going to be ignored.

Screen/navigation transitions can be manually tracked by calling:

where viewState can be either ViewState.START or ViewState.STOP.

It can be explicitly specified if the navigation event happened between Activities or Fragments:

where viewType is one of ViewType.ACTIVITY or ViewType.FRAGMENT.

Timed event

Duration of any time-sensitive or long-running actions in the application can be measured using timed events. A timed event can be started by using the following:

This will not send out any events but will return a unique eventId that needs to be stored and it is then used to stop/cancel a custom timed event. To send out an event with a duration, stop needs to be called:

with corresponding eventId obtained from startTimedCustomEvent.

Properties set in start will be merged with properties set in stop/cancel. Properties from stop/cancel have a higher priority and will rewrite conflicting properties from the start.

In case a given action failed cancelTimedCustomEvent() can be called instead of stopTimedCustomEvent() it has an extra field used for the reason of any failure:

Typical use of timed event might look like this:

In this case the duration_event will have duration a property set to circa 1000ms.

Customize automatic event detection

For some automatically detected events SDK tries to figure out the name from the application context:

  • click event - Event name consists of Activity name, View class (Button, etc.) and the id.
  • navigation event - Event name is set as Activity/Fragment name.

But sometimes it's impossible to name an event with an easy to read and descriptive name. Because of this, SDK provides an option to personalize event names.

Name click events

So a detected click on a given view has a custom event name instead of an id it can be tagged directly in the XML layout file:

If View has smartlook_custom_name set, clicking on this view will trigger an event with the name consisting of Activity name, View class (Button, etc.) and smartlook_custom_name.

Name navigation events

Custom names for navigation events can be set in two different ways. Activity/Fragment can implement SmartlookNamedController interface:

Or Activity/Fragment root view can be tagged directly in XML layout file:

Global event properties

Extra properties can be attached to every event, these properties are called global event properties. Global event properties can be set by calling:

Properties set to be immutable have the highest priority and once set they cannot be overridden (only removed).

Global event properties have higher a priority so in the merging process they will override custom properties with the same key.

Remove global event properties

A global property with a given key can be removed:

Or all global event properties can be removed at once:

Global event properties are stored until they are not removed or the app is uninstalled.

Event tracking modes

It can be beneficial to disable some automatically detected events due to security or usability reasons. This can be done using event tracking modes:

  • FULL_TRACKING this a default state. SDK tracks all automatically detected events along with all user defined events.
  • IGNORE_USER_INTERACTION disables automatically detected selector (click on a View), focus, touch, gesture, and keyboard events.
  • IGNORE_NAVIGATION_INTERACTION disables automatically detected navigation events. User defined ones are still being sent.
  • IGNORE_RAGE_CLICKS disables automatic detection and tracking of rage click events.
  • NO_TRACKING no automatically detected events are tracked. Only user defined events are still tracked.

Setup with event tracking modes

Single or a combination of event tracking modes can be set right at the SDK setup:

Set event tracking modes

Single or a combination of event tracking modes can be set any time after SDK setup by using the following:

Further info about event tracking modes could be found in the Event Tracking conceptual document.

Also take a look at the pin code keyboard sample, demonstrating usage of analytic event modes.

List event tracking modes

All currently active event tracking modes can be listed by calling:


SDK can use different methods of capturing screen image data. These are called rendering modes.

Set rendering mode

A rendering mode can be changed on SDK setup using builder:

Or at anytime during an application run by using thew following:

Rendering modes available are following:

  • RenderingMode.NATIVE
  • RenderingMode.WIREFRAME
  • RenderingMode.NO_RENDERING

NO_RENDERING mode does not record any screen data, this is beneficial on screens that include sensitive data, read more.

Current rendering mode

Currently active rendering mode can be obtained by calling:

Set rendering mode option

WIREFRAME rendering mode can be further configured by renderingModeOption.

The rendering mode option can be set on setup:

Or at anytime during an application run by using the following:

Rendering mode options for WIREFRAME rendering mode are following:

  • RenderingMode.WIREFRAME
  • RenderingMode.BLUEPRINT
  • RenderingMode.ICON_BLUEPRINT

Current rendering mode option

Currently active rendering mode option can be obtained by calling:

Interactive player - BETA

Apart from video or wireframe data, SDK can also send additional data needed for the interactive player. Currently this BETA functionality is accessible via builder. Read more about this interactive player's feature in conceptual documentation.:

WebGL modes available are the following:

  • WebGLRecordingMode.WEBGL_ONLY
  • WebGLRecordingMode.WEBGL_HYBRID

WEBGL_ONLY mode does not record any screen data, similar to NO_RENDERING, however you’ll be able to inspect the app's structure in our interactive player. WEBGL_HYBRID mode sends video or wireframe data and WebGL-related data as well. read more.

Network intercepting

An application’s HTTP traffic can be tracked using the network inceptor provided by the SDK. This feature only currently available for OkHttp HTTP/REST communication library.

In case your application is using another HTTP library that allows intercepting, please feel free to submit a feature request on our github.

OkHttp interceptor

Smartlook interceptor can be added as a another NetworkInterceptor when creating a OkHttpClient like this:

Smartlook SDK will not read or send out any body data, it is reading and sending only these request metadata:

  • Request URL that can be stripped of any sensitive data -> read more.
  • Http method used for this request.
  • Request headers that can be filtered out so they do not leak any sensitive data.
  • Response headers that are filtered out so they do not leak any sensitive data.
  • Protocol negotiated by this connection.
  • Duration between request and response/failure.
  • Request status stating if the request was successful or eventually how it failed, can be one of the following:
    • Ok
    • Error
    • Abort
    • Timeout
  • Status code of http response.
  • Flag stating if response was received from the cache.

All intercepted requests can be displayed in dev tools on every recording.

Url masks

Sensitive parts of request URLs can be hidden using UrlMask:

If replaceWith String is not defined explicitly the default replace String is used.

UrlMasks can be added using SmartlookOkHttpInterceptor.Builder:

In this example SDK is intercepting a request with a URL containing a sensitive query named secret:

The content of this sensitive query can be hidden for intercepting using UrlMask:

Like the above shown UrlMask intercepted request, it will have the following URL stored:;sensitive&gt;&second=query

Sensitive headers

Intercepted headers can contain sensitive data, so they need to be filtered out by their name. This can be done using sensitiveHeaderNameRegexps, this list of sensitive header names contains these regular expressions by default:

  • ".*csrf.*"
  • ".*token.*"
  • ".*auth.*"
  • ".*key.*"
  • ".*cookie.*"

A custom list of sensitive header name regular expressions can be defined by the following:

If at least one sensitive header name regex is added, default ones (shown above) are not going to be used.

Utility methods

Install referrer

When an application is installed from the Google Play Store, Smartlook SDK automatically tracks install referrer.

A custom referrer can also be set by using the following:

Referrer value and source of installation are stored per visitor and can be viewed in the Smartlook Dashboard.

Dashboard session URL

A URL leading to the Smartlook Dashboard for a currently recorded session can be obtained like this:

If withCurrentTimestamp is set to true link it will include information about the current recording timestamp. This will ensure that the player will start playing the session at the moment when getDashboardSessionUrl was called.

This URL can be opened only by someone who has access to your dashboard. This is not a public shareable link.

Dashboard visitor URL

A URL leading to the Smartlook Dashboard for a currently recorded visitor can be obtained like this:

This URL can be opened only by someone who has access to your dashboard. This is not a public sharing link.


Manual integration

Smartlook can be manually integrated into various analytic frameworks using our IntegrationListener.

Listener can be registered like this:

Listener can be simply unregistered:

Integration samples

Samples adjusted for specific analytic tools can be found in the Integrations documentation:

Automatic integrations

Automatic integrations provide a simple way of integrating Smartlook into various third-party analytic tools.

Enable integrations

One or a list of automatic integrations can be enabled by calling:

Specific Integrations are described in the Integrations documentation:

Disable integrations

Every currently enabled Integration can be disabled:

Or all currently enabled integrations can be disabled using the following:

Smartlook SDK tries to disable automatic integration and removes "integrated" URLs from targeted analytic tools. This however is a "best effort" try and cannot be guaranteed to be successful.

List integrations

All currently enabled integrations can be listed: