AndroidAndroid Deep LinkingGoogleTechnical

Technical Guide to Google Play Referrer

By November 3, 2015 6 Comments

This is part four of a four-part technical guide on deep linking on Android. The previous posts covered URI schemes, Chrome Intents, and App Links.

Using Google Play Referrer for Deep Linking

One deep linking technique is for a niche use case where the app is not installed. As the developer, you have the option to pass in a custom parameter through the Google Play store that is then received in your app after the user opens it for the first time. This technique allows you to know where this new user came from if you manage this parameter appropriately, and you can create custom landing pages or deep link through the install process. To learn more, keep reading or request a Branch demo

Google Play Referrer Google Deep Linking

Requirements for Android Install Referrer

  • App must not be installed
  • Cannot be used with Chrome intents since you need to structure the Play Store URL

Configuring the Android Install Referrer

In order to configure your app to receive the Android install referrer, you must register your application to receive the broadcast. Insert the following in between the <application /> tags in your manifest.

In this case, io.branch.testbed.InstallListener is the name of your custom class that will receive the broadcasts. This is a simple subclass of BroadcastReceiver. Here’s the boilerplate code that you’ll need for this class:

Handling in the App

Once you’ve configured your BroadcastReceiver as described above, handling the intent is easy! It’s a very similar mechanism to handling the URI scheme intents, but it happens from within the onReceive call. You can see an example here:

Practical use for Google Play Referrer

In order to properly use this technique, you must be able to control the link to the Google Play Store that the user interacts with. Let’s say our app package name is io.branch.testbed, then we know that Google Play can be opened with either of the following:

  1. market://details?id=io.branch.testbed

To append a referrer, you’ll simply need to append &referrer=specialparam to either of those links. To do this, you’ll need to control the link itself. Note: As you may have noticed reading through the Chrome intent section, you have no control over the Play Store link, meaning that you will not be able to leverage this method.

In order to control the referrer parameter, we’d recommend that you embed it within the client side JS described in the URI method. Here’s a snippet of code that shows how the referrer is added to the market link fallback function that is executed after trying to open the app:


If your eyes are glazing over while reading this, we get it. Google deep linking is incredibly complicated and there are edge cases everywhere. If you use Branch’s tool, you can be confident that your links will just work everywhere.

Branch is a mobile linking platform providing unified mobile experiences and measurement for more than 50,000 mobile apps, including Airbnb, Ticketmaster, Reddit, Tinder and Amazon. Branch’s linking platform can help you grow your mobile app through features like deep linking, sharing, referrals, mobile banners and interstitials, custom app onboarding, and unified attribution across platforms and channels. Learn more about Branch or contact sales today.
  • Lenin

    How can we do this if the app is not hosted through Google Play?

    • Alex Bauer

      Hi @Lenin:disqus!

      The Google Play Referrer is specific to the Google Play store, so unfortunately you cannot use it elsewhere.

      Is your live app hosted on another app store, or are you simply working to debug a pre-release app?

      • Lenin

        It is distributed through our own site (as static files via AWS S3) as we cannot host at Google Play due to legal reasons. I have already signed up for Branch too 🙂

        • Alex Bauer

          It should work fine to set a Custom URL pointing to your APK in Link Settings on your Branch dashboard. You won’t be able to use the Google Play Referrer, but Branch provides superior deferred deep linking functionality anyway 😉.

          Feel free to get in contact with our Integrations team for more specific directions — they’ll be happy to help!



    I am facing an issue with regards to branch io deep linking.

    Environment: I am using
    Android Marshmallow SDK, platform: 25
    Cordova 7.0.1 and
    Branch SDK
    “io.branch.sdk”: “~2.2.3”
    “branch-cordova-sdk”: “^2.2.5”,

    Below are the scenarions in which im facing issue:

    Scenario 1: Calling Branch.InitSession in OnResume call back function.
    Failed case:

    Installed the app for the first time. (Did not open the app)
    clicked on Branch IO Deep Link,
    It opens up the app on my phone, but does not redirect to the url that is specified in the parameters of the Deep Link, as the InitSession is being called twice.
    a) In the OnDeviceReady call back function.
    b) In the OnResume Function ( This is because, since my app is opening for the first time, it request the user for permission, which pauses the application and resumes when user deny’s/ approves the permission calling the onresume method).
    Second time when the InitSession is invoked from OnResume call back it recives empty parameters from Deep Link and the application does not redirect to the URL as expected.
    Scenario 2: If i remove the Branch.InitSession in OnResume call back fucntion.
    Success case: The above scenario works well, if remove the InitSession in OnResume function
    Failed case:

    Installed the app.
    Opened the app and let the app be in the background.
    Clicked on a Branch IO deep link.
    The application does not recieve the deep link data or the parameters to process the information, since the initsession is not avaible in the onresume method.
    Can you please let me know how to handle such a scenario, let me know if i need to publish any further information which might help you in finding if i am implementing it in wrong way.

    Thanks & Regards,

    • Alex Bauer

      Hi Jyothi,

      Sorry you’re running into issues! Would you mind submitting this information to our Integrations team? They’re much better set up to help debug these situations.

Request Demo Create Links