Help centerWeb SDKIntegrationsRest API
API Reference
Go to Smartlook

Analytics

Some analytic events are recorded out-of-box:

  • Navigation changes
  • Focus changes
  • Clicked views
  • For everything else, custom events can be used

Custom event

A simple custom event can be created by calling:

class func trackCustomEvent(name eventName: String)

+ (void)trackCustomEventWithName:(nonnull NSString*)eventName;

Custom event also accepts a dictionary of string key/values as event properties.

Smartlook.trackCustomEvent(name: String, props: [String : String]?)

+ (void)trackCustomEventWithName:(nonnull NSString*)eventName props:(nullable NSDictionary<NSString*, NSString*>*)props;

Navigation event

Screen/navigation transitions can be manually tracked by calling:

static let enter: Smartlook.NavigationEventType
static let exit: Smartlook.NavigationEventType


Smartlook.trackNavigationEvent(withControllerId controllerId: String, type: Smartlook.NavigationEventType)

SLNavigationType const _Nonnull SLNavigationTypeEnter;
SLNavigationType const _Nonnull SLNavigationTypeExit;


+ (void)trackNavigationEventWithControllerId:(nonnull NSString *)controllerId type:(nonnull SLNavigationType)type;

where the type could flag the event as either enter or exit of the navigation controller.

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(name: String, props: [String : String]?) -> Any

+ (id _Nonnull)startTimedCustomEventWithName:(nonnull NSString*)eventName props:(nullable NSDictionary<NSString*, NSString*>*)props;

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:

// to track successfull events
Smartlook.trackTimedCustomEvent(eventId: Any, props: [String : String]?)
// to track event cancellation
Smartlook.trackTimedCustomEventCancel(eventId: Any, reason: String?, props: [String : String]?)

// to track successfull events
+ (void)trackTimedCustomEventWithEventId:(id _Nonnull)eventId props:(nullable NSDictionary<NSString*, NSString*>*)props;
// to track event cancellation
+ (void)trackTimedCustomEventCancelWithEventId:(id _Nonnull)eventId reason:(NSString *_Nullable)reason props:(nullable NSDictionary<NSString*, NSString*>*)props;

Typical use of timed event might look like this:

let eventRef = Smartlook.startTimedCustomEvent("duration_event")
// some lenghty operation
Smartlook.trackTimedCustomEvent(eventRef)

id eventRef = [Smartlook startTimedCustomEventWithName:@"duration_event"];
// some lenghty operation
[Smartlook trackTimedCustomEventCancelWithEventId:eventRef];

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:

class func setGlobalEventProperty(value: String, forName name: String)


static var immutable: SLPropertyOption
class func setGlobalEventProperty(value: String, forName name: String, options: SLPropertyOption)

+ (void)setGlobalEventPropertyValue:(nonnull NSString *)value forName:(nonnull NSString *)name;

typedef NS_OPTIONS(NSUInteger, SLPropertyOption) {
    SLPropertyOptionDefaults    = 0,
    SLPropertyOptionImmutable   = 1 << 0
};
+ (void)setGlobalEventPropertyValue:(nonnull NSString *)value forName:(nonnull NSString *)name withOptions:(SLPropertyOption)options;

Smartlook.setGlobalEventProperty(value: "value", forName: "my-property")
Smartlook.setGlobalEventProperty(value: "immutable-value", forName: "my-immutable-property", options: .immutable)

[Smartlook setGlobalEventPropertyValue:@"value" forName:@"my-property"];
[Smartlook setGlobalEventPropertyValue:@"immutable-value" forName:@"my-immutable-property" withOptions:SLPropertyOptionImmutable];

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(forName: String)

+ (void)removeGlobalEventPropertyForName:(nonnull NSString *)name;

Or all global event properties can be removed at once:

Smartlook.clearGlobalEventProperties()

+ (void)clearGlobalEventProperties;

📘

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:

  • fullTracking: this a default state. SDK tracks all automatically detected events along with all user defined events.
  • ignoreUserInteractionEvents: disables automatically detected selector (click on a UIView), focus, touch, gesture and keyboard events.
  • ignoreNavigationInteraction: disables automatically detected navigation events. User defined ones are still being sent.
  • ignoreRageClicksEvents: disables automatic detection and tracking of rage click events.
  • noTracking: no automatically detected events are tracked. Only user defined events are still tracked.

Set event tracking modes

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

class func Smartlook.setEventTrackingMode(to: Smartlook.EventTrackingMode)
class func Smartlook.setEventTrackingModes(to: [Smartlook.EventTrackingMode])

+ (void)setEventTrackingModeTo:(SLEventTrackingMode _Nonnull)eventTrackingMode;
+ (void)setEventTrackingModesTo:(NSArray<SLEventTrackingMode> * _Nonnull)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:

class func Smartlook.currentEventTrackingModes() -> [Smartlook.EventTrackingMode]

+ (nonnull NSArray<SLEventTrackingMode> *)currentEventTrackingModes;