Initial SDK Setup

Installing the Braze SDK will provide you with basic analytics functionality as well as a working in-app slideup message with which you can engage your users.

The iOS Braze SDK should be installed or updated using CocoaPods, a dependency manager for Objective-C and Swift projects. CocoaPods provides added simplicity for integration and updating.

iOS SDK CocoaPod Integration

Step 1: Install CocoaPods

Installing the SDK via the iOS CocoaPod automates the majority of the installation process for you. Before beginning this process please ensure that you are using Ruby version 2.0.0 or greater. Don’t worry, knowledge of Ruby syntax isn’t necessary to install this SDK.

Simply run the following command to get started:

$ sudo gem install cocoapods

Note: If you are prompted to overwrite the rake executable please refer to the Getting Started Directions on for further details.

Note: If you have issues regarding CocoaPods, please refer to the CocoaPods Troubleshooting Guide.

Step 2: Constructing the Podfile

Now that you’ve installed the CocoaPods Ruby Gem, you’re going to need to create a file in your Xcode project directory named Podfile.

If you are using Xcode 9+, add the following line to your Podfile:

target 'YourAppTarget' do
  pod 'Appboy-iOS-SDK'

If you are using Xcode 8.3.3 or earlier, please use SDK version 3.0.2.

Note: We suggest you version Braze so pod updates automatically grab anything smaller than a minor version update. This looks like ‘pod ‘Appboy-iOS-SDK’ ~> Major.Minor.Build’. If you want to integrate the latest version of Braze SDK automatically even with major changes, you can use pod 'Appboy-iOS-SDK' in your Podfile.

Note: If you do not use any Braze default UI and don’t want to introduce the SDWebImage dependency, please point your Braze dependency in your Podfile to our Core subspec, like pod 'Appboy-iOS-SDK/Core' in your Podfile. .

Example Podfile

If you would like to see an example, see the Podfile within our Stopwatch Sample Application. If you use use_frameworks! in your Podfile, please see the Podfile within our HelloSwift Sample Application.

Step 3: Installing the Braze SDK

To install the Braze SDK Cocoapod, navigate to the directory of your Xcode app project within your terminal and run the following command:

pod install

At this point you should be able to open the new Xcode project workspace created by CocoaPods.

New Workspace

Step 4: Updating your App Delegate

Add the following line of code to your AppDelegate.m file:

#import "Appboy-iOS-SDK/AppboyKit.h"

Within your AppDelegate.m file, add the following snippet within your application:didFinishLaunchingWithOptions method:

[Appboy startWithApiKey:@"YOUR-API-KEY"

If you are integrating the Braze SDK with Cocoapods or Carthage, add the following line of code to your AppDelegate.swift file:

#import Appboy_iOS_SDK

For more information about using Objective-C code in Swift projects, please see the [Apple Developer Docs][apple_initial_setup_19].

In AppDelegate.swift, add following snippet to your application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool:

Appboy.start(withApiKey: "YOUR-API-KEY", in:application, withLaunchOptions:launchOptions)

Note: Braze’s sharedInstance singleton will be nil before startWithApiKey: is called, as that is a prerequisite to using any Braze functionality.

Note: Be sure to update YOUR-API-KEY with the correct value from your App Settings page.

Note: Be sure to initialize Braze in your application’s main thread.

Step 5: Specify Your Custom Endpoint or Data Cluster

If you are an EU-based client, have a custom endpoint or are on a specific data cluster, you will need to direct the SDK to use that endpoint for your integration to work correctly. EU clients should refer to this documentation to implement their iOS integration.

Starting with Braze iOS SDK v3.0.2, you can set a custom endpoint using the Info.plist file. Add the Appboy dictionary to your Info.plist file. Inside the Appboy dictionary, add the Endpoint string subentry and set the value to your custom endpoint url’s authority (e.g., not

In versions prior to 3.0.2, add the following class to your application, and then instantiate it and pass it in the appboyOptions dictionary you pass to startWithApiKey:inApplication:withLaunchOptions:withAppboyOptions with the key: ABKAppboyEndpointDelegateKey

#import "Foundation/Foundation.h"
#import "ABKAppboyEndpointDelegate.h"

@interface AppboyEndpointDelegate : NSObject <ABKAppboyEndpointDelegate>

@implementation AppboyEndpointDelegate
- (NSString *) getApiEndpoint:(NSString *)appboyApiEndpoint {
    return [appboyApiEndpoint stringByReplacingOccurrencesOfString:@"" withString:@"YOUR_CUSTOM_ENDPOINT_OR_DATA_CLUSTER"];


Note: To find out your specific cluster or custom endpoint, please ask your Customer Success Manager or reach out to our support team.

Implementation Example

See the AppDelegate.m file in the Stopwatch sample app.

SDK Integration Complete

Braze should now be collecting data from your application and your basic integration should be complete. Please see the following sections in order to enable custom event tracking, push messaging, the news-feed and the complete suite of Braze features.

Updating the Braze SDK via CocoaPods

To update a Cocoapod simply run the following commands within your project directory:

pod update

Customizing Braze On Startup

If you wish to customize Braze on startup, you can instead use the Braze initialization method startWithApiKey:inApplication:withLaunchOptions:withAppboyOptions and pass in an optional NSDictionary of Braze startup keys.

In your AppDelegate.m file, within your application:didFinishLaunchingWithOptions method, add the following Braze method:

[Appboy startWithApiKey:@"YOUR-API-KEY"

In AppDelegate.swift, within your application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool method, add the following Braze method:

Appboy.startWithApiKey("YOUR-API-KEY", inApplication:application, withLaunchOptions:launchOptions, withAppboyOptions:appboyOptions)

where appboyOptions is a Dictionary of startup configuration values.

Note: This method would replace the startWithApiKey:inApplication:withLaunchOptions: initialization method from above.

This method is called with the following parameters:

  • YOUR-API-KEY – Your application’s API Key from the Braze Dashboard
  • application – The current app
  • launchOptions – The options NSDictionary that you get from application:didFinishLaunchingWithOptions:
  • appboyOptions – An optional NSDictionary with startup configuration values for Braze

See Appboy.h for a list of Braze startup keys.

Appboy.sharedInstance() and Swift nullability

Differing somewhat from common practice, the Appboy.sharedInstance() singleton is optional. The reason for this is that, as noted above, sharedInstance is nil before startWithApiKey: is called, and there are some non-standard but not-invalid implementations in which a delayed initialization can be used.

If you call startWithApiKey: in your didFinishLaunchingWithOptions: delegate before any access to Appboy’s sharedInstance (the standard implementation), you can use optional chaining, like Appboy.sharedInstance()?.changeUser("testUser"), to avoid cumbersome checks. This will have parity with an Objective-C implementation that assumed a non-null sharedInstance.