Using Button Actions on

Using Button Actions

Buttons provide relevant actions to your users, complete with a corresponding UI. Buttons can be configured with one or more Merchants that they can offer to your users.

View Controller


Dashboard Configuration

The first step is to create a Button in the Dashboard and configure it to point to the Uber Merchant.

  • Create a Button in your iOS App
  • Configure the Button to use the "Uber" Merchant
  • Note the Button ID for your newly created Button (it will look like this: btn-xxxxxxxxxxxxx)

View Controller


When you've configured your Button, come back to this guide and complete the rest of the steps.


Add the Button SDK

Button Actions are a feature of the Button SDK, if you haven't already, complete the Button SDK Getting Started guide.


Add a Button to your View

The easiest way to add a Button to your view is using a Storyboard or Xib in the Xcode Interface Builder.

  1. Drag and drop a View into the Controller it belongs in on the canvas
  2. Set the class on the View to be BTNDropinButton
  3. While holding the Control key, click and drag the 'View' into its respective view controller
  4. Assign it as an outlet connection, weak storage, and call it dropinButton

View Controller

In your ViewController class, create an instance of BTNDropinButton and add it to the self.view outlet.

import Button

strong var dropinButton: BTNDropinButton!

override func viewDidLoad() {
    super.viewDidLoad()

    self.dropinButton = BTNDropinButton()
    self.view.addSubview(self.dropinButton)
}

#import <Button/Button.h>

@property (nonatomic, strong) BTNDropinButton *dropinButton;

@end

- (void)viewDidLoad {
  [super viewDidLoad];

  self.dropinButton = [[BTNDropinButton alloc] init];
  [self.view addSubview:self.dropinButton];
}

Using a Button in a Table View

Table view Buttons are Buttons that live within a table view. You may want to add a Button this way if you have multiple items to display on a page.

Storyboard

The easiest way to add a table view Button to your view is to do so through the Storyboard.

  1. Drag and drop a 'Table View' onto your canvas
  2. Drag and drop a 'Table View Cell' into the 'Table View' you just added
  3. Assign it a custom class of BTNDropinButtonCell
  4. Assign it the identifier 'button-cell'

View Controller

Programmatically

override func viewDidLoad() {
    super.viewDidLoad()

    self.tableView.registerClass(BTNDropinButtonCell.self, forCellReuseIdentifier: "button-cell")
}
- (void)viewDidLoad {
    [super viewDidLoad];

    [self.tableView registerClass:[BTNDropinButtonCell class] forCellReuseIdentifier:@"button-cell"];
}

In your table view data source, you'll need to prepare your Button cell in cellForRowAtIndexPath:

override func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {

    let dataItem = dataItems[indexPath.row]
    let identifier = dataItem.cellIdentifier
    let cell = tableView.dequeueReuseableCell(withIdentifier: identifier, for: indexPath)

    if let buttonCell = cell as? BTNDropinButtonCell {
        Button.shared().fetchAppAction(withButtonId: "<#YOUR_BUTTON_ID#>", context: context) { appAction, error in
            if let appAction = appAction {
                buttonCell.prepare(with: appAction)
            }
            else if let error = error {
                print("Fetch App Action Error: \(error.localizedDescription)")
            }
        }
    }

    return cell
}
- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath {

    DataItem *dataItem    = self.dataItems[indexPath.row];
    NSString *identifier  = dataItem.cellIdentifier;

    UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:identifier forIndexPath:indexPath];

    if ([cell isKindOfClass:[BTNDropinButtonCell class]]) {
        BTNDropinButtonCell *buttonCell = (BTNDropinButtonCell *)cell;

        [[Button sharedButton] fetchAppActionWithButtonId:@"<#YOUR_BUTTON_ID#>"
                                                  context:context
                                               completion:
        ^(BTNAppAction *appAction, NSError *error) {
            if (appAction) {
                // Prepare Button with fetched App Action.
                [buttonCell prepareWithAppAction:appAction];
            } else if (error) {
                // Uh-oh, something went wrong.
                NSLog(@"Fetch App Action Error: %@", error.localizedDescription);
            } else {
                // If `appAction` and `error` are equal to nil, there's no App Action for provided context.
                NSLog(@"Fetch App Action: There's no App Action available.");
            }
        }];
    }
}

Load the action for your Button

Buttons work by fetching an Action from the Button API based on a user's Context. For example, if a user is at a location that Uber can pick up at, the Button will become an Uber Button.

We will pass only one element in Context:

  • Location

You can then set this Action on a BTNDropinButton and it will render itself appropriately.

import Button

override func viewDidLoad() {
    super.viewDidLoad();

    // Set up your context
    let location = BTNLocation(name: "<#Location Name#>", latitude: <#lat#>, longitude: <#long#>)
    let context  = BTNContext(subjectLocation: location)

    // Replace YOUR_BUTTON_ID with your Button ID from the Button Dashboard https://app.usebutton.com
    Button.shared().fetchAppAction(withButtonId: "<#YOUR_BUTTON_ID#>", context: context) { appAction, error in
        if appAction != nil {
            self.dropinButton.prepare(with: appAction)
        } else {
            // In the unlikely event of an error, fall back to original action.
        }
    }
}
@import Button;

- (void)viewDidLoad {
    [super viewDidLoad];

    // Set up your context
    BTNLocation *location = [BTNLocation locationWithName:@"<#Location Name#>" latitude:@"<#lat#>" longitude:@"<#long#>"];
    BTNContext *context = [BTNContext contextWithSubjectLocation:location];

    // Replace YOUR_BUTTON_ID with your Button ID from the Button Dashboard https://app.usebutton.com
    [[Button sharedButton] fetchAppActionWithButtonId:@"<#YOUR_BUTTON_ID#>" context:context completion:^(BTNAppAction *appAction, NSError *error) {
        if (appAction) {
            [self.dropinButton prepareWithAppAction:appAction];
        } else {
            // In the unlikely event of an error, fall back to original action.
        }
    }];
}

Now you should have a simple Uber Button in your app!

View Controller


Use other Merchant Actions

This guide uses Uber as a Merchant. If you're adding a different Merchant with Button, see this guide for Context to pass to the Button SDK.


Determining Button availability

If you need to know whether or not a Button will be rendered before actually preparing the Button, you can do so with the following method:

Button.shared().willDisplay(withId: "btn-xxxxxxxxxxx", context: context, completion: { isDisplayable in
    if (isDisplayable) {
      // An action is available for this button and context.
    }
})
[[Button sharedButton] willDisplayButtonWithId:@"btn-xxxxxxxxxxx"
                                       context:context
                                    completion:^(BOOL willDisplay) {
    if (willDisplay) {
        // An action is available for this button and context.
    }
}];

Note: Only use this method if you have some layout requirements that depend on the availability of a Button. You'll need to pass the same context that you'll be using to prepare the Button later or you may get a different result.