Get Started: Android

Unlock features, mobile partnerships & revenue with one drop-in SDK.

Overview

Buttons enable rich cross-application functionality initiated from drop-in UI components, called Buttons! Buttons act as the entry point to highly-contextual, fully attributed actions across apps.

The Button SDK provides full functionality for both displaying Buttons and attributing incoming users and their transactions from the Button marketplace.

Add a Button to your app, pass it some Context and it will render & display itself. e.g...

Ride use-case with an subject-location

You'll get started with the setup of your account and first buttons by sigining up in the Dashboard.

Getting the SDK

The best way to include the Button SDK in your application is by using Gradle. In your module's build.gradle file, we need to add Button as a dependency. Button for Android is distributed via Bintray and JCenter, so you don't need to add any repositories in a standard setup. If you've set custom repositories or are having issues resolving our dependency then add jcenter() to your project's repository clauses. You can watch our repository for updates about new versions.

Repository

We highly recommend that you use our SDK with Gradle, all you need to do is make sure you have jcenter() listed as one of your app's repositories (it's there by default, but you might've changed it).

repositories {
    jcenter()
}

Including the SDK

Once you have the Button repository in your list of repositories, you can include the SDK, by adding the following line to your list of dependencies. You can see the latest version in this badge: Download , make sure you always use the latest version. We recommend that you sign up for new version notifications here: .

dependencies {
    // Add the Button SDK to your app
    compile 'com.usebutton:android-sdk:4.1.3'
    // Required for cross-app attribution, any version of the Google Play Services will work.
    compile 'com.google.android.gms:play-services-ads:8.3.0'
}

Initializing Button

To begin, we need to declare the Button Application ID in the application.manifest file.

<application
        <!-- Under the application element, your ID start with app- -->
        <meta-data android:name="com.usebutton.applicationid" android:value="YOUR-APP-ID"/>
    </application>

Note: Replace YOUR-APP-ID with your Application ID, a value like app-xxxxxxxx

Then setup Button in your Application's onCreate method.

public class MyApplication extends Application {
  @Override
  public void onCreate() {
      super.onCreate();
      // During your first implementation, we recommend you to turn on
      // logging for potential troubleshooting.
      // The logs will be under the tag 'ButtonSDK'
      // adb logcat -s ButtonSDK
      if (BuildConfig.DEBUG) {
        com.usebutton.sdk.Button.enableDebugLogging();
      }
      com.usebutton.sdk.Button.getButton(this).start();
  }
}

Note: You will need to set a custom Application class if you haven't already. More in the Android Docs

Attributing Users

You can associate all Button activity with one of your users by setting the User Identifier. This can either be your user ID, email or a stable hash of one. You can use this later to look up orders, activity and identify the user in web hooks.

Button.getButton(context).setUserIdentifier("someuser@usebutton.com");

If your application offers logout functionality, you should make sure to invoke the SDK's logout feature during your logout handler.

Button.getButton(context).logout();

Note: You will also need to set the user identifer upon completion of a user log in or sign up.

You're now set up and ready to start configuring your first Button.

Full Documenation

You can find the full documentation for the latest version of the Android SDK here: Javadoc. For historic releases, please follow links in our Release Notes History.

Sample Code

For a full sample project head over to our button-android-samples repository.

Proguard Rules

If your app is using Proguard (minifyEnabled true in your build.gradle) make sure that the proguard rules below are in effect in your rules file. This file is usually located in yourapp/proguard-rules.pro, or its location is specified in build.gradle, look for proguardFiles in your default or variant configuration (note: this can be multiple files).

-keepattributes Exceptions,InnerClasses,EnclosingMethod
-keep class com.usebutton.** { *; }
-keepclassmembers class * implements android.os.Parcelable {
    static ** CREATOR;
}
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient { public *; }

Debugging Button

If you're having trouble configuring the SDK or seeing your Button you can enable debug logging to see what's going on.

if (BuildConfig.DEBUG) {
    Button.enableDebugLogging();
}
Button.getButton(context).start();

Note: To see any initialization issues, debug logging should be enabled before starting Button. You should not ship to the Google Play Store with this enabled.

With debug logging enabled, Button will log out success or failure of the following operations:

All operations which failed (including simply not matching an action for the current context) will print with the log statement a Request ID in the format req-xxxxxxxxx. If you can't figure out why your Button isn't working then contact us and send this token to our support team; we can then investigate why things aren't working as expected.