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:

  • Include the Button SDK in your app
  • Start the Button SDK
  • Set up some permissions
  • Configure User Attribution

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

Add the Button SDK


The easiest 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;

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?