Quick Start on
Mobile Web

Quick Start

In this quick start guide, we'll walk through the steps needed to handle and report Button-generated traffic in your mobile website.

Estimated time to complete: About 20 minutes.

Table of contents

Button App Store

This diagram illustrates how a user comes in via a deep link and the steps needed to capture an order and attribute it to the related deep link.

Step 1: Fetch the attribution data

Use the ButtonJS Javascript library to capture the attribution data. The specific field that is relevant is the btn_ref which appears as a query parameter on the deep link.

Call the specified method in ButtonJS to capture the btn_ref.

var btn_ref = bttnio('getReferrerToken');

Step 2: POST your order to your Checkout API

Here you should follow your normal flow to capture orders and POST to your Checkout API. The only change here is to keep the btn_ref, which you acquired in step 2 above, near your order so you can later call Button with the order and the attribution data.

As an example, here is what a call to your API could look like.

// Obtain Attribution Token from step 2
var btn_ref = bttnio('getReferrerToken');

// Set parameters for POST, including Attribution Token
var parameters = {
  "btn_ref": btn_ref, // Attribution Token
  "price": 34.90,
  "location": "New York"
};

$.post("https://api.yourapi.com", parameters, function(data, status){
    console.log("Data: " + data + "\nStatus: " + status);
});

Note: You should report all orders regardless of the presence of a Button attribution token to allow seamless customer support and investigation with Loyalty & Rewards publishers.

Step 3: Report your order to Button

After you've captured the user's order in your own system, you'll need to capture the order in Button's system as well and pass along the attribution data. The details for this API can be found in the API docs. The bare minimum are the total value of the order (exclude shipping and handling, tax, promotions, credits), the currency for the item, your unique identifier for the order, the attribution data (the same btn_ref from steps 2 and 3), and use your API key for authentication. Go to your Button Dashboard to access your API key.

curl https://api.usebutton.com/v1/order \
   -X POST \
   -u your_api_key: sk-XXX \
   -d total=50 \
   -d currency=USD \
   -d order_id=1989 \
   -d btn_ref=srctok-XXX \
   -d customer[id]=mycustomer-1234 \
   -d customer[email_sha256]=39a8189797283875ae692e6198ae087c1c98 \
   -d finalization_date=2017-08-02T19:26:08Z
var client = require('@button/button-client-node')('sk-XXX');

client.orders.create({
  total: 50,
  currency: 'USD',
  order_id: '1989',
  btn_ref: 'srctok-XXX', // This is the Attribution Token POSTed from your app
  customer: {
    id: 'mycustomer-1234',
    email_sha256: '39a8189797283875ae692e6198ae087c1c98'
  }
  finalization_date: '2017-08-02T19:26:08Z'
}, function(err, res) {
  console.log(res);
});
require 'button'

client = Button::Client.new('sk-XXX')

response = client.orders.create({
  total: 50,
  currency: 'USD',
  order_id: '1989',
  finalization_date: '2017-08-02T19:26:08Z',
  btn_ref: 'srctok-XXX', # This is the Attribution Token POSTed from your app
  customer: {
    id: 'mycustomer-1234',
    email_sha256: '39a8189797283875ae692e6198ae087c1c98'
  }
})

puts response
# => Button::Response(button_order_id: btnorder-XXX, total: 50, ... )
from pybutton import Client

client = Client('sk-XXX')

response = client.orders.create({
    'total': 50,
    'currency': 'USD',
    'order_id': '1989',
    'finalization_date': '2017-08-02T19:26:08Z',
    'btn_ref': 'srctok-XXX', # This is the Attribution Token POSTed from your app
    'customer': {
        'id': 'mycustomer-1234',
        'email_sha256': '39a8189797283875ae692e6198ae087c1c98'
    }
})

print(response)
# <class pybutton.Response total: 50, currency: 'USD', ...>

Note: This is a simple example that does not include line item breakout, UPCs etc... See the API Reference for full details. Also, the total must be an integer (e.g. $123.40 is 12340) and not include shipping and handling, tax, promotions, or credits (i.e. total should be the actual value of the product or service before any adjustments).

Interactive Guide

We've put together an interactive tool that lets you make the full lifecycle of Order requests against our API and get real-time feedback and validation that we're handling everything properly.

Sign Up for an account in our dashboard and checkout the Interactive Guide to get up and running.

Button App Store

Update or delete the order

To keep the order you've captured with Button the same as on your system, you can update or delete orders.

Update

To update an order, make an API call with the unique order ID and the parameters that have changed. For example, if the total for an order has been updated, the API call would look like this:

curl https://api.usebutton.com/v1/order/<btnorder-XXX> \
   -X POST \
   -u your_api_key: sk-XXX \
   -d total=50
var client = require('@button/button-client-node')('sk-XXX');

client.orders.update('btnorder-XXX', { total: 60 }, function(err, res) {
    console.log(res);
});
require 'button'

client = Button::Client.new('sk-XXX')

response = client.orders.update('btnorder-XXX', total: 60)

puts response
# => Button::Response(button_order_id: btnorder-XXX, total: 60, ... )
from pybutton import Client

client = Client('sk-XXX')

response = client.orders.update('btnorder-XXX', {
    'total': 60,
})

print(response)
# <class pybutton.Response total: 60, currency: 'USD', ...>
Delete

To delete an order, make an API call with just the unique order ID.

curl https://api.usebutton.com/v1/order/<btnorder-XXX> \
   -X DELETE /
   -u your_api_key: sk-XXX
var client = require('@button/button-client-node')('sk-XXX');

client.orders.del('btnorder-XXX', function(err, res) {
    console.log(res);
});
require 'button'

client = Button::Client.new('sk-XXX')

response = client.orders.delete('btnorder-XXX')

puts response
# => Button::Response()
from pybutton import Client

client = Client('sk-XXX')

response = client.orders.delete('btnorder-XXX')

print(response)
# <class pybutton.Response >

Advanced features and integration docs

For more details, full integration guides, and code samples, check out the full docs.