SDK Reference on
Mobile Web

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

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


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


  • 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


Report the occurrence of a user event to Button.


  • 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


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



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.


Configuration Options

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


Type: string Required

The ID assigned for your mobile website by Button


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" }


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.


Type: string|number

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


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.


Type: Function

This function is called after the initial Button load. It receives a single boolean argument, representing if the current platform is supported by Button. You could use this to conditionally request location access from the user if the platform is supported.


Type: Function

This function is called after any Button load and will be passed an array of all Button objects that were matched during the request.


Type: string

If you use Adobe site catalyst with a non-standard global name (the default is 's'), use this to tell Button where to find the site catalyst object. This is necessary because site catalysts intercepts links, which prevents universal linking.


Type: boolean

If true, Button will attempt to automatically enhance any Merchant links on the page. For more information, see this guide.


Type: string

If you only want Button to consider certain nodes for link enhancement, specify a valid CSS selector to target those nodes.

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.


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.


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".