Getting started with SDKs

Follow

Countly provides various functionality in different SDKs targeted for mobile, web, desktop, server to server and IoT use cases. For a feature comparison in all SDKs, please check this table.

There are common concepts in all Countly SDKs and this document is intended to be a universal getting started guide without getting into the implementation details of individual SDKs. In order to get more information on platform specific implementation, please refer to the documentation of your SDK of choice.

User/device identification

By default Countly generates an anonymous identifier to uniquely identify a device or browser. Total users metric for any period is based on unique number of device ids Countly Server receives requests from. Similarly, users list in User Profiles section is a list of anonymous devices Countly Server is receiving data from. All data originating from a single device, including sessions, events, views, crashes, is grouped under these individual profiles since all the data is tagged with the originating device id.

Most Countly SDKs including, iOS, Android, React Native, FlutterWeb offer a mechanism to change/update this default device id for cases where you already have a better identifier such as an email address or account id or you get this information at some point in user journey such as after user logs into your application. For an in depth analysis of different device/user identification strategies please check out this post.

Deciding on custom user properties

User properties play an important role not only in reporting, but also in various other cases such as personalizing push notifications and creating conditional remote configuration variables.

Most Countly SDKs send some user properties together with the session request  which is triggered automatically when the app is launched, user lands on a website, or manually in some cases such as server to server SDK usage. These properties, which we call default user properties, are meta data including but not limited to app version, device, platform, platform version. 

Furthermore, there are some reserved user properties that you can choose to set, including name, email, organization, gender and age if you choose to store PII (personally identifiable information) in Countly.

Custom user properties are similar in logic to default and reserved user properties, in the sense that this information is stored in user profile level. All the data (sessions, events, views, crashes etc.) originating from a user will get tagged with a historical snapshot of default, reserved and custom user properties and will be available to be used in reporting and features such as Cohorts, Funnels, Drill, Retention and Formulas.

Custom user properties consist of key value pairs, where value can be a string, number, boolean, or an array. There are various modifiers available in the SDKs such as set, set once, push unique, increment, multiply in order to update these as you need. For example, you can store account levels of your users in an accountType custom user property that can take values Basic or Premium to later on filter & segment all reports based on the account type of your customers.

Custom events

A custom event generally represents one of the following:

  • An action of the user such as an interaction with a single UI element, or set of elements
  • An important milestone the user reaches after completing other actions, such as completing an application or on-boarding process 
  • A transaction that takes place after one or more actions of the user, such as a backend API returning a result

It is important to note that custom events aren't designed to only track simple user interactions such as "user clicked this button". The way you define custom events in your app determines the depth of insights you can get from Countly. Tracking everything you possibly can or tracking very little are equally bad. An ideal strategy is collecting the needs of various departments in your organization that'll take advantage of Countly. As a common example;

  • Product team will want to check feature usage, they'll need multiple custom events that show how users interact with various application features
  • Customer experience & success team will want to understand paths users go through (such as during on-boarding) and get stuck in, and will need custom events as milestone indicators
  • Engineering team will want to get transactions & statutes that are created after users' interaction with the UI layer thus they'll need events or event segments that they can take advantage of
  • CXOs and managers will want to see higher level metrics or KPIs, thus this higher level data should exist either as dedicated custom events or individual ones to be used while constructing complex metrics using Formulas

In its most complex form (there can of course be additional segments), an event's JSON representation looks like below. Only mandatory fields are key and count which are set when you call the recordEvent function in any given SDK. Optional sum property is useful when you would like to store an extra numerical value for an event, in the below example we used it to store kilometers for a journey. Duration property represented as dur can be explicitly set, or you can take advantage of the timed events concept available in most SDKs.

{
"key": "Journey",
"count": 1,
"sum": 100,
"dur": 3600,
"segmentation": {
"Route Type": "Fastest"
}
}

Now let's dive into custom event segments and strategies you can follow.

Deciding on custom event segments

Segments are properties that add further detail and meaning to a custom event. Segments are important since most of the time you aren't only interested in how many times some general action happened but also will have the need to dig deeper, filter certain cases or group occurrences by different nuances of the action.

From our custom event sample in the above section, thanks to the Route Type event segment, you can not only see overall journeys taking place, but also see how many of the journeys were planned with a fastest, shortest or eco route types offered in the app. Furthermore, in plugins like Cohorts, Funnels, Drill and Formulas these event segments will be available for use cases such as;

  • Filter events where Route Type = Eco using Drill
  • Construct 3 different funnels where final step is the Journey event in all but filtered to be Route Type = Eco, Route Type = Fastest and Route Type = Shortest
  • Create a behavioral cohort of users who did have a Journey with Route Type = Eco at least 2 times in the last 30 days (these are our eco friendly personas which we can target using remote config and automated push notifications)
  • Construct 2 formulas in which you calculate average kilometers driven per journey for Route Type = Shortest and Route Type = Fastest

As you can tell from the above reporting examples, event segment selection is an important part of your success with reporting & visualization in Countly.

 

Was this article helpful?
0 out of 0 found this helpful

Looking for help?