Token Management on

Token Management

This guide walks you through how to add Button to your iOS application. In this guide, we'll:

  1. Add the Button Merchant Library
  2. Attribute Users from Incoming Deeplinks
  3. Pass the Button Attribution Token to your Checkout API (Server)
  4. Configure Button Links

Add the Button Merchant Library

Add the Button Merchant Library through CocoaPods.

pod 'ButtonMerchant', '~> 1'

Carthage

You can include the Button Merchant library from GitHub using Carthage — we recommend using a major version match with fuzzy-matching for feature releases.

github "button/button-merchant-ios" ~> 1.0

In your AppDelegate file, configure the Button Merchant Library and handle any post-install deeplinks within the didFinishLaunchingWithOptions function.

import ButtonMerchant

func application(_ application: UIApplication,
  didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

    // Replace app-xxxxxxxxxxxxxxxx with your App ID from the Button Dashboard https://app.usebutton.com
    ButtonMerchant.configure(applicationId: "<#app-xxxxxxxxxxxxxxxx#>")

    ButtonMerchant.handlePostInstallURL { url, error in

        guard let url = url else {
            // Route user to the url
        }
    }

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

    // Replace app-xxxxxxxxxxxxxxxx with your App ID from the Button Dashboard https://app.usebutton.com
    [ButtonMerchant configureWithApplicationId:@"<#app-xxxxxxxxxxxxxxxx#>"];

    [ButtonMerchant handlePostInstallURL:^(NSURL * _Nullable url, NSError * _Nullable error) {
        if (url) {
            // Route user to the url
        }
    }];

    return YES;
}

Traffic from the App Store can result in users opening your app without any deeplink path or parameters. Button's Deferred Deeplink product closes this gap by recovering the link the user was originally following based on device fingerprinting.

After a fresh install, the user may both have an attributed source, and a destination deep link which needs to be retrieved from the Button API.

This is achieved using a single call in the Merchant library — the Merchant library will ensure that this network call is only performed when it is possible to have a response (e.g. after first open) so you can safely call it as much as is needed.

The Merchant library will automatically store the attribution from the received URL, so there’s no need to pass it back to trackIncomingURL, but you will need to route the user to the url that is returned, if present.

Attribute Users from Incoming Deeplinks

Whenever a user deep links into your app, the incoming URL should be passed to the Merchant library so that the library can extract and store the token.

Incoming URLs are reported, and attributed by calling the trackIncomingURL method.

// Handle custom scheme urls
func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey: Any] = [:]) -> Bool {

    ButtonMerchant.trackIncomingURL(url)

    return true
}

// Handle Universal Links
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([Any]?) -> Void) -> Bool {

    ButtonMerchant.trackIncomingUserActivity(userActivity)

    return true
}
// Handle custom scheme urls
- (BOOL)application:(UIApplication *)app
            openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {

    [ButtonMerchant trackIncomingURL:url];

    return YES;
}

// Handle Universal Links
- (BOOL)application:(UIApplication *)application
continueUserActivity:(NSUserActivity *)userActivity
  restorationHandler:(void (^)(NSArray * _Nullable))restorationHandler {

    [ButtonMerchant trackIncomingUserActivity:userActivity];

    return YES;
}

Pass the Button Attribution Token to your Checkout API (Server)

When an order has been placed in your app, and just before the request to your own Checkout API (server) is made, fetch the Button Attribution token via the Button Merchant Library.

// Obtain Attribution Token
if let token = ButtonMerchant.attributionToken {
    // referred token is present
}
NSString *token = ButtonMerchant.attributionToken;
if (token) {
  // referred token is present
}

  • It is a case-sensitive ASCII-encoded string
  • It is under 256 bytes
  • It is an uninterpretable random value, corresponding to the impression which drove the most recent app or mobile website visit (do not attempt to parse or interpret its contents)
  • Although most attribution tokens include the string prefix srctok-, this prefix is not guaranteed to exist; do not test for or rely on this

Then execute a call to your Checkout API just like you currently do, adding the Button Attribution Token retrieved to the request payload along with the order details:

// Set parameters for POST, including Attribution Token
let parameters: Parameters = [
    "token": token, // Attribution Token from previous section
    "price": 50.00,
    "location": "New York"
]

// Perform POST request to your Checkout API (server)
Alamofire.request("https://api.yourapi.com", method: .post, parameters: parameters, encoding: JSONEncoding(options: []))
NSDictionary *params = @{ @"token": token, // Attribution Token from previous section
                          @"price": @50.00,
                          @"location": @"New York" };

// Perform POST request to your Checkout API (server)
[AFHTTPSessionManager.manager POST:@"https://api.yourapi.com"
                        parameters:params
                          progress:nil
                           success:successHandler failure:errorHandler];

Configure Button Links

This section ensures you can support Button's mobile web Publishers.

In the Button Dashboard, navigate to "Merchant" > "Apps" & click on the App for which you want to configure a Button Links domain. Once on the App details page, click on the "Add a Button Links Domain" button in the "Button Links Domains" section. Simply fill out the details in the popup modal to complete the configuration.

To support Universal Links for the Button domain (to stop any Safari redirecting), add the Button subdomain (yourdomain.bttn.io) to the Associated Domains Capability. Switch Associated Domains on if it's not already and add your domain to the list of domains registered in the format applinks:yourapp.bttn.io.

Web Links