SDK Reference on
All Platforms

SDK Reference

Public Methods

All ButtonJS method calls are performed by passing the method name to the global bttnio object as a string, with any additional arguments after that. For example:

// No arguments
bttnio('refresh');

// Arguments
bttnio('reportEvent', 'buy-things', { numberOfThings: 10 });

refresh

Trigger a re-evaluation of the page for any Button slots that need to be filled.

Arguments

  • callback: Function (optional) - If provided, a function to execute upon completion or termination of the API call to fetch available actions. The function receives two arguments: the first is a boolean indicating if the request was successful, and the second is an array of all of the successfully matched Buttons from the request.
bttnio('refresh', function(didSucceed, actions) {
  // Optional callback
});

reportEvent

Report the occurrence of a user event to Button.

Arguments

  • name: string - The name of the event (e.g. user-leveled-up).
  • data: Object - Key-value pairs to add detail to the event.
  • callback: Function (optional) - If provided, a function to execute upon completion or termination of the event reporting API call. The function receives a single boolean argument indicating if the request succeeded or not.
bttnio('reportEvent', 'select-product', { id: '12b' }, function(didSucceed) {
  // Optional callback
});

getReferrerToken

Obtain the attribution token for reporting orders to Button's API. Fore more information on order reporting, check out this guide.

bttnio('getReferrerToken');

logout

Revoke the user's current Button session. This method should be invoked any time your user logs out of your own system to ensure that Button sessions aren't reused for multiple users.

bttnio('logout');

Configuration Options

The following properties can be set on the window.ButtonWebConfig object to alter the behavior of the ButtonJS library:

applicationId

Type: string Required

The ID assigned for your mobile website by Button

defaults

Type: object

A mapping of default configuration options for any Button on a page. Each key in defaults should be a Button ID (btn-XXXX) and the value an object with any of the following keys:

  • context: A Context Object
  • inventoryMode Either "inline" or "card", defaults to "card"

For example:

window.ButtonWebConfig.defaults = {
    'btn-XXX': {
        inventoryMode: 'inline'
    },
    'btn-YYY': {
        inventoryMode: 'inline',
        context: {
            subject_location: { city: "San Francisco" }
        }
    }
}

enableLogging

Type: boolean

If set to true, Button will produce logging output in the browser console to help debug any issues encountered during integration. Default: false.

userIdentifier

Type: string|number

Associate your user's Button session with a unique identifier from your system, such as user ID or email.

noUI

Type: boolean

If set to true, Button will not automatically fetch and render any Buttons on page load. Using this mode will grant greater control but will require you to specify when, how, and where the Button will render. Matched Buttons will be returned as the second parameter to the refresh callback.


DOM Configuration Attributes

The following data- attributes can be declared directly on a Button DOM node (any node which is already declared with a data-bttnio-id attribute). They always take precedence over any window.ButtonWebConfig.defaults config.

data-bttnio-context

Type: string

Context to provide for the Button, as a JSON.stringifyd representation of the Context object

If not defined, defaults to any context declared in window.ButtonWebConfig.defaults['btn-XXX'].context.

data-bttnio-inventory-mode

Type: string

Default: "card"

The display mode for a Button that renders a list of inventory. May be "inline" or "card"

If not defined, defaults to window.ButtonWebConfig.defaults['btn-XXX'].inventoryMode or "card".