React Native





Unreal Engine



SDK Installation
SDK Conceptual
SDK API reference
API reference
SDK Cookbooks
SDK Integrations
REST API (beta)

Lifecycle & recording

SDK setup (on application start)

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

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

SDK can be setup later than in Application class, typically when the Application is fetching 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:

Smartlook SDK needs to be intialized with 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 Dashboard will be overridden!2
experimentalnoIf set to true it enables some experimental features as TextureView/Maps/MapBox recording etc.false
activitynoActual activity reference is required when setting the SDK outside of Application class.null
renderingModenoDefines the way SDK is going to capture screen image data.RenderingMode.NATIVE
renderingModeOptionnoFurther customization of rendering mode.null

Full SDK setup configuration can be done with SetupOptionsBuilder, that provides methods for settting 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:

Reset session

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

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

New session can be created on SDK setup:

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. Recording can be configured with methods listed below so sensitive data is not recorded, or Wireframe rendering mode can be set beacause it does not record sensitive data by design.

Sensitive elements are hidden locally on the device, no sentive data is transfered over network and stored in dashboard.

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

Or can be tagged directly in xml layout file:

If view no longer needs to be blacklisted:

Blacklisted view is hidden on recording by single color rectangle. 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 given Class that extends View rather than blacklisting specific View instances:

Any of blacklisted classes can be removed:

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

View can be whitelisted so it is recorded even if it is instance of a blacklisted class:

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

View can be removed from whitelist by calling:

No Rendering

Sometimes the whole screen consists of sensitive data in theese 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 beaing recorde, 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 application is no longer displaying sensitive screen rendering mode can be set back to preferred variant:

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

If WebView is being recorded all sensitive elements on the displayed web page should be marked as sensitive so the are 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 input inputs are hidden by default except for button and submit types. If some hidden inputs should to be recorded they can be marked with .smartlook-show css class:

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

User Identification

User indetifier can be specified by calling:

Identifiers can be found in the Dashboard and are usefull 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 identifier is used.

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

All helper and put() method have optional parameter 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 (new value will not overrride 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

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 custom event:

Event properties will effectively use only flat object. In case 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. Timed event can started using:

This will not send out any events but returns a unique eventId that needs to be stored and its used to stop/cancel custom timed event. To send out event with 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 higher priority and will rewrite conflicting properties from start.

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

Typical use of timed event might look like this:

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

Customize automatic event detection

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

  • click event - Event name consists of Activity name, View class (Button, etc.) and 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 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 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 priority so in the merging process they will override custom properties with the same key.

Remove global event properties

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.

Set event tracking modes

Single or combination of event tracking modes can be set using:

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

Also take a look at 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

Rendering mode can be changed on SDK setup using builder:

Or at anytime during application run using:

Rendering modes available:

  • 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.

Rendering mode option can be set on setup:

Or at anytime during application run using:

Rendering mode options for WIREFRAME rendering mode:

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

Current rendering mode option

Currently active rendering mode option can be obtained by calling:

Network intercepting

Applications HTTP traffic can be tracked using the network inceptor provided by the SDK. This feature is available is curently available only for OkHttp HTTP/REST communication library.

In case your applications 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:
    • Ok
    • Error
    • Abort
    • Timeout
  • Status code of http response.
  • Flag stating if response was received from 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 in not defined explicitly the default replace String is used.

UrlMasks can be added using SmartlookOkHttpInterceptor.Builder:

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

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

With above shown UrlMask intercepted request will have 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.*"

Custom list of sensitive header name regular expressions can be defined:

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

Utility methods

Instal referrer

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

Custom referrer can be also set using:

Referrer value and source of installation is stored per visitor and can be viewed in Dashboard.

Dashboard session URL

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

If withCurrentTimestamp is set to true link will include information about 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

URL leading to Smartlook Dashboard for 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 manualy integrated info various analytic frameworks using our IntegrationListener.

Listener can be registered like this:

Listener can be simply unregistered:

Automatic integrations

Smartlook SDK automatic integrations into most popular frameworks are in progress.

Integration samples

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