Get Started on

Get Started

Welcome to the Button iOS Getting Started guide. This guide will walk you through adding the SDK to your app and will prepare you to use any of the Button Publisher products. We will:

From here you can begin using Button Purchase Path or Button Actions.

Add the Button SDK

The simplest way to include the Button SDK is through CocoaPods. To do this, simply add the Button pod to your Podfile.

pod "Button", "~>5"

If you don't already have a Podfile, create it.

pod init

Add Button to your Podfile so it looks as below. If you don't already use CocoaPods, you can follow their setup guide.

target 'nameOfYourApp' do

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


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 Button 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


Button does not currently support Carthage, but are actively investigating ways to sensibly distribute a closed-source project on Carthage.

Start the SDK

To initialize a Button in your app, your app ID is needed, which can be found in the Button Dashboard. If you're a loyalty Publisher, you must attribute your users' IDs through Button. It's recommended to initialize your Button in your AppDelegate file in the didFinishLaunchingWithOptions function, although this can be done in the view as well.

At the top of the file, import the Button SDK, and in the didFinishLaunchingWithOptions function, initialize your Button.

import Button

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

  // Replace YOUR_BUTTON_APP_ID with your App ID from the Button Dashboard
  Button.shared().configure(withApplicationId: "<#YOUR_BUTTON_APP_ID#>", userId: "<#USER_ID#>") { error, url in
    if let err = error {
      print("Error: \(err.localizedDescription)")
    else {
      print("Button created a Session successfully 🎉")

  return true
@import Button

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

  // Replace YOUR_BUTTON_APP_ID with your App ID from the Button Dashboard
  [[Button sharedButton] configureWithApplicationId:@"<#YOUR_BUTTON_APP_ID#>" userId:@"<#USER_ID#>" completion:^(NSError *error, NSURL *url) {
    if (error) {
      NSLog(@"Error: %@", error.localizedDescription);
    else {
      NSLog(@"Button created a Session successfully 🎉");

  return YES;

Note: The Button SDK is disabled by default. No user activity is reported and no data is collected until configured with an application id. Initialization can be deferred by simply not calling this method until ready to do so.

Set App Permissions


LSApplicationQueriesSchemes attribute tells your app which other apps it may link to (or more specifically, determine whether a link to that Merchant app will work). The key contains an array of all schemes that your app can check for the existence of.

Open your Project's Info.plist file, add the LSApplicationQueriesSchemes key, and include at least the button scheme.

Note: You should add the scheme of all Merchant apps that you launch partnerships with.

Update Build Settings

Configure user attribution

You can associate all Button activity with one of your users by setting their User Identifier. This can either be your user ID, email or a stable hash of one. You can use this later to look up orders, activity and identify the user in Webhooks.

[[Button sharedButton] setUserIdentifier:@"<#YOUR_USER_ID#>"];

If your app offers logout functionality, you should make sure to invoke the SDK's logout feature during your logout handler.

[[Button sharedButton] logOut];

Note: You will also need to set the user identifier upon completion of a user log in or sign up.

For more information on user attribution, see this guide.

Run your app

You should see printed to the console:

Button created a Session successfully 🎉

If you don't, try using debug mode to figure out why.

Start using Button

You're now ready to start using Button. What would you like to do?

Create a Button Purchase Path

Button Purchase Path take regular Merchant URLs to products, categories or just the homepage and replaces them with a fully attributed Button Purchase Path, optimized for both conversion and user experience.

View Guide

Using Button Actions

Buttons provide relevant actions to your users, complete with a corresponding UI. Buttons can be configured with one or more Merchants that they can offer to your users.

View Guide