The Google Play Referrer API and the AppBrain SDK

Mathijs Vogelzang
Dec 12, 2019 · 3 min read

On December 10th, Google sent out emails “[Action Required] Switch to the Play Referrer API by March 1, 2020” to many Android developers. The AppBrain SDK could be the cause, as the SDK tracks referrals and shows them in the Analytics part of our dashboard.

Short summary: what should I do?

  • Upgrade your app to a recent version of the AppBrain SDK to keep the referral analytics working. Any version released since July 2019 correctly uses the new API if available. Make sure your Gradle dependency does not include ‘@aar’ as discussed in our integration guide.
  • If you take no action, and your apps are using a SDK version from before July, the referral analytics on the AppBrain dashboard will stop working in March 2020.
    The warning from Google is *not* a policy warning and your app is not at risk to be taken down because of this. Your earnings from the AppBrain SDK are also not affected by this.

For a more detailed explanation, read on.

Explanation: what exactly is changing?

The change has to do with the “install referrer”. When a user installs your app, Google Play stores a message about how that user found your app, the “install referrer”. Often this will be “organic” (i.e., the user browsed Google Play and saw your app). If the user clicked an AppBrain promotion ad it will be “appbrain_cpi”, and it can be other values for other install channels.

Example referrer report from AppBrain analytics

The AppBrain SDK retrieves this install referrer and records it so you can see in the AppBrain analytics. This shows which channels led to the most installs, what their retention is, and other information that may help you optimize your user acquisition strategy. Other analytics SDKs may also use the install referrer for similar purposes.

The install referrer goes from being broadcast by Google Play to something that needs to be requested through the referrer API.

The interaction between your app and Google Play to retrieve the referrer is changing. The old way worked by Google Play broadcasting the install referrer to your app (usually 10–20 seconds after an app runs for the first time).

The new way works by the app requesting the referrer from Google Play. This is called the “referrer API”.

How does the AppBrain SDK handle the install referrer?

Since last July, the AppBrain SDK uses the referrer API (the ‘new’ way) when available. However, it also still listens for the broadcasts that are sent the old way, just in case the new API is not working. The presence of the code for handling the old-style broadcasts triggered the warning email from Google. (In other words, they seem to not have checked whether apps use both ways of handling referrers, only whether the old way is still present).

If your app is still using an AppBrain SDK version from before July, and you won’t upgrade it, then the referrer information will stop showing in March 2020.

Relevant links


The go-to place to promote and earn money for Android…


The go-to place to promote and earn money for Android developers.

Mathijs Vogelzang

Written by

Building the top Android CPI network, AppTornado, AppBrain, Swiss Codemonkey


The go-to place to promote and earn money for Android developers.