Add a Button

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

Creating your first Button

All Button functionality is surfaced by adding a ButtonDropin view to a screen and allowing it to present itself.

Adding to Layout XML

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

Add a Button to the view hierarchy where it should appear, replacing YOUR-BUTTON-ID with an ID from the Button dashboard (a value like btn-xxxxxxxx), you can setup a Button here: Add Button.

<com.usebutton.sdk.ButtonDropin
        xmlns:button="http://schemas.android.com/apk/res-auto"
        android:layout_width="match_parent"
        android:layout_height="60dp"
        button:btn_buttonId="YOUR-BUTTON-ID"
        />

Context

The last thing you need to do to see your Button is pass it some context.

Context describes the state of the screen & app that the Button is embedded in. It gives the Button information about what venue / item the user is looking at, the location of the venue & much more. For our getting a ride use-case, we want to at least tell the Button where we want to go.

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

// We have a screen describing a location or point of interest
final Location location = new Location("Button HQ", 40.7382965, -73.9823084);
final ButtonContext context = ButtonContext.withSubjectLocation(location);

// Let's also provide the user's location if we have the permission to
final android.location.Location userLocation = new LocationProvider(this).getBestLocation();
if (userLocation != null) {
    context.setUserLocation(userLocation);
}

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

That's it! You're Button should now appear if there's buttons available for the context and button ID you provided.

Seeing your Button

Now, run your project. Provided that your Button is configured in the Button Dashboard (or have been assigned a button ID by our team), you should see your first Button.

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.");
    }
});

Visual Customization

Buttons are rendered on the fly, but there is still room for customization. Maybe you need to change the size of the icon to match your other icons, or bump the left margin over ever so slightly. You can easily adjust the look of your Button using appearance attributes on the Button view.

Now, for what each of those things means..

Item Appearance Attribute Default Purpose
A android:paddingLeft 3dp Inset all Button content.
B button:btn_iconSize Image size The size of the image on the Button.
A,C,D,E button:btn_drawablePadding 5dp The padding between the image and other elements
A button:btn_drawablePaddingLeft 5dp The padding between the image and other elements, left side
D button:btn_drawablePaddingTop 5dp The padding between the image and other elements, top
C button:btn_drawablePaddingRight 5dp The padding between the image and other elements, right side
E button:btn_drawablePaddingBottom 5dp The padding between the image and other elements, bottom
C button:btn_padding 5dp The padding between the button's outline and its text and icon. You can control the individual paddings with button:btn_paddingLeft, button:btn_paddingTop, button:btn_paddingRight, button:btn_paddingBottom.
D android:paddingTop 5dp Inset all Button content from the top.
E android:paddingBottom 5dp Inset all Button content from the Bottom.
F android:background System default Container view background, can have padding too if e.g. a 9-patch.

Open this page in a desktop browser to see the full configuration table

<com.usebutton.sdk.ButtonDropin
    xmlns:button="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="60dp"
    android:id="@+id/button_dropin"
    android:padding="5dp"
    button:btn_buttonId="YOUR-BUTTON-ID"
    button:btn_textSize="20sp"
    button:btn_textColor="@color/button_text_color"
    button:btn_backgroundDrawable="@android:drawable/btn_default_small"
    button:btn_backgroundColor="#ffffff"
    button:btn_drawablePadding="15dp"
    button:btn_padding="5dp"
    button:btn_paddingRight="10dp"
    button:btn_paddingLeft="10dp"
    button:btn_iconColor="@color/button_icon_color"
    button:btn_iconSize="20dp"
    button:btn_gravity="right|center_vertical"
    button:btn_textStyle="lower"
    button:btn_font="Lobster-Regular.ttf"
    />

You can set any of these on your Button in the layout XML. For a complete list of supported styling attributes, see the documentation for ButtonDropin.