Integrate the Button SDK on
Android

Integrate the Button SDK

This guide details how to fully integrate the Button SDK into your Android application. The SDK captures the user for attribution and allows Button to properly affiliate commissions and user rewards. This guide will go over how to add the SDK, how to initialize the SDK, and how to render a Button.

Add the Button 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.

Allow JFrog bintray access to your project's build.gradle file.

allprojects {
    repositories {
        jcenter()
    }
}

Then, add the Button SDK to your dependencies in your app's build.gradle file. Here is an example of what it will look like:

dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
    androidTestCompile('com.android.support.test.espresso:espresso-core:2.2.2', {
        exclude group: 'com.android.support', module: 'support-annotations'
    })
    compile 'com.android.support:appcompat-v7:25.0.1'
    testCompile 'junit:junit:4.12'

    // Button SDK
    compile 'com.usebutton:android-sdk:5.7.0' // I was added!
}

Initialize the Button SDK

To initialize a Button in your app, your application ID is needed, which can be found in the Button Dashboard. If you're a loyalty Publisher, you must attribute your users' IDs through Button

AndroidManifest.xml file

Add the Button SDK within the application tag. Your application ID found in the Dashboard.

<application

    <activity
      <!-- your activities  -->
    </activity>

    <!--Button SDK-->
    <meta-data android:name="com.usebutton.applicationid" android:value="YOUR_BUTTON_APP_ID"/>
</application>

MainActitivty.java file

Import the Button SDK at the top of the file.

import com.usebutton.sdk.Button;
import com.usebutton.sdk.ButtonContext;
import com.usebutton.sdk.ButtonDropin;
import com.usebutton.sdk.LineItem;
import com.usebutton.sdk.context.Location;
import com.usebutton.sdk.util.LocationProvider;

In your Application's onCreate() method, configure Button.

public class MyApplication extends Application {
  @Override
  public void onCreate() {
      super.onCreate();

      // Required if you're a loyalty Publisher. Replace with user's unique user ID.
      Button.getButton(context).setUserIdentifier("<#YOUR_USER_ID#>");

      if (BuildConfig.DEBUG) {
        com.usebutton.sdk.Button.enableDebugLogging();
      }
      com.usebutton.sdk.Button.getButton(this).start();
  }
}

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 identifier upon completion of a user log in or sign up.


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 *; }

Render a Button

Buttons are rendered in the Layout XML and the Java file that handles your views. Your particular Button code will vary depending on which Merchant action you're adding to your Button. Some require specific information about the Merchant while others require user location or venue location. This is called Button context. For more information on context, see this guide.

Layout XML

The easiest way to add a Button is to add it to the layout of an Activity or Fragment in XML.

<com.usebutton.sdk.ButtonDropin
        xmlns:button="http://schemas.android.com/apk/res-auto"
        android:layout_width="match_parent"
        android:id="@+id/main_dropin"
        android:layout_height="60dp"
        button:btn_buttonId="<#YOUR_BUTTON_ID#>"
        />

Determining Button availability

After you've setup Button you can determine if we will render a Button in a few ways, so you can control e.g. your UI visibility. For your convenience we provide two ways of doing this, either by using the global Button singleton or any ButtonDropin view instance, they are functionally identical.

By using the Button object:

Button.getButton(this).start();
final ButtonContext context = ButtonContext.withSubjectLocation(new Location("Button HQ", 40.7382752, -73.9822849));
context.withUserLocation(new Location("Union Sq", 40.7359168, -73.990408));
Button.getButton(this).willDisplayButton("YOUR-BUTTON-ID", context, new ButtonDropin.Listener() {
    @Override
    public void onPrepared(final boolean willDisplay) {
        Log.d("ButtonApp", "Will display button: " + willDisplay);
    }

    @Override
    public void onClick(final ButtonDropin dropin) {
      Log.d("ButtonApp", "Button clicked.");
    }
});

Or on the ButtonDropin you added to your layout:

final ButtonContext context = ButtonContext.withSubjectLocation(new Location("Button HQ", 40.7382752, -73.9822849));
context.withUserLocation(new Location("Union Sq", 40.7359168, -73.990408));
ButtonDropin dropin = (ButtonDropin) findViewById(R.id.my_dropin);
// Either:
dropin.prepareForDisplay(context, new ButtonDropin.Listener() {
    @Override
    public void onPrepared(final boolean willDisplay) {
        Log.d("ButtonApp", "Will display button: " + willDisplay);
    }

    @Override
    public void onClick(final ButtonDropin dropin) {
      Log.d("ButtonApp", "Button clicked.");
    }
});
// Or by setting a permanent listener on your view
dropin.setListener(new ButtonDropin.Listener() {
    @Override
    public void onPrepared(final boolean willDisplay) {
        Log.d("ButtonApp", "Will display button: " + willDisplay);
    }

    @Override
    public void onClick(final ButtonDropin dropin) {
      Log.d("ButtonApp", "Button clicked.");
    }
});

Java view file

At the top of the file, import the Button SDK.

import com.usebutton.sdk.Button;
import com.usebutton.sdk.ButtonContext;
import com.usebutton.sdk.ButtonDropin;
import com.usebutton.sdk.LineItem;
import com.usebutton.sdk.context.Location;
import com.usebutton.sdk.util.LocationProvider;

The rest of this section is broken down by vertical and Merchant. For each Merchant is the context required to render a Button.

Cleaning
Handy
// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final Location location = new Location(<#latitude#>, <#longitude#>);
final ButtonContext context = ButtonContext.withSubjectLocation(location);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);
Deals
Groupon
// Coming soon
Delivery
Delivery Hero
Restaurant location
// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final Location location = new Location(<#latitude#>, <#longitude#>);
location.addIdentifier("deliveryhero", "<#RESTAURANT_NAME#>");
final ButtonContext context = ButtonContext.withSubjectLocation(location);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);

Top restaurants nearby
// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final ButtonContext context = ButtonContext();
final android.location.Location location = new LocationProvider(this).getBestLocation();
if (location == null) {
    final Location location = new Location(<#latitude#>, <#longitude#>);
}
context.setUserLocation(location);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);
Drizly
User location
// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final ButtonContext context = ButtonContext();
final android.location.Location location = new LocationProvider(this).getBestLocation();
if (location == null) {
    final Location location = new Location("<#Location Name#>", <#latitude#>, <#longitude#>);
}
context.setUserLocation(location);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);

Subject location
// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final Location location = new Location("<#Location Name#>", <#latitude#>, <#longitude#>);
final ButtonContext context = ButtonContext.withSubjectLocation(location);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);
delivery.com
Venue ID

For information on how to find the Venue ID, see this guide.

// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final Location location = new Location("<#Location Name#>", <#latitude#>, <#longitude#>);
location.addIdentifier("deliverydotcom", "<#VENUE_ID#>");
final ButtonContext context = ButtonContext.withSubjectLocation(location);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);

User location
// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final ButtonContext context = ButtonContext();
final android.location.Location location = new LocationProvider(this).getBestLocation();
if (location == null) {
    final Location location = new Location("<#Location Name#>", <#latitude#>, <#longitude#>);
}
context.setUserLocation(location);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);
Caviar

Contact us to add this partner.

User location
// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final ButtonContext context = ButtonContext();
final android.location.Location location = new LocationProvider(this).getBestLocation();
if (location == null) {
    final Location location = new Location("<#Location Name#>" ,<#latitude#>, <#longitude#>);
}
context.setUserLocation(location);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);

Venue ID

For information on how to find the Venue ID, see this guide.

// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final Location location = new Location("<#Location Name#>", <#latitude#>, <#longitude#>);
location.addIdentifier("caviar", "<#VENUE_ID#>");
final ButtonContext context = ButtonContext.withSubjectLocation(location);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);
DoorDash

Contact us to add this partner.

Direct link
// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final ButtonContext context = ButtonContext();

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);
Dining
Quandoo
Specific restaurant

For information on how to find the Venue ID, see this guide.

// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final Location location = new Location("<#Location Name#>", <#latitude#>, <#longitude#>);
location.addIdentifier("quandoo", "<#VENUE_ID#>");
final ButtonContext context = ButtonContext.withSubjectLocation(location);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);

Top restaurants nearby
// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final ButtonContext context = ButtonContext();
final android.location.Location location = new LocationProvider(this).getBestLocation();
if (location == null) {
    final Location location = new Location("<#Location Name#>", <#latitude#>, <#longitude#>);
}
context.setUserLocation(location);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);
Resy
User location
// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final ButtonContext context = ButtonContext();
final android.location.Location location = new LocationProvider(this).getBestLocation();
if (location == null) {
    final Location location = new Location("<#Location Name#>", <#latitude#>, <#longitude#>);
}
context.setUserLocation(location);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);

Venue ID
// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final Location location = new Location("<#Location Name#>", <#latitude#>, <#longitude#>);
location.addIdentifier("resy", "<#VENUE_ID#>");
final ButtonContext context = ButtonContext.withSubjectLocation(location);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);
OpenTable

Contact us to add this partner.

Specific restaurant
// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final Location location = new Location("<#Location Name#>", <#latitude#>, <#longitude#>);
location.addIdentifier("opentable", "<#RESTAURANT_ID#>");
final ButtonContext context = ButtonContext.withSubjectLocation(location);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);

User location
// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final ButtonContext context = ButtonContext();
final android.location.Location location = new LocationProvider(this).getBestLocation();
if (location == null) {
    final Location location = new Location("<#Location Name#>", <#latitude#>, <#longitude#>);
}
context.setUserLocation(location);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);
E-commerce
Spring

Contact us to add this partner.

Specific item
// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final ButtonContext context = ButtonContext();
context.addItem("spring", "<#spring_item_identifier#>");

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);

iTunes

Contact us to add this partner.

For information on how to find the Venue ID, see this guide.

// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final ButtonContext context = ButtonContext();
context.addItem("iTunes", "<#artist_identifier#>");

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);
Apple Retail

Contact us to add this partner.

Direct link
// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final ButtonContext context = ButtonContext();

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);
eBay

Contact us to add this partner.

// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final ButtonContext context = ButtonContext();

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);
Boxed

Contact us to add this partner.

// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final ButtonContext context = ButtonContext();

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);  
BloomThat

Contact us to add this partner.

// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final ButtonContext context = ButtonContext();

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);  
Jet

Contact us to add this partner.

Specific item

For information on how to find the Venue ID, see this guide.

// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final ButtonContext context = ButtonContext();
context.addItem("jet", "<#jet_item_identifier#>");

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);
Health & Beauty
Zeel
// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final ButtonContext context = ButtonContext();
final android.location.Location location = new LocationProvider(this).getBestLocation();
if (location == null) {
    final Location location = new Location("<#Location Name#>", <#latitude#>, <#longitude#>);
}
context.setUserLocation(location);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);
Glamsquad
// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final ButtonContext context = ButtonContext();
final android.location.Location location = new LocationProvider(this).getBestLocation();
if (location == null) {
    final Location location = new Location("<#Location Name#>", <#latitude#>, <#longitude#>);
}
context.setUserLocation(location);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);
Tickets
Ticketmaster
Ticketmaster artist name and ID
// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final ButtonContext context = ButtonContext();
final Location location = new Location("<#Location Name#>", <#latitude#>, <#longitude#>);
context.setSubjectLocation(location);
final MusicArtist musicArtist = new MusicArtist("<#ARTIST_NAME#>");
context.setArtist(musicArtist);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);

Venue ID

For information on how to find the Venue ID, see this guide.

// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final Location location = new Location("<#Location Name#>", <#latitude#>, <#longitude#>);
location.addIdentifier("ticketmaster", "<#VENUE_ID#>");
final ButtonContext context = ButtonContext.withSubjectLocation(location);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);

Goldstar

Contact us to add this partner.

User location
// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final ButtonContext context = ButtonContext();
final android.location.Location location = new LocationProvider(this).getBestLocation();
if (location == null) {
    final Location location = new Location("<#Location Name#>", <#latitude#>, <#longitude#>);
}
context.setUserLocation(location);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);
Transportation
Uber
Subject location
// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final Location location = new Location("<#Location Name#>", <#latitude#>, <#longitude#>);
final ButtonContext context = ButtonContext.withSubjectLocation(location);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);

User location
// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final ButtonContext context = ButtonContext();
final android.location.Location location = new LocationProvider(this).getBestLocation();
if (location == null) {
    final Location location = new Location(<#latitude#>, <#longitude#>);
}
context.setUserLocation(location);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);

Subject and user location
// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final Location subjectLocation = new Location("<#Location Name#>", <#latitude#>, <#longitude#>);
final ButtonContext context = ButtonContext.withSubjectLocation(subjectLocation);
final android.location.Location userLocation = new LocationProvider(this).getBestLocation();
if (userLocation == null) {
    final Location userLocation = new Location("<#Location Name#>", <#latitude#>, <#longitude#>);
}
context.setUserLocation(location);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);

Parking Panda
// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final Event event = new Event("<#Event Name#>");
event.setStart(<#START_DATE#>);
event.setEnd(<#END_DATE#>);
final Location location = new Location("<#Location Name#>", <#latitude#>, <#longitude#>);
event.setLocation(location);
final ButtonContext context = ButtonContext.withEvent(event);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);
Travel
Hotels.com
Specific hotel

For information on how to find the Venue ID, see this guide.

// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final Location location = new Location("<#Location Name#>", <#latitude#>, <#longitude#>);
location.addIdentifier("hotelsdotcom", "<#HOTEL_ID#>");
final ButtonContext context = ButtonContext.withSubjectLocation(location);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);

User location
// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final ButtonContext context = ButtonContext();
final android.location.Location location = new LocationProvider(this).getBestLocation();
if (location == null) {
    final Location location = new Location(<#latitude#>, <#longitude#>);
}
context.setUserLocation(location);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);
HotelTonight

Contact us to add this partner.

Specific hotel
// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final Location location = new Location("<#Location Name#>", <#latitude#>, <#longitude#>);
location.addIdentifier("hoteltonight", "<#HOTEL_ID#>");
final ButtonContext context = ButtonContext.withSubjectLocation(location);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);

User location
// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final ButtonContext context = ButtonContext();
final android.location.Location location = new LocationProvider(this).getBestLocation();
if (location == null) {
    final Location location = new Location(<#latitude#>, <#longitude#>);
}
context.setUserLocation(location);

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);
Airbnb

Contact us to add this partner.

// Get the Button View
final ButtonDropin buttonDropin = (ButtonDropin)this.findViewById(R.id.button_dropin_id);

// Setup your context
final Journey journey = new Journey();
journey.setStart(<#start_date#>);
journey.setEnd(<#end_date#>);

final Location startLocation = new Location("<#Location Name#>", <#latitude#>, <#longitude#>);
journey.setStartLocation(startLocation)

final Location destination = new Location("<#Location Name#>", <#latitude#>, <#longitude#>);
journey.setDestinationLocation(destination)

// Prepare the Button for display with our context
buttonDropin.prepareForDisplay(context);