iOS App Setup

Add the Button SDK to your iOS application

To get started, add the Button SDK through CocoaPods, Carthage or Swift Package Manager.

pod "Button", "~> 6"

In Xcode, navigate to **File → Swift Packages → Add Package Dependency**

https://github.com/button/button-ios

github "button/button-ios" ~> 6.29

dependencies: [
    .package(url: "https://github.com/button/button-ios", .upToNextMajor(from: "6.29.0"))
]

👍

Allow auto-updating

The Button SDK is strictly semantically versioned so we strongly recommend allowing automatic updates up to the next major version.

To manually integrate with the Button SDK, follow the instructions here.

Configure the Button SDK

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

After your iOS app initializes, pass in your Publisher iOS Application ID to Button.configure. Your Publisher’s iOS Application ID can be acquired from the Button Dashboard.

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] setLoggingEnabled: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;
    }

More information on the didFinishLaunchingWithOptions method can be found in the Apple Developer Documentation section for UI Application Delegate

Set App Permissions

Open your Project's Info.plist file, add the LSApplicationQueriesSchemes key, and add the schemes for all Brand apps that you launch partnerships with. This will ensure that your application has the ability to open Brand apps installed on the user’s phone.

Configure User Attribution

User attribution ensures downstream commerce activity is associated with a unique user identifier. We recommend anonymizing this identifier before reporting it to Button (e.g. providing a uuid for the user, or hashed email via sha-256). Once your user finalizes a purchase, we’ll notify you using this identifier.

Warning: Never send personally identifiable information (PII) as the identifier. If you’re unsure about this, please reach out to your Button representative who can help guide you to follow our security & privacy best practices.

After your Publisher application launches and has been configured with the Button SDK, you can configure user attribution. If a user is already logged in, you can pass your application’s User ID to the Button.user.setIdentifier method. This identifier must be a string between 1 and 255 characters long in the ASCII range [0x21-0x7E]. If a user has not yet logged in, handle your user’s login first before calling Button.user.setIdentifier.

Button.user.setIdentifier("<#YOUR_LOGGED_IN_USERS_ID#>")

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

Similarly, after your user has successfully logged out of your Publisher application, invoke the Button SDK’s logout feature by calling the Button.clearAllData method. This method only needs to be called once at the time of logout.

Button.clearAllData()

[Button clearAllData];

Handle Link Routing When A User Taps

Next, it’s time to handle link routing when a user taps on an offer. This is done by setting up a Button Purchase Path wherever your mobile application routes your user to a Brand.

Creating a Purchase Path is done by passing a Brand URL into the PurchasePathRequest. Upon passing the PurchasePathRequest into the Button.purchasePath.fetch method, the Button SDK will first validate that the PurchasePathRequest is valid. If it is, then the Button SDK will initialize the Purchase Path flow.

If Button can exchange 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 Brand app, install flow, or web checkout.

Publishers should pass the value returned by the Personalization API in the offer_id field as the offerId when creating Purchase Path requests.

In order to help with tracking this Purchase Path, Publishers can optionally set a value to the PurchasePathRequest's pubRef property. The pubRef (Publisher Reference) accepts a string value with a maximum length of 512, and is made available downstream in Button Webhooks as pub_ref . Publishers usually populate this value with click IDs, campaign IDs, and other identifiers to help with measuring performance.

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

    // Step 2 - Associate the offerId
    request.offerId = "offer-G123456789123_abcdefghijklmnopqrstuvwxyzABCDEFGFHIJKL"

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

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

        // Step 4 - Start Purchase Path flow
        // (Note: for CLO integrations this step is skipped) 
        purchasePath?.start()
    }

// Step 1 - Create a Purchase Path request
    NSURL *url = [NSURL URLWithString:@"https://www.example.com"];
    BTNPurchasePathRequest *request = [BTNPurchasePathRequest requestWithURL:url];

    // Step 2 - Associate the offerId
    request.offerId = @"offer-G123456789123_abcdefghijklmnopqrstuvwxyzABCDEFGFHIJKL";

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

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

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

Now that you’ve set up a Purchase Path, you’ll be able to track taps and deep-links visited within the Button Dashboard.

Report Impression Views

It is critical to implement Impression Views within your app UI. Without this data, your integration will have an incomplete view of the user behavior funnel.

Impression views are programmatically wrapped subviews around your offer views which enable viewable impressions. In specific, they meet 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.

The implementation can be done in code or using the Interface Builder.

If you’re writing code, utilize Button’s ImpressionView class and supply a string value to the exposed enumerated creativeType. The available creativeType values are: hero, carousel, list, grid, detail, other.

The following example shows how an Impression View is added to an Offer View.

let impressionView = ImpressionView(creativeType: .hero)
    myOfferView.addSubview(impressionView)

BTNImpressionView *impressionView = [[BTNImpressionView alloc] initWithCreativeType:BTNCreativeTypeHero];
    [myOfferView addSubview:impressionView];

If you’d like to use Xcode’s Interface Builder, you can add Impression Views and set the creativeType in the Attributes Inspector for the ImpressionView.

Next, it's time to ensure your Impression Views track data by calling the configure method wherever your offer views are being recycled with new data. This is distinct from impression events, which are handled by Button when Impression Views are rendered.

To implement tracking, call the configure method and supplying the following required arguments:

Remember to always call configure whenever your Offer Views are updated with new data, such as when making another fetch to the Button Personalization API, or when rendering new offers.

// Configure the Impression View with new offer details
    let details = OfferDetails(url: "https://example.com", // The URL for the Brand offer
                                           offerId: "offer-abc123def456abc1", // The offer Id provided by the Button Personalization API
                                           visibleRate: 5, // The rate visible to the user on your offer view. In this example, it's a 5% offer.
                                           rateType: .percent) // or .fixed (a percentage or fixed rate offer)
    myOfferView.impressionView.configure(with: details)

// Configure the Impression View with new offer details
    BTNOfferDetails *details = [BTNOfferDetails detailsWithURL:@"https://example.com" // The URL for the Brand offer
                                                       offerId:@"offer-abc123def456abc1" // The offer Id provided by the Button Personalization API
                                                   visibleRate:5 // The rate visible to the user on your offer view. In this example, it's a 5% offer.
                                                      rateType:BTNVisibleRateTypePercent]; // or .fixed (a percentage or fixed rate offer)
    [impressionView configureWithDetails:details];

Debugging Impression Tracking

In order to help debug Impression Tracking, the Button SDK supports an impression tracking debugging mode that will show you viewable areas for impression tracking views and log helpful messages to the debug console.

Button.debug.visualDebuggingEnabled = true

For more information, take a look at the Debugging Impression Tracking guide