Building your own Button UI

Take full control of the UI for Button Actions by building your own Buttons and Commerce Cards.


Note: This document is a work in progress and interfaces here may be subject to change prior to release. It does however accurately reflect the approach to accessing the data that we ourselves use to build Buttons & Commerce Cards.

Dropin Buttons provide a range of Visual Customization and can accomodate almost all uses. Should you require further flexibility you can access the underlying data that we use to build the Buttons and Commerce Cards as well as being able to invoke cards yourself. This guide will run you through the basics of building your own Button UI.

We'll begin by introducing some concepts and classes that we will use throughout this guide.


AppAction is the main class that you will use when interacting with Button data. It consists of the objects that make up the Preview and Card which we will discuss in detail later.

Getting an AppAction is simple. Create a context object as you would to populate a Button (outlined here) and call getAction() with your Button ID and a callback listener. You can find your Button ID in the Button Dashboard where you'll also find more Context code samples.

// import com.usebutton.sdk.Button;
// import com.usebutton.sdk.ButtonContext;
// import com.usebutton.sdk.Location;

final Location location = new Location("Button HQ", 40.7382752,-73.9844789);
final ButtonContext buttonHq = ButtonContext.withUserLocation(location);
Button.getButton(this).getAction("btn-your-app-id", buttonHq, new Button.ActionListener() {
    public void onAction(final AppAction action) {


    public void onNoAction() {
        // We had no AppAction available for this context, hide your UI element

Note: The AppAction class and all other classes outlined here implement Parcelable and can be passed as extras in intents. Also, it's important to note that sometimes, there's no inventory available based on the context for the Button. In such cases, we recommend hiding your UI element (see onNoAction in code snippet above).

Key Methods

Advanced Methods


The Preview object rendered as a button

The Preview object is the first component on the AppAction that you will use. It consists of an icon getIcon() (A in the image above) and a title getText() (B in the image above) and is the object used to populate the default Button in our SDK.

A preview object can have an action getAction() if there's a direct action associated with it, but in most cases the preview itself will not have a default action & you will need to either use an action from one of the Inventory items or use the built-in Commerce Card to allow the user to choose one.

If you use custom cards (see below) and the Preview object has an action you should call AppAction.invoke(Context, Preview) if shouldInvoke() returns true as this means that there's no cards associated with this action and it should be invoked directly.

Key Methods

Button Commerce Card

Once you have displayed a preview, you can choose whether to show the underlying inventory or not. If you do want to show the user inventory you can either use the built-in Button Commerce Card or create your own. To make your own, continue reading this guide.

To display the Button Commerce Card for an AppAction you can call AppAction.invoke(Context, Preview) and the user will be presented with the built-in Button Commerce Card and UI flow. A simple way to achieve a custom Button is to render the Preview yourself and to call AppAction.invoke(Context, Preview) from your OnClickListener.onClick(). The remainder of the Button flow will run from that point on (Attended Installation, deep link etc..)

Types of Cards

An AppAction will always have a preview, but from there on things can be a little different. The Card that it's designed to populate will dictate what data is available. For the purposes of this guide, there are two types of Card:

Grouped Inventory Card

AppActions that represent a grouped inventory card will return a ListBody object from getListBody(). This contains the inventory items which are available for this AppAction.

A card representing groups (New York, Boston etc...) and inventory (individual show locations)

The Header A object is available under AppAction.getHeader() and represents a heading describing the inventory.

The ListBody object B, C represents a number of inventory items and a fallback action. The inventory items are individual actions each of which can be invoked by calling AppAction.invoke(Context, Inventory).

The Footer object D can also be invoked with AppAction.invoke(Context, Footer) and is considered as an alternative or fallback action, the inventory items will be more detailed & useful for the user than the footer.


List Body Items

The ListBody object contains one or more InventoryGroup objects. The InventoryGroups are logical groups B of Inventory items C which we recommend that you reflect in your UI. If AppAction.hasGroups() return we have one or more groups with one or more inventory items.

Each group has one or more Inventory items, there's no guarantee to minimum or maximum number of items so your UI should be flexible to handle this. The inventory items can be invoked AppAction.invoke(Context, Inventory), triggering either the action or an app installation that will trigger the action after installation completes.

An inventory item.

When displaying an Inventory item, the following fields are available to you. Calling AppAction.invoke(Context, Inventory) will cause the Button SDK to invoke the action and perform an AttendedInstall if the app is not currently installed.

Product Card

Coming soon.

UI Guidelines

Commerce Partners on the Button Marketplace expect that their brand be represented appropriately and within agreed upon guidelines. Before releasing a product using the Custom Button UI, you will need to contact us at to confirm partner approval.

More details on UI Guidelines coming soon.