Mobile Web Integration Guide

Enable dozens of contextual actions on your mobile web site with one simple integration.

Overview

Buttons are dynamic, contextual slots on your page that offer your users contextual actions. To add Buttons to your page, you simply need to include a lightweight JavaScript snippet and decorate some nodes with Button metadata where you want Buttons to appear.

Create A Mobile Web Button

Before you can add Buttons to your page, you need to apply some light configuration in our developer dashboard. For adding Buttons on the web, click "Add a Button" in the left navigation bar. You can associate this Button with a Mobile Web Application you've already created or create a new one. Select the app you want to link to and save your Button.

Add Button To Your Page

The best way to include the ButtonJS JavaScript Library in your page(s) is to include the following snippet at the bottom of the page, right before the closing </body> tag. ButtonJS is loaded asynchronously and will not impact the initial loading of your page.

<script>
(function(u,s,e,b,t,n){u['__bttnio']=b;u[b]=u[b]||function(){(u[b].q=u[b].q||[]).push(arguments)};t=s.createElement(e);n=s.getElementsByTagName(e)[0];t.async=1;t.src='https://web.btncdn.com/v1/button.js';n.parentNode.insertBefore(t,n)})(window, document, 'script', 'bttnio');
</script>

Grab your application ID from the dashboard and expose it in a global variable called ButtonWebConfig, like so:

window.ButtonWebConfig = {
  applicationId: 'app-XXXXXXXX'
};

Alternatively, use the "Get Code" button in the dashboard to get a full snippet you can copy and paste.

Click here to see all configuration options

Render Your Button

Buttons are dynamic slots on your website – given the appropriate context, your Button can surface actions for your users to take. Similarly, if there is no contextually relevant action available, no Button will be shown. To render a Button at a particular place in a page, we declare a DOM node using the data-bttnio-id attribute:

<div data-bttnio-id="btn-XXXXXXXXXXXX" />

In this example, we use a div as our container. The most important piece is to provide the data-bttnio-id, which is the ID of the Button you configured in the Dashboard above.

Providing context to your Button can be done two ways. The first is to simply provide a JSON blob as the data-bttnio-context attribute of the DOM node:

<div data-bttnio-id="btn-XXXXXXXXXXXX"
     data-bttnio-context='{"subject_location": ... }' />

Alternatively, you can provide a mapping of Button ID to context objects in your defaults configuration, like so:

// Sample context for a theoretical trip from Barclays to Button
ButtonWebConfig.defaults = {
  'btn-xxxxxx' {
    context: {
      subject_location: {
        latitude: '40.738275',
        longitude: '-73.982285',
        name: 'Button HQ'
      },
      user_location: {
        latitude: '40.684178',
        longitude: '-73.975168',
        name: 'Barclays Center'
      }
    }
  }
};

NOTE: You still need to provide the data-bttnio-id field on the div

NOTE: Context declared on the data-bttnio-context DOM attribute will take precedence over context found in defaults

Dynamic Pages

When the Button JS loads, it will detect any Button slots on the page it needs to fill out. If the DOM is going to change during the lifecycle of the page in a way that could create new Buttons, simply tell Button to refresh itself:

bttnio('refresh')

Advanced Configuration

Custom UI Buttons

If you want more control over how, when, and where your Button(s) will render, you can use ButtonJS in UI-less mode by setting ButtonWebConfig.noUI to true and manually calling refresh to request Buttons:

window.ButtonWebConfig = {
  applicationId: 'app-xxxx',
  noUI: true
};

bttnio('refresh', function(success, buttons) {
  // buttons is an array of Button objects that you can use
  // to render your own Button UI
});

NOTE: You still need to perform the standard configuration steps outlined above to specify your Button IDs and context.

Inline Inventory Buttons

Buttons are capable of showing relevant inventory for a merchant's goods or services right from within your page. Buttons can display a list of inventory (like menu items or nearby hotels) in two ways: a modal (we call it a Commerce Card) or inline in a horizontally-scrollable container. They look something like this:

If a Button on your page is currently being displayed as a list of items within a Commerce Card, you can try out the inline style by adding data-bttnio-inventory-mode="inline" as an attribute on the Button's DOM node (the default for inventory mode is "card"):

<div data-bttnio-id="btn-XXXXXXXXXXXX"
     data-bttnio-context='{"subject_location": ... }'
     data-bttnio-inventory-mode="inline" />

Alternatively, the inventory mode can be specified as a part of the global config:

window.ButtonWebConfig.defaults = {
  'btn-XXXXXXXXXXXX': {
    inventoryMode: 'inline'
  }
}

NOTE: data-bttnio-inventory-mode declared on the DOM attribute will take precedence over inventoryMode found in defaults

Debugging

If you're having any trouble getting Button set up, you can enable some helpful debug logging by setting ButtonWebConfig.enableLogging to true.