Quick Start on

Quick Start

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

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: Pass the deeplink to the SDK

Setup the SDK to route all your deeplinks through it. That way it can grab the attribution data when it is passed along a deep link.

import Button

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions:
   [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    Button.shared().configure(withApplicationId: "<#APPLICATION_ID#>", userId: <#USER_ID#>) {
        error, targetURL in

        // Handle the targetURL and open the relevant content.
    }
    return true
}
@import Button;

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

  [[Button sharedButton] configureWithApplicationId:@"<#APPLICATION_ID#>" userId:<#your user Id or nil#> completion:
  ^(NSError *error, NSURL *targetURL) {

    // Handle the targetURL and open the relevant content.
  }];

  return YES;
}

Step 2: Fetch the attribution data

Use the SDK 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 the Button SDK to capture the btn_ref. Note: you should never store this value and should always access it from Button when it is needed.

if let btn_ref = Button.shared().referrerToken() {
    // referred token is present
}
NSString *btn_ref = [[Button sharedButton] referrerToken] ?: @"No Referrer Token";

Step 3: 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. Note: you should never store this value and should always access it from Button when it is needed.

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

// Obtain Attribution Token from step 2
if let btn_ref = Button.shared().referrerToken() {
    // referred token is present
}

// Set parameters for POST, including Attribution Token
let parameters: Parameters = [
    "btn_ref": btn_ref, // Attribution Token
    "price": 34.90,
    "location": "New York"
]

// Perform POST request
Alamofire.request("https://api.yourapi.com", method: .post, parameters: parameters, encoding: JSONEncoding(options: []))
// Obtain Attribution Token from step 2
NSString *btn_ref = [[Button sharedButton] referrerToken] ?: @"No Referrer Token";

// Set parameters for POST, including Attribution Token
NSDictionary *parameters = @[
    @"btn_ref": btn_ref, // Attribution Token
    @"price": @(34.90),
    @"location": @"New York"
]

// Perform POST request
[sessionManager POST:@"https://api.yourapi.com" parameters:parameters progress:nil success:^(NSURLSessionDataTask *task, id responseObject) {
  NSLog(@"Success");
} failure:^(NSURLSessionDataTask *task, NSError *error) {
  NSLog(@"Failure");
}];

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 4: 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 >

Step 5: Setup post-install deep linking

To setup post-install deep linking, add the domain you use on the web (e.g. https://usebutton.com) to the Button Dashboard. This is required so that Publishers can add your Button to their mobile website. This helps when post-install deep linking occurs, which is when a user clicks your Button in a Publisher mobile website and the user does not have your app installed. When this happens, Button will then route the user to the App Store or Google Play Store for them to download your app. When the user opens up your app after it is downloaded, the deeplink is lost and your app does not know what your user was doing when it came in from Button. This results in the Publisher losing that commission if a transaction is made. However, if you add your domain to the Button Dashboard, ButtonJS is smart enough to figure out the details of that potentially lost order, allowing Button to apply the appropriate commissions.

Advanced features and integration docs

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