Google Play Referrer API: Track and measure your app installs easily and securely

Posted by Neto Marin, Developer Advocate

Understanding how people find your app and what they do once they've installed
it is crucial to helping you make the right product and marketing decisions.
This is especially important when you're deciding your advertising strategy and
budget. Today many app measurement companies and ad networks offer ad
attribution solutions based on referral data. As such accurate install referral
data is vital for correctly attributing app installs, as well as discounting
fraudulent attempts for install credit.

To help you obtain more accurate and reliable data about your installs, we're
introducing the Google Play Install Referrer API, a reliable
way to securely retrieve install referral content. Using this API, your app will
get precise information straight from the Play Store, including:

• The referrer URL of the installed package.
  
• The timestamp, in seconds, of when the referrer click happened.
  
• The timestamp, in seconds, of when the installation began.

We've tested the API with our href="https://www.google.com/adwords/appcampaigns/attribution/">App Attribution
Program partners including Adjust,
AppsFlyer, Singular and TUNE.

"The new Play API provides us with the data we need to effectively detect
and prevent click injection; it's a monumental step in securing a crucial
information exchange on Android."

- Paul Müller, CTO & Co-Founder, Adjust

"The new Google Play API introduces fresh insights into both mobile ad fraud
and the mobile user journey, two key domains with impact across the ecosystem."

- Elad Mashiach, VP, AppsFlyer

"This additional data directly from the Play Store provides increased precision for the Kochava fraud suite to further minimize fraud for our customers."

- Charles Manning, CEO, Kochava

"Google's new API is a game changer that will help marketing analytics
platforms like Singular identify and prevent a significant portion of Ad Fraud,
and provide security and accuracy to mobile advertisers"

- Gadi Eliashiv, CEO &
Co-Founder, Singular

"This new data from Google Play is essential for marketers who demand
accountability out of their mobile app install advertising spend. At TUNE, this
data is allowing us to outright eliminate entire forms of mobile app install
fraud while providing new insight into how mobile app installs are driven."

– Dan Koch, Chief Technical Officer, TUNE

Starting today, the API works with the Play Store app from version
8.3.73 and later for all developers.

Play Install Referrer Library 1.0 now available

To make it easy to integrate the Install Referrer API, we've released the
Install Referrer Library 1.0 for Android. The library is available in our Maven
repository. To start using it, add the following dependency to your app module
build.gradle file:

dependencies {
          ...
          compile 'com.android.installreferrer:installreferrer:1.0'
      }

All communication with the Play Store app happens through a Service, so the
first step is to establish the connection between your app and the Play Store.
Also, to receive the connection result and updates it's necessary to implement a
listener, InstallReferrerStateListener. This listener could be your
current Activity or any other class you want to use:

class="prettyprint">public class MainActivity extends AppCompatActivity
implements InstallReferrerStateListener {
…
}

Now that you have an InstallReferrerStateListener, you can start
binding your app to the Play Store app service. To establish the connection, you
must build an InstallReferrerClient instance and call the
startConnection() method:

class="prettyprint">InstallReferrerClient mReferrerClient
...
mReferrerClient = newBuilder(this).build();
mReferrerClient.startConnection(this);

Then, handle the connection result in the
onInstallReferrerSetupFinished() method. If the connection is OK,
the app can retrieve install referrer information, by calling the
getInstallReferrer() method:

class="prettyprint">@Override
public void onInstallReferrerSetupFinished(int responseCode) {
switch (responseCode) {
case InstallReferrerResponse.OK:
try {
Log.v(TAG, "InstallReferrer conneceted");
ReferrerDetails response = mReferrerClient.getInstallReferrer();
handleReferrer(response);
mReferrerClient.endConnection();
} catch (RemoteException e) {
e.printStackTrace();
}
break;
case InstallReferrerResponse.FEATURE_NOT_SUPPORTED:
Log.w(TAG, "InstallReferrer not supported");
break;
case InstallReferrerResponse.SERVICE_UNAVAILABLE:
Log.w(TAG, "Unable to connect to the service");
break;
default:
Log.w(TAG, "responseCode not found.");
}
}

For more details about the new API and the client library, visit the href="https://developer.android.com/google/play/installreferrer/library.html">Install
Referrer Client Library page and the href="https://developer.android.com/reference/com/android/installreferrer/">reference
documentation.

Other Implementations

If you are not able to use our client library, you can use the AIDL interface
and establish the connection with Google Play Store on your own. Check out the
href="https://developer.android.com/google/play/installreferrer/igetinstallreferrerservice.html">IGetInstallReferrerService
AIDL reference for details of the methods and the service
specification.

What's next?

Check out the href="https://developer.android.com/google/play/installreferrer/library.html">Play
Install Referrer API documentation for details about the new API, the href="https://developer.android.com/reference/com/android/installreferrer/">library's
reference docs, and our href="https://developer.android.com/google/play/installreferrer/library.html">Quick
Start guide.