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
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
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:
Some recording parameters can be configured on setup:
|apiKey||yes||Unique 40-character key identifying your app (can be found in the dashboard).||""|
|fps||no||Recorded video frame rate (allowed values between 2 and 10). Note that by setting this value settings from the dashboard will be overridden!||2|
|experimental||no||If set to true it enables some experimental features such as TextureView/Maps/MapBox recording, etc.||false|
|activity||no||Actual activity reference is required when setting the SDK outside of the Application class.||null|
|renderingMode||no||Defines the way SDK is going to capture screen image data.||RenderingMode.NATIVE|
|renderingModeOption||no||Further customization of the rendering mode.||null|
|eventTrackingModes||no||Event tracking modes can be used to disable some automatically detected events.||EventTrackingMode.FULL_TRACKING|
|useAdaptiveFramerate||no||Adaptive 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(builder.build()) so the recording can be started later.
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 currently recording can be handy when using
stopRecording() methods. Simply call:
Check if SDK is currently recording can be handy when using
stopRecording() methods. Simply call:
Current session can be ended and a new session created by calling:
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:
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
Any blacklisted classes can be removed:
WebView are blacklisted by default and can be removed using
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:
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:
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.</div>
All inputs are hidden by default except for
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 identifier can be specified by calling:
Identifiers can be found in the Dashboard and are very useful for finding specific user’s recordings.
Additional user information such as
UserProperties helper class and its methods.
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
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.
A simple custom event can be created by calling:
Additional data serialized as
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:
viewState can be either
It can be explicitly specified if the navigation event happened between
viewType is one of
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:
eventId obtained from
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.
For some automatically detected events SDK tries to figure out the name from the application context:
- click event - Event name consists of
Viewclass (Button, etc.) and the
- navigation event - Event name is set as
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.
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
View class (
Button, etc.) and
Custom names for navigation events can be set in two different ways.
Fragment can implement
Fragment root view can be tagged directly in
XML layout file:
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.
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.
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_TRACKINGthis a default state. SDK tracks all automatically detected events along with all user defined events.
IGNORE_USER_INTERACTIONdisables automatically detected selector (click on a
View), focus, touch, gesture, and keyboard events.
IGNORE_NAVIGATION_INTERACTIONdisables automatically detected navigation events. User defined ones are still being sent.
IGNORE_RAGE_CLICKSdisables automatic detection and tracking of rage click events.
NO_TRACKINGno automatically detected events are tracked. Only user defined events are still tracked.
Single or a combination of event tracking modes can be set right at the SDK setup:
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.
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.
A rendering mode can be changed on SDK setup using
Or at anytime during an application run by using thew following:
Rendering modes available are following:
NO_RENDERING mode does not record any screen data, this is beneficial on screens that include sensitive data, read more.
Currently active rendering mode can be obtained by calling:
WIREFRAME rendering mode can be further configured by
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:
Currently active rendering mode option can be obtained by calling:
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:
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.
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.
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:
- 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.
Sensitive parts of request URLs can be hidden using
String is not defined explicitly the default replace
String is used.
UrlMasks can be added using
In this example SDK is intercepting a request with a URL containing a sensitive query named
The content of this sensitive query can be hidden for intercepting using
Like the above shown
UrlMask intercepted request, it will have the following URL stored:
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:
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.
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.
URL leading to the Smartlook Dashboard for a currently recorded session can be obtained like this:
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.
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.
Smartlook can be manually integrated into various analytic frameworks using our
Listener can be registered like this:
Listener can be simply unregistered:
Samples adjusted for specific analytic tools can be found in the
Automatic integrations provide a simple way of integrating Smartlook into various third-party analytic tools.
One or a list of automatic integrations can be enabled by calling:
Integrations are described in the Integrations documentation:
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.
All currently enabled integrations can be listed: