Offer a Button

Attract users and transactions from any of the apps in the Button network.

Users from the Button marketplace will enter your app through a deep link. In order to attribute incoming deep links we check any new activity for a valid button link. For this to work it's important that you start our SDK before any Activity is created, so Application.onCreate() is highly recommended.

Referrer token

If you need to determine whether the user was referred by the Button marketplace, you can access the referrerToken as follows:

if (Button.getButton(context).getReferrerToken() != null) {
   // The user was referred by the Button marketplace.
}

Button Links are a simple, free way to bring users from all channels directly into your app with tracking, attribution and post-install deep linking. After integrating, you can simply replace .com with .bttn.io.

e.g. https://yourdomain.com/some/path -> https://yourdomain.bttn.io/some/path

Button Links are enhanced by:


Deep Linking Support

In order to use Button Links, your app needs to support deep linking using http and https links. Don't support it yet? The Android Deep Linking Guide will get you deep linking in just a few minutes..


In order to start using Button Links you first need to set up your Button Links Domain. This is the base URL that you will use for links that you want to enhance.

Your Button Links Domain is a subdomain of bttn.io which you can use interchangeably with yourdomain.com that will always either open your app if installed, send the user to the App Store for post-install deep linking or forward them to yourdomain.com on the relevant page.

To create your Button Links domain, choose the subdomain of bttn.io that you want to use for your app, specify the base web domain (the domain that you normally use on the web) and associate it with your app.


Once you configure your domain, you can try your first Button Link. Get a Button Link either by using the Button Link Generator on the page or simply replace yourdomain.com with yourdomain.bttn.io in any of your usual links.

Open it in a browser on your mobile device and you'll see your Button Links landing page. We're part of the way there, but before we can open your app using Universal Links or take advantage of post-install deep linking and advanced analytics, you'll need to integrate with Button in your app.


Next, to support App Links for the Button domain (to stop any browser redirecting) you need to add intent filters for the http and https scheme for the Button subdomain (yourdomain.bttn.io) you registered. If you already registered an intent filter for your domain, you can simply add another to the same activity declaration.

We currently do not support verified web associated App Links but by adding the autoVerify="true" attribute you will get this enabled without any further changes when supported. Note: this support is part of Android Marshmallow (6.0), so you'll also need to build against this target sdk level.

<activity name=".YourActivity">
            <intent-filter android:autoVerify="true">
                <action android:name="android.intent.action.VIEW"/>
                <data android:scheme="https"/>
                <data android:host="yourdomain.bttn.io"/>
                <data android:pathPattern=".*"/>
                <category android:name="android.intent.category.DEFAULT"/>
                <category android:name="android.intent.category.BROWSABLE"/>
            </intent-filter>
….
</activity>

Now, your link should open your app without ever opening your browser when the app is installed. Note: by supporting web associated app links you will prevent the Intent Chooser when opening the URL and your app will open automatically.


Post-Install Deep Linking

The easiest way to add post-install deep linking and get access to analytics is to add the Button SDK.

The Button SDK is easily included in your application by adding compile 'com.usebutton:android-sdk:4.1.3' or higher to your app's build.gradle file. You can find more information regarding integrating the SDK in the Integration Guide.

It's a default repository for Android projects, but make sure that jcenter() is listed as one of your repositories.

Alternatively, you can download our SDK from the link below and include it with your project setup manually. Download


Fetch Post-Install Deep Links

To begin, we will initialize the Button SDK with your applicationId. You can get an applicationID by creating an App in the Button Dashboard or reaching out to our team.

You need to add your application ID to you AndroidManifest.xml under the <application> element as a <meta-data> element:

<meta-data android:name="com.usebutton.applicationid" android:value="your-app-ID"/>

Initialize the Button SDK, we suggest you add this to your Application subclass's onCreate() method or if you have a base class for your activities, you can also add it here. Note: the .start() method can be called multiple times without side effects, so no guard is necessary for calling it multiple times.

// Application subclass
@Override
public void onCreate() {
    super.onCreate();
    if (BuildConfig.DEBUG) {
        // Enable debug logging on debug builds
        // adb logcat ButtonSDK:D *:S
        com.usebutton.sdk.Button.enableDebugLogging();
    }
    // Init SDK
    com.usebutton.sdk.Button.getButton(this).start();
}

Now, when the application launches and the activity or activities you declares as recipient for your new yourdomain.bttn.io intent will launch. In onCreate() we will look for a post-install deep link for this user and open it if found. This might take a second or two, so we suggest that your UI reflects that some wait time is to be expected.

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    Button.checkForDeepLink(new Button.DeepLinkListener() {
        @Override
        public void onDeepLink(final Intent intent) {
            // Deep link received, let's open it.
            startActivity(intent);
        }

        @Override
        public void onNoDeepLink() {}
    });
   setContentView(R.layout.your_activity);
   // ....
}


Multiple Install Referrer Receivers

For exact installation and order attribution we take advantage of the Install Referrer Receiver technique which lets you pass a referrer through the installation process on the Google Play Store. Correct attribution is important so we can attribute you and your partners correctly. If you already are one ore more services for installation attribution (Tune, Google Analytics) you need to take some extra measures to make sure that all SDK receivers gets the referrer token as it's not deterministic which one will get it when multiple receivers are registered.

The change you need to do is first disable our default Install Referrer Receiver in your AndroidManifest.xml under the <application> element and then add a new BroadcastReceiver: DelegatingReferrerReceiver.

<!-- Disable intent-filter for default Button Install Receiver-->
<receiver
    xmlns:tools="http://schemas.android.com/tools"
    android:name="com.usebutton.sdk.internal.receivers.InstallReferrerReceiver"
    android:exported="true" >
    <intent-filter tools:node="remove">
        <action android:name="com.android.vending.INSTALL_REFERRER" />
    </intent-filter>
</receiver>
<!-- Delegating BroadcastReceiver, will pass intent to multiple receivers, including Button -->
<receiver android:name="com.yourapplication.DelegatingReferrerReceiver" android:exported="true">
    <intent-filter>
        <action android:name="com.android.vending.INSTALL_REFERRER" />
    </intent-filter>
</receiver>
package com.yourapplication;

import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;
import android.util.Log;

public class DelegatingReferrerReceiver extends BroadcastReceiver {
    private static final String TAG = "InstallReceiver";

    @Override
    public void onReceive(Context context, Intent intent) {
        Log.d(TAG, "Delegating install referrer to Button & Tune: " + intent.toString());
        new com.usebutton.sdk.internal.receivers.InstallReferrerReceiver().onReceive(context, intent);
        // Google Analytics (uncomment if needed)
        // new com.google.android.gms.tagmanager.InstallReferrerReceiver().onReceive(context, intent);
        // Tune (uncomment if needed)
        // new com.mobileapptracker.Tracker().onReceive(context, intent);
        // Branch (uncomment if needed)
        // new io.branch.referral.InstallListener().onReceive(context, intent);
    }
}

Report Orders to Button

In order to facilitate the payment of commission for attributed orders, you need to let Button know when the user makes a transaction or purchase.

We've created an order attribution guide that will walk you through this simple process!


And you're done

You now have Button Links fully configured. Something not working? Contact us and we'll help you work through it.

Testing Post-Install Deep Linking

Testing post-install deep linking is a bit cumbersome, but we'll help you out. What we need to simulate is the following:

  1. Uninstall your app
  2. Record a device fingerprint by visiting your bttn.io link in a browser
  3. Install your app
  4. Open your app

Since we only check for a post-install deep link once you will have to repeat all of the steps below for each test you make. First of all, you need to know two things: a valid bttn.io link for your app <button link> and your app's package name <package> (AndroidManifest.xml under manifest.package).

The general process is as follows:

# 0. Uninstall your app so it doesn't capture the bttn.io link
adb uninstall <package>
# 1. Navigate to the Button link in a browser. Note: This records a fingerprint
# of the device for this link which will be used to retrive it later.
# Note: some versions of adb is sensitive to & in URLs, so URL encode the query component of your URL if
# you're having issues
adb shell am start -W -a android.intent.action.VIEW -d "<button link>"
# 2. Install your app
adb install <your apk>
# 3. Open your app, from the launcher or with this command:
adb shell monkey -p <package> -c android.intent.category.LAUNCHER 1
# 4. Your app should open your `OnDeepLink.onDeepLink` callback will be called
# with an intent to open the intent your declared for these links.
# You will also see useful logging with:
adb logcat -s ButtonSDK

Here's an example for a dummy app:

# package: com.usebutton.example
# link: https://usebutton.bttn.io/Test?btn_ref=abcdef&utm_source=test
adb uninstall com.usebutton.example && \
adb shell am start -W -a android.intent.action.VIEW \
-d "https://usebutton.bttn.io/Test?btn_ref=abcdef&utm_source=test" && \
sleep 1 && \
adb install ~/ButtonApp/app/build/outputs/apk/app-production-release.apk && \
adb shell monkey -p com.usebutton.example -c android.intent.category.LAUNCHER 1
adb logcat -s ButtonSDK