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
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
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:
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 Dashboard will be overridden!||2|
|experimental||no||If set to true it enables some experimental features as TextureView/Maps/MapBox recording etc.||false|
|activity||no||Actual activity reference is required when setting the SDK outside of Application class.||null|
|renderingMode||no||Defines the way SDK is going to capture screen image data.||RenderingMode.NATIVE|
|renderingModeOption||no||Further 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(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:
Current session can be ended and new session created by calling:
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:
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
Any of blacklisted classes can be removed:
WebView are blacklisted by default and can be removed using
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:
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:
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.</div>
All input inputs are hidden by default except for
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 indetifier can be specified by calling:
Identifiers can be found in the Dashboard and are usefull 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
identifier is used.
If there is no suitable helper method for specific properties,
put() method can be used. This method accepts combination of
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.
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 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:
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. 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:
eventId obtained from
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.
For some automatically detected events SDK tries to figure out the name from application context:
- click event - Event name consists of
Viewclass (Button, etc.) and
- 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 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
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 priority so in the merging process they will override custom properties with the same key.
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_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.
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.
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.
Rendering mode can be changed on SDK setup using
Or at anytime during application run using:
Rendering modes available:
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
Rendering mode option can be set on setup:
Or at anytime during application run using:
Rendering mode options for
WIREFRAME rendering mode:
Currently active rendering mode option can be obtained by calling:
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.
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:
- 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.
Sensitive parts of request URLs can be hidden using
String in not defined explicitly the default replace
String is used.
UrlMasks can be added using
In this example SDK is intercepting request with URL containing sensitive query named
The content of sensitive query can be hidden for intercepting using
With above shown
UrlMask intercepted request will have 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:
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.
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.
URL leading to Smartlook Dashboard for currently recorded session can be obtained like this:
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.
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.
Smartlook can be manualy integrated info various analytic frameworks using our
Listener can be registered like this:
Listener can be simply unregistered:
Smartlook SDK automatic integrations into most popular frameworks are in progress.
Samples adjusted for specific analytic tools can be found in