Button Merchant Library for Native Apps on
iOS

Button Merchant Library for Native Apps


The Button Merchant Library for iOS is a lightweight, open-source library designed to manage the Button Attribution Token. By the end of this section, you’ll be able to associate all incoming users against their subsequent taps in other applications that brought them to your iOS application.


Add the Button Merchant Library

To get started, add the Button Merchant Library through CocoaPods.

    pod 'ButtonMerchant', '~> 1'

Alternatively, you can include the Button Merchant library from GitHub using Carthage. If you choose to include the Button Merchant Library in this way, we recommend using a major version match with fuzzy-matching for feature releases.

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

In your AppDelegate file, import the open-source ButtonMerchant class, and initialize configuration by calling the ButtonMerchant.configure method and passing in your iOS Application ID registered from the Button Dashboard.

Additionally, some users will be initializing your application from a fresh install after following a promotion. In order to fulfill these specific user requests, include a call to the ButtonMerchant.handlePostInstallURL method. This will fetch the user’s intent prior to the fresh install, and allow you to route them directly to your relevant promotion. For more information on the handlePostInstallURL method, take a look at Button Deferred Deeplinking.


    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 {
              // Use the information in this url to direct 
              // the user to the correct destination in your app.
            }
        }
    
        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;
    }


Registering Deeplinks with Button’s Merchant Library

Button’s Merchant Library will abstract any complexities of token management for you, including extracting the token from any incoming deeplinks.

For users that have already installed your application and are entering from another application’s promotion, Button’s Merchant library will help you source where they came from. Pass the incoming URL to the Button Merchant Library in order to accurately attribute and handle their intent.

The ButtonMerchant class allows you to handle both Universal Linking by passing incoming user activity to trackIncomingUserActivity, and Custom Scheme URLs by passing incoming URLs to trackIncomingURL.


    // Handle custom scheme urls
    func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey: Any] = [:]) -> Bool {
    
        ButtonMerchant.trackIncomingURL(url)
    
        // Route user to the url
    
        return true
    }
    
    // Handle Universal Links
    func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([Any]?) -> Void) -> Bool {
    
        ButtonMerchant.trackIncomingUserActivity(userActivity)
    
        // Route user to the url
    
        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

Once the user has placed an order in your app, include the Button Attribution Token before sending the user’s checkout request to your checkout API. The Button Attribution Token can be retrieved by calling the attributionToken method from the Button Merchant Library.



Let’s say your user has successfully made a purchase for a pair of jeans on your client application. Before sending that purchase request to your checkout API, retrieve the Button Attribution Token using ButtonMerchant.attributionToken


    // Obtain Attribution Token
    if let token = ButtonMerchant.attributionToken {
        // referred token is present
    }


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

Once the Button Attribution Token has been retrieved, include it when sending the user’s order request to your checkout API.


    // Set parameters for POST, including Attribution Token
    let parameters: Parameters = [
        "token": token, // Attribution Token from previous section
        "price": 50.00,
        "location": "New York",
        "items": "Jeans"
    ]
    
    // Perform POST request to your Checkout API (server)
    Alamofire.request("https://example.com", method: .post, parameters: parameters, encoding: JSONEncoding(options: []))


    NSDictionary *params = @{ @"token": token, // Attribution Token from previous section
                              @"price": @50.00,
                              @"location": @"New York",
                              @"items": @"Jeans" };
    
    // Perform POST request to your Checkout API (server)
    [AFHTTPSessionManager.manager POST:@"https://example.com"
                            parameters:params
                              progress:nil
                               success:successHandler 
                               failure:errorHandler];

This concludes handling a user journey from outside applications.