Get Started: iOS

Unlock features, mobile partnerships & revenue with one drop-in SDK.


Buttons enable rich cross-application functionality initiated from drop-in UI components, called Buttons! Buttons act as the entry point to highly-contextual, fully attributed actions across apps.

The Button SDK provides full functionality for both displaying Buttons and attributing incoming users from the Button marketplace.

Add a Button to your app, pass it some context and it will render & display itself. e.g...

Ride use-case with a subjectLocation

You'll get started with the setup of your account and first buttons by sigining up in the Dashboard.

Getting the SDK

Latest Button SDK version

The best way to get the Button SDK is to use CocoaPods. If you don't already use CocoaPods, the CocoaPods Getting Started Guide will have you managing dependencies in no time.

Add Button to your target by adding the following line to your Podfile.

pod "Button", "~> 4"

Note: If you have a previous version, run pod update Button to get the latest SDK.

Alternatively, you can download the latest Button framework and follow the Framework Integration Steps.

Examples and Documentation

If you'd like to download an example app to get started, you'll find Objective-C and Swift projects demonstrating CocoaPods and framework integrations of the SDK on our Button-iOS repository.

The full reference documentation for the latest release is also available.

Add Schemes to your Info.plist

As of iOS 9, in order to query for the installation state of another app you need to declare the scheme in your Info.plist file. The easiest way to do this is to download the plist below and copy and paste the LSApplicationQueriesSchemes key into your Info.plist file.

Initializing Button

To begin, we will initialize the Button SDK with your applicationId. You can get an applicationID by creating an App in the Button Dashboard or reaching out to our team.

// Import Button
#import <Button/Button.h>

// Application Finished Launching
- (BOOL)application:(UIApplication *)application
        didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    [[Button sharedButton] configureWithApplicationId:@"<#YOUR_BUTTON_APP_ID#>"
     ^(NSError *error, NSURL *targetURL) {
        if (!error && targetURL) {
          // Handle targetURL and navigate your users to the relevant content 
          // as you do in your app delegate url handling methods 
          // (e.g. application:openURL:sourceApplication:annotations:).

    return YES;

Note: For iOS 9 support, you will also need to add the URL scheme of each app you connect with to the LSApplicationQueriesSchemes array in your Info.plist file.

You're now set up and ready to start configuring your Button.

Attributing Users

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 web hooks.

Button must be initialized before calling -setUserIdentifier: independently, so either pass it to the configureWithApplicationId:userId:completion:method or when your user logs in later.

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

If your application 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 identifer upon completion of a user log in or sign up.

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

Debugging Button

If you're having trouble configuring the SDK or seeing your Button you can enable debug logging to see what's going on.

[[Button sharedButton] setDebugLoggingEnabled:YES];

Note: You should not ship to the App Store with this enabled.

With debug logging enabled, Button will log to the standard log output with the success or failure of the following operations:

All operations which failed (including simply not matching an action for the current context) will print with the log statement a Request ID in the format req-xxxxxxxxx. If you can't figure out why your Button isn't working then contact us and send this token to our support team; we can then investigate why things aren't working as expected.