Events in Cocoa apps
Events help you to track all the user actions within your app. For example, sign up, purchase made, feedback given and so on. Events analytics and the associated data helps you understand your users.
Event types
Zoho Apptics provides two types of event analytics; Defined events and Custom events.
Defined events - These are the default events that are available for your use once you have integrated our SDK.
Custom events - These are the events that you want to capture using our SDK.
To be able to use either the defined or custom events, you need to:
- Make sure that you have integrated Apptics with your app, refer to the integration guide for detailed steps.
Logging custom events
Copied[APEvent trackEvent:<#(nonnull NSString *)#> andGroupName:<#(nonnull NSString *)#>]
CopiedAPEvent.trackEvent(<#String#>, andGroupName: <#String#>)
- should not be more than 100 characters.
- should start with an alphabet.
- should not contain any space or special characters apart from underscore (_).
- cannot start with 'ap_' or 'AP_'. These are reserved for the defined events.
An example of a valid event name : 'helloworld' , 'Hello_world' , 'helloWorld'
An example of an invalid event name : '_helloworld' , '1hello' , `Hello World` , 'ap_helloworld`
Custom events with properties
- Event properties are any additional information that can be associated with the events you are capturing using our SDK. These properties are can be passed as a NSDictionary or Dictionary.
- To add the custom properties, call the below method.
Copied[APEvent trackEvent:<#(nonnull NSString *)#> andGroupName:<#(nonnull NSString *)#> withProperties:<#(nonnull NSDictionary *)#>];
CopiedAPEvent.trackEvent(<#String#>, andGroupName: <#String#>, withProperties: <#Dictionary#>);
Sample snippet to use properties
CopiedNSDictionary *properties = @{@"item": @"Box", @"quantity": @10};
[APEvent trackEvent:@"event_name" andGroupName:@"group_name" withProperties:properties];
Copiedlet properties = ["item": "Box", "quantity": 10]
APEvent.trackEvent("event_name", andGroupName: "group_name", withProperties: properties)
Make sure that the event properties follow the below norms else, the properties won't be logged with the events.
- property key should not be more than 50 characters.
- property key should start with an alphabet.
- property key should not contain any space or special characters except underscore (_).
- property key should not start with 'ap_' or 'AP_'.
- property value can be a number (init, float, double, long), boolean, or string. Other data types such as JSONObject or JSONArray will be converted to string.
- property value length should not be more than 250 characters.
Logging timed events
- To log the timed events, call the startTimedEventwithEventname method.
CopiedNSNumber *startTime = [APEvent startTimedEventWithEventName:(nonnull NSString *) group:(nonnull NSString *) andProperties:(id_Nullable)];
Copiedlet startTime = APEvent.startTimedEvent(withEventName: (String), group: (String), andProperties: (Dictionary?))
- Pass the timestamp returned during the startTimedEvent method to the endTimedEventWithEventName method. This will end the timer of the specific event.
Copied[APEvent endTimedEventWithEventName:(nonnull NSString *) group:(nonnull NSString *) andStartTime:startTime];
CopiedAPEvent.endTimedEvent(withEventName: (String), group: (String), andStartTime: startTime)
Logging timed event for Extensions
- Track the sessions using timed events for Extensions.
Start the timed event in extensions
- Use the startTimedEventWithGroupName method from the AppticsExtensionManager. This method will also return a timestamp which is needed to end the event.
CopiedNSNumber *startTime = [AppticsExtensionManager startTimedEventWithGroupname:(NSString * _Nonnull) eventName:(NSString * _Nonnull) property:(NSDictionary<NSString *,id> * _Nonnull) appGroup:(NSString * _Nonnull)];
Copiedlet startTime = AppticsExtensionManager.startTimedEvent(withGroupname: (String), eventName: (String), property: (Dictionary<String, Any>), appGroup: (String))
End the timed events in extensions
- Pass the timestamp returned during the startTimedEvent method to the endTimedEvent method. It will end the timer for the specific event.
Copied[AppticsExtensionManager endTimedEventWithGroupname:(NSString * _Nonnull) eventName:(NSString * _Nonnull) andStartTime:startTime];
CopiedAppticsExtensionManager.endTimedEvent(withGroupname: (String), eventName: (String), andStartTime: startTime)
Logging defined events
Our SDK comes with a set of default events known as defined, available for your use once you have completed the SDK integration. Some of these events are tracked automatically (please see the automatic events).
The defined events are available as a constant string in our SDK and you can pass them to the trackEvent method.
Copied[APEvent trackEvent:AP_IN_APP_PURCHASE andGroupName:AP_APPLICATION];
CopiedAPEvent.trackEvent(AP_APPLICATION, andGroupName: AP_IN_APP_PURCHASE);
Enable automatic tracking
To track the events automatically, set enableAutomaticEventTracking to true just before you initialize Apptics.
Copied[[AppticsConfig defaultConfig] setEnableAutomaticEventTracking:YES];
CopiedAppticsConfig.default.enableAutomaticEventTracking = true;
A list of all the defined events.
Group name | Event name | Auto tracked |
---|---|---|
AP_GROUP_APP_LIFE_CYCLE | AP_EVENT_APP_INSTALL | No |
AP_GROUP_APP_LIFE_CYCLE | AP_EVENT_APP_UNINSTALL | No |
AP_GROUP_APP_LIFE_CYCLE | AP_EVENT_APP_UPDATE | No |
AP_GROUP_APP_LIFE_CYCLE | AP_EVENT_APP_CRACKED | No |
AP_GROUP_APP_LIFE_CYCLE | AP_EVENT_APP_OPEN | No |
AP_GROUP_APP_LIFE_CYCLE | AP_EVENT_APP_CLEAR_DATA | Yes |
AP_GROUP_APP_LIFE_CYCLE | AP_EVENT_APP_FOREGROUND | Yes |
AP_GROUP_APP_LIFE_CYCLE | AP_EVENT_APP_BACKGROUND | Yes |
AP_GROUP_APP_LIFE_CYCLE | AP_EVENT_APP_OUT_OF_MEMORY | Yes |
AP_GROUP_APP_LIFE_CYCLE | AP_EVENT_APP_FIRST_OPEN | Yes |
AP_GROUP_APP_LIFE_CYCLE | AP_EVENT_APP_LAUNCHING | Yes |
AP_GROUP_APP_LIFE_CYCLE | AP_EVENT_APP_RESIGN_ACTIVE | Yes |
AP_GROUP_APP_LIFE_CYCLE | AP_EVENT_APP_WILL_CONNECT | Yes |
AP_GROUP_USER_LIFE_CYCLE | AP_EVENT_USER_SIGNUP | Yes |
AP_GROUP_USER_LIFE_CYCLE | AP_EVENT_USER_LOGIN | Yes |
AP_GROUP_USER_LIFE_CYCLE | AP_EVENT_USER_LOGOUT | Yes |
AP_GROUP_APPLICATION | AP_EVENT_DEEP_LINK_OPEN | No |
AP_GROUP_APPLICATION | AP_EVENT_DEEP_LINK_UPDATE | No |
AP_GROUP_APPLICATION | AP_EVENT_DEEP_LINK_FIRST_OPEN | No |
AP_GROUP_APPLICATION | AP_EVENT_IN_APP_PURCHASE | No |
AP_GROUP_APPLICATION | AP_EVENT_NOTIFICATION_RECEIVE | No |
AP_GROUP_APPLICATION | AP_EVENT_NOTIFICATION_OPEN | No |
AP_GROUP_APPLICATION | AP_EVENT_NOTIFICATION_DISMISS | No |
AP_GROUP_APPLICATION | AP_EVENT_NOTIFICATION_FOREGROUND | No |
AP_GROUP_APPLICATION | AP_EVENT_SEARCH | No |
AP_GROUP_APPLICATION | AP_EVENT_BATTERY_LOW | Yes |
AP_GROUP_APPLICATION | AP_EVENT_BATTERY_FULL | Yes |
AP_GROUP_APPLICATION | AP_EVENT_LOW_POWER_MODE_ON | Yes |
AP_GROUP_APPLICATION | AP_EVENT_LOW_POWER_MODE_OFF | Yes |
AP_GROUP_OTHERS | AP_EVENT_NETWORK_REACHABILITY_CHANGE | No |
AP_GROUP_OTHERS | AP_EVENT_NETWORK_BANDWIDTH_CHANGE | No |
AP_GROUP_OTHERS | AP_EVENT_SWITCH_THEME_LIGHT | Yes |
AP_GROUP_OTHERS | AP_EVENT_SWITCH_THEME_DARK | Yes |
AP_GROUP_OTHERS | AP_EVENT_SWITCH_THEME_CUSTOM | No |
AP_GROUP_OTHERS | AP_EVENT_SWITCH_ORIENTATION_LANDSCAPE | Yes |
AP_GROUP_OTHERS | AP_EVENT_SWITCH_ORIENTATION_PORTRAIT | Yes |
AP_GROUP_OS | AP_EVENT_OS_UPDATE | No |
AP_GROUP_OS | AP_EVENT_OS_UNSUPPORTED | No |