Integrate the Button SDK on

Integrate the Button SDK

This guide will walk you through how to add the Button SDK into your application. The SDK captures the user for attribution and allows Button to properly affiliate commissions and user rewards.

Add the Button SDK

There are two ways to add the Button SDK to your iOS application. You can either do so through CocoaPods or by directly downloading the source code and adding it to your application.

CocoaPods

The easiest way to include the Button SDK into your iOS application is through CocoaPods. To do this, add the Button pod to your Podfile.

target 'nameOfYourApp' do

  # Comment the next line if you're not using Swift
  use_frameworks!
  pod "Button", "~>5" # This is what was added!

end

In the terminal, from your app's root directory, install the newly added Button pod

pod install

Open up your project workspace to continue working on your app.


Direct Download

Get the SDK by downloading the latest Button framework.

Add the framework and bundle into your project by dragging Button.framework and Button.bundle into your project. Make sure to check the "Copy items if needed" box.

Add Framework and Bundle

In your target's build settings, you'll need to pass the -ObjC flag to "Other Linker Flags". This ensures that the Button SDK categories get linked into your app.

Update Build Settings

Initialize the Button SDK

To initialize the Button SDK, you have to include it into your AppDelegate file with your application ID, found on the Dashboard. This will allow your app to register deeplinks with the SDK.

Import the Button SDK and register deeplinks

Import the Button SDK at the top of the file of your AppDelegate file. This will give the file access to the Button SDK and all of its capabilities.

// AppDelegate file

import Button
// AppDelegate file

@import Button;

Add the following code to your AppDelegate’s applicationDidFinishLaunching: method to set up Button. This will initialize Button in your application and allow it to register deeplinks.

// AppDelegate file

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
}
// AppDelegate file

- (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;
}

Determine referrer through attribution token

If you need to determine whether the user was referred by the Button marketplace, you can access the attribution token as follows:

if (Button.shared().referrerToken()) {
   // The user was referred by the Button marketplace.
}
if ([Button sharedButton].referrerToken.length) {
   // The user was referred by the Button marketplace.
}

Pass the attribution token to your Checkout API

When a user comes into your app through deep link, a unique Attribution Token (or btn_ref) will be generated and stored by the Button SDK for their session. When the user checks out and your app reports the order to your Checkout API, you must obtain their Attribution Token via the SDK and POST this in addition to any other information you regularly would.

Obtain attribution token

When the order is complete within your mobile app and you're ready to POST the user's order to your Checkout API for further processing, grab the Attribution Token from the SDK and POST to your Checkout API how you normally would, including the Attribution Token in the payload. Note: you should never store this value and should always access it from Button when it is needed.

// Obtain Attribution Token
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
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");
}];

Add call to Button's Order API from your Checkout API

To report orders to Button, you will need to add an API request from your Checkout API to Button's Order API. To implement this, checkout this guide.

Enable mobile web Publishers

What are Universal Links?

Universal Links allow you to open your app to specific content or actions from an http-style URL, if your app is installed. This means that for any given web URL, it will open in your app if it's available, or on the website if not. It is the simplest way to support deep linking and is the method that both Google and Apple now recommend. To enable this, do the following:

  1. Configure the 'Associated Domains' entitlement in the 'Capabilities' tab on your Target
  2. Add your domain to the list (example applinks:yourdomain.com)

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, Button's SDK is smart enough to figure out the details of that potentially lost order, allowing Button to apply the appropriate commissions.

Setup mobile web affiliation

In addition to integrating the Button SDK into your iOS app, you must also include ButtonJS in your mobile website. ButtonJS is a Javascript library that captures users for attribution on your mobile website, allowing Button to properly affiliate commissions and user rewards. See how to set this up here.

Button Links

Button Links are a simple, free way to bring users from all channels directly into your app with tracking, attribution and post-install deep linking. After integrating, you can simply replace .com with .bttn.io.

e.g. https://yourdomain.com/some/path -> https://yourdomain.bttn.io/some/path

Button Links are enhanced by:

  • Sending users who don't have your app to the app store
  • Maintaining the user's destination through install using Post-Install Deep Linking
  • Full reporting and attribution, with a Dashboard to dig in to the numbers.

Deep Linking Support

In order to use Button Links, your app needs to support deep linking using Universal Links. Don't support it yet? Follow our simple guide to get up and running with your first deep links in just a few minutes, using our DeepLink Kit.

Configure Button Links

In order to start using Button Links you first need to set up your Button Links Domain. This is the base URL that you will use for links that you want to enhance.

Your Button Links Domain is a subdomain of bttn.io which you can use interchangeably with yourdomain.com that will always either open your app if installed, send the user to the App Store for post-install deep linking or forward them to yourdomain.com on the relevant page.

Web Links

To create your Button Links domain, choose the subdomain of bttn.io that you want to use for your app, specify the base web domain (the domain that you normally use on the web) and associate it with your app. You can do it here in the Dashboard.

See your first Link

Once you configure your domain, you can try your first Button Link. Get a Button Link either by using the Button Link Generator on the page or simply replace yourdomain.com with yourdomain.bttn.io in any of your usual links.

Open it in a browser on your mobile device and you'll see your Button Links landing page. We're part of the way there, but before we can open your app using Universal Links or take advantage of post-install deep linking and advanced analytics, you'll need to integrate with Button in your app.

Configuring your app

Next, to support Universal Links for the Button domain (to stop any Safari redirecting) you need to 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

Now, when you run your app and tap a Button Link, it should open in your app.

Next Step

See how to report orders to Button.