SDK Integration on

SDK Integration

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

  1. Add the Button SDK
  2. Configure User Attribution
  3. Set App Permissions
  4. Create a Button Purchase Path
  5. Add Impression Tracking

Add the Button SDK

Add the Button SDK through CocoaPods.

pod "Button", "~>6"

In your AppDelegate file, configure the Button SDK in the didFinishLaunchingWithOptions method.

import Button

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

  // Debugging enabled (do not include in production)
  Button.debug.loggingEnabled = true

  // Replace app-xxxxxxxxxxxxxxxx with your App ID from the Button Dashboard https://app.usebutton.com
  Button.configure(applicationId: "<#app-xxxxxxxxxxxxxxxx#>") { error in
    // Optional callback to inspect whether an error occurred while
    // creating or resuming a session. See also debug logging.
  }

  return true
}
@import Button;

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

  // Debugging enabled (do not include in production)
  Button.debug.loggingEnabled = YES;

  // Replace app-xxxxxxxxxxxxxxxx with your App ID from the Button Dashboard https://app.usebutton.com
  [Button configureWithApplicationId:@"<#app-xxxxxxxxxxxxxxxx#>" completion:^(NSError *error) {
    // Optional callback to inspect whether an error occurred while
    // creating or resuming a session. See also debug logging.
  }];

  return YES;
}

Configure User Attribution

Note: Passing a User ID is required for Loyalty Publishers.

Passing a user ID ensures subsequent Merchant activity (such as installs or purchases) is attributed to a user. This can either be their user ID or SHA-256 encoded email address. Never send personally identifiable information (PII) as the identifier. You can use this later to look up orders, activity and identify the user in Webhooks. String with a maximum length of 255.

Set the user ID in your login handler.

Button.user.setIdentifier("<#YOUR_LOGGED_IN_USERS_ID#>")
[Button.user setIdentifier:@"<#YOUR_LOGGED_IN_USERS_ID#>"];

If your app offers logout functionality, invoke the SDK's logout feature during your logout handler.

Button.clearAllData()
[Button clearAllData];

Set App Permissions

Open your Project's Info.plist file, add the LSApplicationQueriesSchemes key, and add the scheme of all Merchant apps that you launch partnerships with.

Update Build Settings

Create a Button Purchase Path

// Step 1 - Create a Purchase Path request
let url = URL(string: "https://www.example.com")!
let request = PurchasePathRequest(url: url)

// Optionally associate a unique token (e.g. campaign Id)
// request.pubRef = "abc123"

// Step 2 - Fetch a Purchase Path object
Button.purchasePath.fetch(request: request) { purchasePath, error in

    // Step 3 - Start Purchase Path flow
    purchasePath?.start()
}
// Step 1 - Create a Purchase Path request
NSURL *url = [NSURL URLWithString:@"https://www.example.com"];
BTNPurchasePathRequest *request = [BTNPurchasePathRequest requestWithURL:url];

// Optionally associate a unique token (e.g. campaign Id)
// request.pubRef = @"abc-123";

// Step 2 - Fetch a Purchase Path object
[Button.purchasePath fetchWithRequest:request purchasePathHandler:
^(BTNPurchasePath *purchasePath, NSError *error) {

    // Step 3 - Start Purchase Path flow
    [purchasePath start];
}

If Button can exchange the the given url for a fully attributed action, the fetch will complete with a PurchasePath. Starting a purchasePath will pass control to the Button SDK which will open the merchant app, install flow, or web checkout.

You can pass an optional Publisher Reference (pubRef) (string with a maximum length of 512), which will be passed back to you in webhooks as pub_ref. This pass through value is typically used for click IDs, campaign IDs, etc.


Add Impression Tracking

While you'll be able to track taps and deeplinks in the Button Dashboard after each Purchase Path you start, in order to see the viewable impressions related to those taps, you'll need to implement Impression Tracking.

Button's impression tracking works by adding an ImpressionView as a subview to the views that you use to display offers to your users. Impression views are transparent and do not accept user interaction. They are used strictly to detect the visibility of the offer and track "viewable impressions" as users interact with your app.

This feature will be tracking what are known as “viewable impressions” as defined by the Interactive Advertising Bureau (IAB), where a viewable impression is one that meets the following criteria:

  • Pixel Requirement: Greater than or equal to 50% of the pixels (Density- Independent) in the offer were on an in-focus browser or a fully downloaded, opened, initialized application, on the viewable space of the device.
  • Time Requirement: The time the pixel requirement is met was greater than or equal to one continuous second, post offer render. The clock starts once the pixel requirement is met.
  • User Interaction: A strong user interaction with the offer can substitute the above requirements (i.e. a tap on the offer).

Adding Impression Views

Impression tracking illustration

You add impression views to your app's offer views just as you would add any other view. You can add them with a few lines of code in Interface Builder.

When you create an impression view, you specify a "creative type" to indicate where in your app an impression originated. The ImpressionView class exposes creativeType as an enumerated type in code, but it can be specified as a string in your layout or in Interface Builder.

Available Creative Types

  • hero
  • carousel
  • list
  • grid
  • detail
  • other

In View Layout

In Interface Builder, you can add impression views and set the creativeType in the Attributes Inspector for the ImpressionView.

Setting creative type

Programmatically

let impressionView = ImpressionView(creativeType: .hero)
myOfferView.addSubview(impressionView)
BTNImpressionView *impressionView = [[BTNImpressionView alloc] initWithCreativeType:BTNCreativeTypeHero];
[myOfferView addSubview:impressionView];

Tracking Offer Details

When you populate your offer views with data you’re displaying to the user, call track(…) on the ImpressionView that you added to that view in the previous step.

The track(…) method takes the following arguments:

  • url (string): The same URL you’ll use when fetching a Purchase Path from the Button SDK.
  • visibleRateType (enum): the rate type displayed to your user. Accepted values are "percent" or "fixed".
  • visibleRate (double): the visible rate displayed to your user, e.g. "5" to represent an offer of 5%.
  • offerId (string): If you’re using Button’s Personalized Rates API, the offers[].id associated with the offer. In the case of a Brand with multiple categories/rates, please use the best_offer_id value. If you are not using the Rates API, do not include this value in the track(…) method.
// Track the new data on the associated ImpressionView
myOfferView.impressionView.track(withURL: URL(string: "https://example.com")! // The URL for the Brand offer,
                                 visibleRateType: .percent, // or .fixed (a percentage or fixed rate offer)
                                 visibleRate: 5, // The rate visible to the user on your offer view. In this example, it's a 5% offer.
                                 offerId: "offer-abc123def456abc1") // Only relevant if using Button's Personalized Rates API. If not, pass `nil` here.
// Track the new data on the associated ImpressionView
[impressionView trackWithURL:[NSURL URLWithString:@"https://example.com"], // The URL for the Brand offer,
             visibleRateType:BTNVisibleRateTypePercent, // or BTNVisibleRateTypeFixed (a percentage or fixed rate offer)
                 visibleRate:5, // The rate visible to the user on your offer view. In this example, it's a 5% offer.
                     offerId:@"offer-abc123def456abc1"]; // Only relevant if using Button's Personalized Rates API. If not, pass `nil` here.