Adobe Experience Platform Mobile SDKs – Mapping Data for Analytics

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.

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.

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.

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!

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”.

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.

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.

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)

Next, head over to Edit Settings > Conversion > Success Events

The list will once again be empty.

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.

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

You are now likely going to see an 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.

In the next list, find and select “language (Context Data)”

Change the name of the rule and add something in the “Reason” box.

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.

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”.

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.

A click on “Save” and “Ok” will save the second Processing Rule.

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:

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”?

(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”).

We can also, if we scroll a little bit, see events, including our “Icon clicks” event.

And, if you do the same on a hit that has them, you can also see eVars and props, regular eVars and props.

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.