Application Browse and Tap Integration on
iOS

Application Browse and Tap Integration


In this section we will walk through the steps needed to integrate your iOS application with Button.


Add the Button SDK

To get started, add the Button SDK through CocoaPods.


    pod "Button", "~>6"

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


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. 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];


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.


Update Build Settings


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 iOS 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
    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.

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.

Setting creative type


Next, it's time to ensure your Impression Views track data by calling the track 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 track method and supplying the following required arguments:

PropertyDescription
urlstring – The URL destination of the offer rendered. This is the same URL used when fetching a Purchase Path using the Button SDK
visibleRateTypeenum – The rate type displayed to your user. Valid options are percent or fixed
visibleRatedouble – The visible rate displayed to your user. For example a value of 5 represents an offer shown to the user of 5%
offerIdstring – This is the id associated with the offer fetched from the Button Personalization API. If a Brand item being displayed contains multiple categories/rates, you may use the best_offer_id instead.


Remember to always call track 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.


    // data is loaded into myOfferView before the track method is called
    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") 


    // 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.