Adobe Experience Platform Mobile SDKs – Mapping Data for Analytics

[screenshot]

This article is part of the Adobe Experience Platform Mobile SDKs mini-series. It is about mapping data into Analytics.

You can find the overview here.

Mapping data for Analytics

In the article about adding Analytics to your app, I mentioned lifecycle metrics, as well as explicit tracking of Views/Activities and user actions. I put a little example of how to add data to a tracking call, using contextData, key-value-pairs of information.

In my experience, developers have no problem understanding contextData, as opposed to events and eVars, and I therefore like contextData. I’d happily use it on the web, too, but that’s a topic for another day.

The one thing about contextData: you must map it, otherwise Analytics won’t see it at all.

In Analytics, that mapping is done using Processing Rules.

Before we dive into actually creating some Processing Rules, let’s look at the data that the Mobile SDKs are sending.

There are lifecycle metrics, sent by the Mobile Core Extension. They give you metrics like “Installs”, “First Launches”, “Launches”, “Crashes”, dimensions like “Launch number”, “Days since last launch”, “Device name”, “OS version”, and more.

And there are explicit calls triggered by the trackState() and trackAction() methods.

You can tell them apart by looking for a “pev2” parameter.

[screenshot]
Two Analytics tracking calls in Android Studio
Ok.

Context data can be namespaced, and the examples below show items starting with “a.”, “a” being the “built-in”, Adobe-owned name space. In the Processing Rules interface, you can clearly see what data has an “a” namespace, what data is out-of-the-box, so to speak.

[screenshot]
All “a.” values are out-of-the-box, sent by the SDKs, while “language” is not

Metrics vs Dimensions

Context data doesn’t know about metrics or dimensions, or what the difference could be. All context data is key-value-pairs, like “language = en”, or “LaunchEvent = LaunchEvent”.

It is up to you to decide which is which, and to create Processing Rules accordingly.

In general, everything that looks like “xyz = xyz” (“LaunchEvent = LaunchEvent”) is likely meant to be used as a metric, and so it should be mapped to an event. Everything that looks like “abc = def” (“OSVersion = Android 10”) is likely meant to be used as a dimension, and so it should be mapped to an eVar.

Exceptions obviously prove the rule.

Sometimes you want to count an action, but only if some dimension has a specific value. Or you want to count something as an action that hasn’t been set up as one — the most used example being search. Seeing a pagename of “Search Results” and something like “searchTerm = ice cream truck” on a trackState() hit can be used to set the corresponding “Searches” event.

Processing Rules are flexible like that.

There are three metrics and one dimension that do not follow the above: the Page Views, Visits, and Visitors metrics, and the Page dimension (aka pageName).

The three metrics are calculated in the Analytics back end. Page Views are automatically counted if the hit has been sent using trackState(), Visitors are counted based on Experience Cloud IDs or visitor IDs, and Visits are calculated based on the settings (usually by looking at all hits from the same visitor, with a 30-minute timeout).

The Page is tracked explicitly on hits sent using trackState(). The first argument to that function will be used, and you can see that on the hit itself as the pageName parameter. There is no need to map this one.

[screenshot]
state becomes pageName

Events & eVars

Your context data shall then be mapped against events and eVars. If you’re old-fashioned, some of it might even be mapped into props.

So the first thing to do is to actually create these events and eVars, or, if you have already done that, to make sure you know which ones you will be using.

I don’t want to go into that in great detail, so let’s just do one example each.

Log into Analytics, then go to Admin > Report Suites and select the report suite you use for your mobile app.

You should have two of them, actually, one for development, and one for production. Select them both!

[screenshot]
Two Report Suites selected
With both report suites selected, go to Edit Settings > Conversion > Conversion Variables.

You’ll see a list of eVars that is empty save for the “Tracking Code”.

[screenshot]
Empty list of eVars
You can click “Add New” to add an eVar.

This will open up “eVar1”, and if that is the eVar you want to use, go for it.

Alternatively, you can click the “1 – 50” link, and the page will show you all the disabled eVars up to eVar50.

[screenshot]
List of first 50 eVars, all disabled
To stay in line with what I usually do, I will use eVar2 for the language.

Click the little plus, set “Status” to “Enabled” and enter “Language” in the “Name” field.

[screenshot]
Changing eVar2 settings
Next, scroll all the way down and click the “Save” button. A warning will pop up, which you can confirm by clicking “Ok”.

The page will now reload and show you your enabled eVar(s)

[screenshot]
eVar2 set up correctly and saved
Next, head over to Edit Settings > Conversion > Success Events

[screenshot]
Edit Settings > Conversion > Success Events
The list will once again be empty.

[screenshot]
Empty list of events
Use “Add New” or “1 – 100”, whichever you like better, then add your event.

Change your event as you need it, then scroll down, click “Save”, then “Ok” in the pop up.

[screenshot]
Setup for event5
And that’s it, you have successfully created your events and eVars, and you can now start mapping context data.

Processing Rules

Go back to Admin > Report Suites and select the report suite you use for your mobile app.

If you are still in the process of building all this, you will want to use the dev report suite here. You can later copy Processing Rules over to the production report suite.

With one report suite selected, go to Edit Settings > General > Processing Rules

[screenshot]
Edit Settings > General > Processing Rules
You are now likely going to see an empty list of Processing Rules.

[screenshot]
Empty list of Processing Rules
Empty lists are sad, so we shall change that.

Click “Add Rule”, and you’ll see a dialog pop into the page.

We’ll do the eVar first, so leave the drop down on “Overwrite value of”, then select “Language (eVar2)” in the list next to it.

[screenshot]
Set to overwrite eVar2 / Language
In the next list, find and select “language (Context Data)”

[screenshot]
Language in Context Data list
Change the name of the rule and add something in the “Reason” box.

[screenshot]
Rule for setting eVar2 / Language complete
Click “Save” and “Ok” in the pop up warning.

Click “Add Rule” again, see the same dialog as before.

We’re adding a Processing Rule for the event, now, so change the first drop down to “Set event”

Select event5 in the list next, and leave the rest as is.

[screenshot]
Processing Rule to setting an event
The crucial part is to set when exactly the event should be set. For that, we click “Add Condition”

Reminder: we want event5 to be set when the user taps the icon in our app. A look at the app code tells us that when a user does tap, we’re calling trackAction("Targeting Button tapped", null), which in the tracking call translates to the “a.action” context data being “Targeting Button tapped”.

[screenshot]
Java code that handles icon taps
To match that, we select “a.action” in the left list and type “Targeting Button tapped” into the field on the right.

Change the name and add a reason, and that’s it.

[screenshot]
Processing Rule for event5 / Icon clicks
A click on “Save” and “Ok” will save the second Processing Rule.

[screenshot]
2 Processing Rules at your service
With the two Processing Rules in place, data should start to flow into Analytics as soon as we use the app.

In my case, that looks like this:

[screenshot]
Data from app in Analytics
In case you wonder what those “Unspecified” language Visits are: my guess is that the first lifecycle call opens the Visit, and since that doesn’t have a value for eVar2, well, there you go: “Unspecified”.

Debugging / Project Griffon

When I first wrote about Project Griffon, I had made a mistake, and the data from my app did not end up in Analytics (if you must know: timestamps).

Once I fixed that mistake, I saw data coming in (as you can see in the screenshot above), and I also saw a feature in Project Griffon that I hand’t seen before!

Remember how when you switched to the “Analytics view”, some hits were “queued” and then “processed”?

[screenshot]
Processed hits in Post-processed Request Info in Project Griffon
(Also note how the “Home” menu on the left has been changed. Much better, I think!)

Well, when an Analytics hits is in status “processed”, Griffon has actually found it in Analytics, so to speak, and pulled Analytics data back out.

In the “Post-processed Request Info” tab on the right, we can see mobile reserved variables (“reVars” and “rprops”).

[screenshot]
Reserved Variables in Post-processed Request Info in Project Griffon
We can also, if we scroll a little bit, see events, including our “Icon clicks” event.

[screenshot]
event in Post-processed Request Info in Project Griffon
And, if you do the same on a hit that has them, you can also see eVars and props, regular eVars and props.

[screenshot]
eVar in Post-processed Request Info in Project Griffon
This, people, is brilliant!

Not only can Griffon show me what the app is sending out, it can also help me see whether my Processing Rules are correct or not! End-to-end debugging!

This is a huge step forward, if you ask me.

6 thoughts on “Adobe Experience Platform Mobile SDKs – Mapping Data for Analytics

  1. I would also mention Mobile Services Interface (if that one is here to stay) – if configured properly it has a sort of a set of simplified mappings of context Data variables to props, eVars and events that somehow translates to a single huge processing rule. Sometimes it is a bit easier to manage and maintain.

    Liked by 1 person

  2. Can I please know why we still need to create rules in processing rules at adobe analytics report suite instead of creating variables & rules in Adobe Launch for mobile tracking?
    Can i define context variables in Adobe Launch for mobile tracking?

    Like

    1. I guess I look at it the other way round: I see eVars, props, and events as something too specific, and too difficult to learn for implementers. I prefer key/value pairs, or even context data.
      The Processing Rules UI, on the other hand, would be better with a substantial overhaul 🙂

      Like

Leave a Reply to Lukáš Čech Cancel reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.