Lifecycle Metrics
19 Nov 2017 » Mobile
In my previous post, I explained how to use Adobe Analytics in mobile apps, as there are many similarities between web and apps. However, there are very clear differences, like the fact that an app is installed in a mobile device and a web is not. This gives the SDK the opportunity to capture additional metrics and dimensions in what we call lifecycle metrics. You might also see them named as mobile metrics and dimensions.
Metrics and dimensions
The expression “lifecycle metrics” might lead you to think that it only relates to metrics. In fact, the opposite is true: it refers to both dimensions and metrics. I guess it is just simpler to just reference to the “metrics” part. The important concept here is “lifecycle”. It shows information gathered by the SDK, automatically, about the app life cycle.
You have the full list of lifecycle metrics offered by Adobe Mobile Services here. This list has been increasing over time, so expect to find more in the future. I am not going to enumerate them all, but let me explain you those that I consider most important.
Metrics
- First launches. Many of my clients, when they start tracking mobile apps, ask the same question: number of installs. I understand that this is a very good success metric. However, it is impossible to measure it directly within the SDK. The reason is that, when a user installs an app, it is not executed. On the other hand, what the SDK can track is when the user launches the app for the first time, thus, generating this metric. In fact, I would argue that the first launches metric is more important than the installs metric. If a user installs an app and never launches it, is like he has never installed it in the first place.
-
Launches. If, like me, you come from a web background, you will think in visits. There is an industry standard definition for visit. The reason why we must use this metric is that the browser gives no information on when a visitor stops viewing the website. However, in a mobile device, the SDK knows when the app is in the foreground and in the background. As a consequence, there is no need for guesses. In principle, you could count the number of times the app is in the foreground (showing on the screen).
However, it is very common for the user to switch between apps. Counting every time the user comes back will not give you an accurate picture. What you need is a session timeout. If an app stays in the background for more than this timeout, the next time the user brings it back to the foreground, the SDK will fire a launch event. The default value is 5 minutes (=300 seconds), it is configurable and you can find it in the app settings under “Session Timeout (seconds)”. Remember to update the JSON file if you change it. - Crashes. Not that it is important, but I have seen a recurring issue with it worth mentioning. In particular, for Android, if you do not strictly follow the implementation guidelines below, the SDK may get confused. You have to make sure the SDK sees that the app exited correctly, to avoid sending this event.
Dimensions
- App ID. This is the app name and the version. The important part is, from my point of view, the version. Whenever you release a new version of your app, you would hope everybody would immediately updates through the app store. This is particularly important if a new release fixes an important issue or offers new functionality. Unfortunately, this is not always the case. Therefore, if you have modified the Analytics code to capture new details, always remember to do a breakdown by App ID.
- Launch number. This is a more accurate count compared to visit number. Now you have a clearer definition of launch and, usually, a user will only have your app in one device. It is a very good dimension to measure the engagement of a user with your app.
Implementation of lifecycle metrics
The beauty of how lifecycle metrics have been implemented in the SDK is that no special code is needed. All you have to do is follow the steps in the “getting started” sections of the SDK: Android & iOS. You will notice that each operating system requires different code. This is due to the differences in how they work internally. Besides, you do not need to burn events or precious eVars to capture them. Adobe Analytics stores these metrics and dimensions in reserved variables, which behave as regular eVars and events.
In some rare occasions, you may want to send additional context data as part of your lifecycle metrics calls. You can do that just like any other call to Analytics:
public void onResume() {
HashMap<String, Object> contextData = new HashMap<String, Object>();
contextData.put("myapp.category", "Game");
Config.collectLifecycleData(this, contextData);
}
As usual, you will have to map these context data variables to custom eVars, props or events in the Adobe Mobile Services UI, just as what you did with the Adobe Analytics implementation. If you are wondering why you would need this feature, you should know that the first call to Analytics happens on launch, before calling Analytics.trackState() or Analytics.trackAction(). Therefore, if you want to set, for example, an eVar at the very beginning, this solution is for you. You can then use these additional variables combined with the out-of-the-box lifecycle metrics.
Debugging lifecycle metrics
Since everything happens in the SDK, there is nothing you can debug directly in the code. In order to see what is going on, you need to capture the data sent to Adobe’s server. As usual, I recommend Charles proxy. In a future post, I will explain how to debug mobile apps with this excellent tool.
The following is an example of the first request upon launching an app:
I think that most of the parameters are self-explanatory and do not need any additional comments. However, I will explain some details of what we see in the previous image:
- All lifecycle metrics are contained between “a.” and “.a”.
- The call clearly states it is a lifecycle metric with the “internalaction=Lifecycle” parameter.
- This is a launch event, which will increase the launches metric. You can also see it is the first call.
- The previous session did not end well, triggering the crash event.
- The call looks exactly like a custom link tracking call (pe=lnk_o).