Building your own Button UI

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

Overview

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.

App Action

BTNAppAction 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 a BTNAppAction is simple. Create a context object as you would to populate a Button (outlined here) and call fetchAppActionWithButtonId:context:completion: with your Button ID and a callback handler. You can find your Button ID in the Button Dashboard where you'll also find more Context code samples.

// @import Button;

BTNLocation *venue = [BTNLocation locationWithName:@"Parm" latitude:40.723027 longitude:-73.9956459];
BTNContext *context = [BTNContext contextWithSubjectLocation:venue];

[[Button sharedButton] fetchAppActionWithButtonId:@"YOUR-BUTTON-ID" context:context completion:^(BTNAppAction *appAction, NSError *error) {
  if (appAction && !error) {
    // You have an AppAction ready to display
  } else {
    // hide your UI element
  }
}];

Note: Sometimes, there's no inventory available based on the context for the Button. In such cases, we recommend hiding your UI element (see else in code snippet above).

Key Methods

Advanced Methods


Preview

The BTNPreview object rendered as a button

The Preview object is the first component on the BTNAppAction that you will use. It consists of an icon -iconImage.URL (A in the image above) and a title -labelText.text (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 (invokePreviewAction on BTNAppAction) 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.

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 a BTNAppAction you can call -invokePreviewAction 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 -invokePreviewAction from the onTouchUpInside event from your control. The remainder of the Button flow will run from that point on (Attended Installation, deep link etc..)


Types of Cards

An App Action 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

BTNAppActions that represent a grouped inventory card will return an array of one or more BTNGroup objects from -groups. This contains the inventory items which are available for this BTNAppAction.

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

The BTNHeader A object is available as -header and represents a heading describing the inventory.

The BTNGroup object B represents a number of inventory items C. The inventory items are individual actions each of which can be invoked by calling BTNAppAction -invokeActionForListItem:.

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


Inventory Items

BTNGroups are logical groups B of BTNListItems C which we recommend that you reflect in your UI. If BTNAppAction -groups returns one or more groups there is inventory available.

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 BTNAppAction -invokeActionForListItem:, 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 BTNAppAction -invokeActionForListItem: 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 support@usebutton.com to confirm partner approval.

More details on UI Guidelines coming soon.