After 2½ years of being in the Play Store, Google has banned my application without warning because my icon contained a portion of the Google Play logo within it. I offered to change the icon and submit a new version, but I was told my app is banned for life. I'm not sure those terms even existed 2½ years ago, but nonetheless, the terms do exist now and it appears my icon probably did violate the terms. My bad. I'm told I can create a new Google Play account and submit a brand new app, but I think I'm done with Google Play for now.
This page is used to test how 'referrer' parameters work when installing applications from the Play store on an Android device. The Play store on Android can be launched from a URL and configured to start on the install page for your application. This is extremely useful when you want to direct a user to install your Android application from a web page, email, ad campaign, etc.
One cool feature of this mechanism is that you can pass information on the URL that will eventually be delivered to your Android application after the installation of your application is complete. Why is this cool? Well, the Google documentation will tell you it is useful for tracking campaigns via the Google Analytics SDK for Android. For example, you may have multiple ad campaigns, web sites, and/or emails driving users to install your application. If each source correctly sets the referrer parameter according to Google's recommended format, then you can track what campaigns are driving the most installs. To get the full benefit of this process, you should compile in the Google Analytics SDK for Android. The SDK will automatically process the referrer parameter after an install completes and pass the information up to the Google Analytics server where you can view the aggregated results for all installs.
Depending on what you read, it often sounds like the referrer string is just for campaign tracking. If you are using campaign tracking with the Google Analytics SDK for Android then you do need follow the required format. If you are not using campaign tracking through the SDK, then you are free to pass whatever you want in the referrer parameter. It can be a string, a JSON object, some XML, whatever. So, why is this cool? There are many uses for this. Say you have a mobile site where you may have some state information about the viewer such as an invitation, some cached credentials, a shopping cart, etc. If your mobile website has an upsell to install your Android application, you can pass this state information into your application and provide the user with a seamless way to install your application and continue in your native app with the same state as they had in your mobile site.
First you have to build a URL that will navigate to your application in the Play store. This looks something like https://play.google.com/store/apps/details?id=com.yourcompany.yourapp&referrer=sometext. In your application, you need to register a broadcast receiver in your AndroidManifest.xml file to catch the intent for the "com.android.vending.INSTALL_REFERRER" action.
Great, let's code it up, test it, and ship it! Along this journey you'll realize that it is impossible to fully test this without first shipping your application since testing it requires your application to be installed from the Play store. There are some things you can do to help test, such as simulating an INSTALL_REFERRER intent from an ADB shell or in code from an Android app, but the only way to truly know how things will behave is to ship your app.
This webpage and the accompanying Android app in the Play store can help with a few things. First, you can play with the referrer builder forms below to see how things work with an app that is actually in the Play store. Second, there are differences to how the INSTALL_REFERRER intent is delivered depending on your OS and Play store version, and this page and app can help you test different cases.
Sadly, the INSTALL_REFERRER intent has a buggy past, but you'll find it mostly works. First, there is no guarantee you will even get the intent, and if you do, the referrer string could be missing, incorrect, or improperly encoded. Make sure your intent processing code is a bit defensive and maybe wrap it in a try/catch handler for good measure. Next, there is no guarantee as to when you will receive the intent. There was a day where the intent would be delivered at install time, which could be long before the user's first run of your app. More recently, the intent seems to be delivered during the first run. So, you should be prepared for both cases. In my app, the referrer receiver class persists the referrer string and provides a static getter so other places in the app can retrieve it whenever needed. The receiver class also exposes a listener interface that it uses to notify any listeners that want to know when the intent is received.
Below are two forms that will build a URL that will navigate to my test app in the Play store. In both cases, extra referrer information that you enter will be passed along on the URL. If all goes well, you should be able click the generated URL on your Android device, go to the Play store, install the "Referrer Test for Google Play" application, run the application, and see the referrer string you entered on this site show up in the log within the application. The log in the application is persisted over all instances of the application. You'll be able to see the order of events over time, even if they come from multiple runs of the application.
The first form builds a referrer string that follows the required format if you plan to use the Google Analytics SDK for Android. You can read more about that here. For information on what the parameters mean, go here. The second form below allows you to enter any freeform text you wish to be delivered to the application.