Help centerWeb SDKIntegrationsRest API
API Reference
Go to Smartlook

Analytics

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:

Smartlook.trackCustomEvent(eventName: String)

Smartlook.trackCustomEvent(@NonNull String eventName);

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

Smartlook.trackCustomEvent(eventName: String, eventProperties: JSONObject)
Smartlook.trackCustomEvent(eventName: String, eventProperties: Bundle)
Smartlook.trackCustomEvent(eventName: String, validJsonString: String)
Smartlook.trackCustomEvent(eventName: String, key: String, value: String)

Smartlook.trackCustomEvent(@NonNull String eventName, JSONObject eventProperties);
Smartlook.trackCustomEvent(@NonNull String eventName, Bundle eventProperties);
Smartlook.trackCustomEvent(@NonNull String eventName, String validJsonString);
Smartlook.trackCustomEvent(@NonNull String eventName, @NotNull String key, String value);

🚧

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.

Navigation event

Screen/navigation transitions can be manually tracked by calling:

Smartlook.trackNavigationEvent(name: String, viewState: ViewState)

Smartlook.trackNavigationEvent(@NotNull String name, ViewState viewState);

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

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

Smartlook.trackNavigationEvent(name: String, type: ViewType, viewState: ViewState)

Smartlook.trackNavigationEvent(@NotNull String name, ViewType type, ViewState viewState);

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:

Smartlook.startTimedCustomEvent(eventName: String)
Smartlook.startTimedCustomEvent(eventName: String, eventProperties: JSONObject)
Smartlook.startTimedCustomEvent(eventName: String, eventProperties: Bundle)
Smartlook.startTimedCustomEvent(eventName: String, eventPropertiesJson: String)

Smartlook.startTimedCustomEvent(@NotNull String eventName);
Smartlook.startTimedCustomEvent(@NotNull String eventName, JSONObject eventProperties);
Smartlook.startTimedCustomEvent(@NotNull String eventName, Bundle eventProperties);
Smartlook.startTimedCustomEvent(@NotNull String eventName, String eventPropertiesJson);

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:

Smartlook.stopTimedCustomEvent(eventId: String)
Smartlook.stopTimedCustomEvent(eventId: String, eventProperties: JSONObject)
Smartlook.stopTimedCustomEvent(eventId: String, eventProperties: Bundle)
Smartlook.stopTimedCustomEvent(eventId: String, eventPropertiesJson: String)

Smartlook.stopTimedCustomEvent(@NotNull String eventId);
Smartlook.stopTimedCustomEvent(@NotNull String eventId, JSONObject eventProperties);
Smartlook.stopTimedCustomEvent(@NotNull String eventId, Bundle eventProperties);
Smartlook.stopTimedCustomEvent(@NotNull String eventId, String eventPropertiesJson);

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:

Smartlook.cancelTimedCustomEvent(eventId: String, reason: String)
Smartlook.cancelTimedCustomEvent(eventId: String, reason: String, eventProperties: JSONObject)
Smartlook.cancelTimedCustomEvent(eventId: String, reason: String, eventProperties: Bundle)
Smartlook.cancelTimedCustomEvent(eventId: String, reason: String, eventPropertiesJson: String)

Smartlook.cancelTimedCustomEvent(@NotNull String eventId, String reason);
Smartlook.cancelTimedCustomEvent(@NotNull String eventId, String reason, JSONObject eventProperties);
Smartlook.cancelTimedCustomEvent(@NotNull String eventId, String reason, Bundle eventProperties);
Smartlook.cancelTimedCustomEvent(@NotNull String eventId, String reason, String eventPropertiesJson);

Typical use of timed event might look like this:

val eventID = Smartlook.startTimedCustomEvent("duration_event")
Thread.sleep(1000) //long running operation
Smartlook.stopTimedCustomEvent(eventId)

String eventID = Smartlook.startTimedCustomEvent("duration_event");
Thread.sleep(1000); //long running operation
Smartlook.stopTimedCustomEvent(eventId);

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:

<View>
    <tag android:id="@id/smartlook_custom_name" android:value="custom_name"/>
</View>

📘

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:

class SettingsActivity : AppCompatActivity(), SmartlookNamedController {

    override fun getCustomName(): String {
        return "custom_activity_name"
    }
}

public class SettingsActivity extends AppCompatActivity implements SmartlookNamedController {
    @NotNull
    @Override
    public String getCustomName() {
        return "custom_activity_name";
    }
}

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

<?xml version="1.0" encoding="utf-8"?>
<View>
	<tag android:id="@id/smartlook_custom_controller_name" android:value="custom_name"/>

	<!-- child views -->
</View>

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:

Smartlook.setGlobalEventProperties(globalEventProperties: JSONObject, immutable: Boolean)
Smartlook.setGlobalEventProperties(globalEventProperties: Bundle, immutable: Boolean)
Smartlook.setGlobalEventProperties(globalEventPropertiesJson: String, immutable: Boolean)
Smartlook.setGlobalEventProperty(key: String, value: String, immutable: Boolean)

Smartlook.setGlobalEventProperties(JSONObject globalEventProperties, boolean immutable);
Smartlook.setGlobalEventProperties(Bundle globalEventProperties, boolean immutable);
Smartlook.setGlobalEventProperties(String globalEventPropertiesJson, boolean immutable);
Smartlook.setGlobalEventProperty(@NotNull String key, @NotNull String value, boolean immutable);

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:

Smartlook.removeGlobalEventProperty(propertyKey: String)

Smartlook.removeGlobalEventProperty(String propertyKey);

Or all global event properties can be removed at once:

Smartlook.removeAllGlobalEventProperties()

Smartlook.removeAllGlobalEventProperties();

📘

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:

val options = Smartlook.SetupOptionsBuilder(API_KEY)
        .setEventTrackingModes(eventTrackingModes: List<EventTrackingMode>)
        .build()

Smartlook.setupAndStartRecording(options)

Smartlook.SetupOptionsBuilder setupOptionsBuilder = new Smartlook.SetupOptionsBuilder(API_KEY)
        .setEventTrackingModes(List<EventTrackingMode> eventTrackingModes);

Smartlook.setupAndStartRecording(setupOptionsBuilder.build());

Set event tracking modes

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

Smartlook.setEventTrackingMode(eventTrackingMode: EventTrackingMode)
Smartlook.setEventTrackingModes(eventTrackingModes: List<EventTrackingMode>)

Smartlook.setEventTrackingMode(EventTrackingMode eventTrackingMode);
Smartlook.setEventTrackingModes(List<EventTrackingMode> eventTrackingModes);

👍

Next reading

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

Smartlook.currentEventTrackingModes()

Smartlook.currentEventTrackingModes();