The new Android app that some of your colleagues are currently building has to be tracked. Fortunately, your organisation is mature, has therefore thought about this well in advance and as a result you are well under way with your analytics implementation.
(Note: if you are still wondering about how to implement in a mobile app, may I recommend my mini series on analysing mobile apps?)
But all of a sudden your friendly marketer tells you that they need to track “the full user journey”, and now you are a bit flummoxed. What does that even mean?
In all likelihood what she wants is a report like this one:
How does that work, technically?
Google Play Campaigns
Google’s Play Store is unique in the sense that it allows campaign tracking to pass through from the store all the way into the app.
Meaning: if your marketer sends visitors to the app’s page on the Play Store with tracking codes on the URL (the usual Google codes apply), Android (or rather Google Play Services) will pass those into the app when it installs it.
That in turn allows you to track them into Adobe Analytics (or any other analytics tool, of course).
The story goes like this:
- Friendly marketer creates URL to app on Play Store, like so:
https://play.google.com/store/apps/details?id=com.example.app&referrer=utm_source%3Dgoogle%26utm_medium%3Dcpc%26utm_term%3Drunning%252Bshoes%26utm_content%3DdisplayAd1%26utm_campaign%3Dshoe%252Bcampaign
- Friendly marketer sends email blast with that link
- Visitor clicks link and lands on the app’s page on the Play Store
- Visitor now install the app
- Play Services on Android device receives APK and installs it
- Play Services on device “broadcasts” an Intent to the app — a
com.android.vending.INSTALL_REFERRER
Intent, to be exact - Intent contains an “Extra” of type
String
named “referrer” that contains the above - A
BroadcastReceiver
in your app can use the Intent, extract the data and track it
Easy? Yup. Let’s make an example.
Code (simple)
Most of this comes straight from the manual pages (Adobe: Google Play Campaign Tracking (v3.1+), Google Play Campaign Tracking (v4.x+) & Google: Campaign Measurement – Android SDK, Testing Google Play Campaign Measurement), errors are entirely my fault.
I show you how to build a rudimentary app, as simple as possible, with just enough code in it to grab the campaign parameters and track them.
For that, we will need two things: an Activity so that we can launch the app and track the launch, and a BroadcastReceiver that picks up the Intent after installation.
So go ahead, create an Android project containing one Activity.
Next we need the Adobe Marketing Cloud library, which we can find on the Developer Connection. Extract adobeMobileLibrary.jar
and ADBMobileConfig.json
somewhere. Add adobeMobileLibrary.jar
as an external library (also select it on the Order and Export tab!). Copy ADBMobileConfig.json
into the assets
folder in your project.
android.permission.INTERNET
and android.permission.ACCESS_NETWORK_STATE
permissions to your AndroidManifest.xml
file.
Customize your ADBMobileConfig.json
file. For Analytics, all we really need is one or more report suite ID in the rsids
field, and of course a tracking server in the server
field.
Tip: you can find the value for server
if you look at your web site, provided the site is being tracked. Load a page, look for an HTTP request containing /b/ss/
in the URL, then use the host part of that URL.
Your friendly marketer must enable mobile application reporting for the report suite. Note that you can test all of your work before he has done that.
Let’s add some code now.
The library wants to be configured when the app starts, therefore we add a call to Config.setContext(this.getApplicationContext())
to the onCreate
method of the app. We also add Config.collectLifecycleData()
to the onResume
method and Config.pauseCollectingLifecycleData()
to onPause
.
Technically this is all we need for tracking. Meaningful analytics would definitely be more involved than this, but for our purposes the Activity is now ready. It should look like this:
package com.exner.test.jeapptrackingtest; import android.app.Activity; import android.os.Bundle; import com.adobe.mobile.Config; public class MainActivity extends Activity { @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); // set context for Mobile Analytics Config.setContext(this.getApplicationContext()); // for debugging Config.setDebugLogging(true); } @Override protected void onPause() { super.onPause(); // pause collection of lifecycle metrics Config.pauseCollectingLifecycleData(); } @Override protected void onResume() { super.onResume(); // collect lifecycle metrics Config.collectLifecycleData(); } }
Next we create a class that extends BroadcastReceiver
. The onReceive
method in our class will be called when the app is installed on a device, and this is where we can pick up the campaign parameters that our friendly marketer has added to the URL to Google Play.
All we need is a call to Analytics.processReferrer(context, intent)
in the onReceive
method. This is what it’ll look like:
package com.exner.test.jeapptrackingtest; import android.content.BroadcastReceiver; import android.content.Context; import android.content.Intent; import com.adobe.mobile.Analytics; public class InstallBroadcastReceiver extends BroadcastReceiver { @Override public void onReceive(Context context, Intent intent) { Analytics.processReferrer(context, intent); // DEBUG - show the referrer String referrer = intent.getStringExtra("referrer"); Log.d("JE", "Referrer is: " + referrer); } }
The call to processReferrer
will grab the campaign parameters from the Intent and store them. No tracking happens at this time!
I added some debugging to the method. You can’t set a breakpoint in the onReceive
method, because when this code is executed, your app won’t actually be debuggable!
The BroadcastReceiver needs to be exported in the manifest, of course, so let’s add it. The AndroidManifest.xml should now look like this:
Now to the fun part.
Debugging
Here comes the fun complicated part. Debugging this is slightly tricky.
The main limitation is that in order for the campaign data to be sent, the following steps need to happen in order. No shortcuts!
- Completely remove app from emulator or testing device
- Push app to emulator or device but do not start it
- Broadcast the Intent (either via ADB or however you like)
- Now launch the app
Two crucial pieces of information: the referrer data from the Intent in the broadcast will only be sent on first launch! In order for data to be sent, utm_campaign, utm_medium & utm_source must be set in the URL!
I spent half a day testing and not seeing anything before I knew this, so chances are if you are reading this you will save a lot of time. You’re welcome.
Other than that, debugging is straight-forward: just look at Logcat output.
Let me walk you through the steps.
Firstly, you will need to load the APK for your app onto the device without running it.
I did not find a way of doing this using eclipse, so I basically used adb
to install the APK manually every time I changed something.
(Can’t find an APK for your app? Go to preferences > Android > Build and untick the “Skip packaging and dexing …” option.)
Now launch your emulator or plug in your test device, then go to your platform-tools
folder and install the APK.
adb install \dev\jeapptrackingtest\bin\JEAppTrackingTest.apk
Do NOT run it at this point!
For a normal user, the app would be installed via the Play Store. After installation, the Google Play Services on the phone would send the com.android.vending.INSTALL_REFERRER
broadcast to the app, so this is what we need to do now.
Again we will use ADB here, although theoretically you should be able to write a small app that sends the broadcast.
adb shell am broadcast -a com.android.vending.INSTALL_REFERRER -n com.exner.test.jeapptrackingtest/.InstallBroadcastReceiver --es "referrer" "utm_source=testSource&utm_medium=testMedium&utm_term=testTerm&utm_content=testContent&utm_campaign=testCampaign"
If you do this right (and I had to add “\” before the “&”s in the referrer), you should see the whole referrer in LogCat, like so:
![[Screenshot]](https://webanalyticsfordevelopers.files.wordpress.com/2013/11/131119-tracking-and-logcat.png?w=300&h=87)
Note
One important thing: if you want to test this again, you have to remove the app completely from your emulator or device before you try again!
how can i test if the BroadcastReceiver was inplemented on a different package than the main activity
for example my main activity is com.example.jose
and i create a second package in the same project called com.xxx.utils
in the second one is the class TestReceiver that extend BroadcastReceiver
how i should use the adb call :
apk shell am broadcast -a com.android.vending.INSTALL_REFERRER
-n com.example.jose/com.xxx.utils.TestReceiver
–es “referrer” “utm_source=testSource&utm_medium=testMedium&utm_term=testTerm&utm_content=testContent&utm_campaign=testCampaign”
???
it doesn’t seems to work this way
LikeLike
Good question, Jose!
Let me try to find out…
LikeLike
Have you tried
-n com.xxx.utils/.TestReceiver?
LikeLike
yes is saying broadcast completed: result=0 but nothing is been passed to the app, or the app is not catching that
in the manifest should i put com.xxx.utils.TestReceiver no?
LikeLike
Hm… You could add some logging to your BroadcastReceiver to see whether it is actually being called.
LikeLike
Hi,
I tried your code,while running the application in log i am getting ADBMobile Error : SDK has not been configured correctly this type of error and no camp found.please any suggestion.
LikeLike
Hi Prashant!
I guess you are using an SDK v4.x, right? They are different.
I’m currently preparing an article series about the v4.x SDKs for release in August.
In the meantime, have you looked at the developer quickstart on http://microsite.omniture.com/t2/help/en_US/mobile/ios/dev_qs.html?
LikeLike
Hi,
Actually am really confused,but thanks for your suggestion.
LikeLike