Skip to content

Integrating the Braze Swift SDK

Learn how to integrate and customize the Braze Swift SDK using the Swift Package Manager (SPM), CocoaPods, or manual integration methods. For more information about the various SDK symbols, see Braze Swift reference documentation. To learn more about the SDK in general, see Getting started: Integration overview.

Prerequisites

Before you start, verify your environment is supported by the latest Braze Swift SDK version.

Integrating the SDK

Step 1: Install the Braze Swift SDK

We recommend using the Swift Package Manager (SwiftPM) or CocoaPods to install the Braze Swift SDK. Alternatively, you can install the SDK manually.

Step 1.1: Import SDK version

Open your project and navigate to your project’s settings. Select the Swift Packages tab and click on the add button below the packages list.

Enter the URL of our iOS Swift SDK repository https://github.com/braze-inc/braze-swift-sdk in the text field. Under the Dependency Rule section, select the SDK version. Finally, click Add Package.

Step 1.2: Select your packages

The Braze Swift SDK separates features into standalone libraries to provide developers with more control over which features to import into their projects.

Package Details
BrazeKit Main SDK library providing support for analytics and push notifications.
BrazeLocation Location library providing support for location analytics and geofence monitoring.
BrazeUI Braze-provided user interface library for in-app messages and Content Cards.
About Extension libraries
Package Details
BrazeNotificationService Notification service extension library providing support for rich push notifications.
BrazePushStory Notification content extension library providing support for Push Stories.

Select the package that best suits your needs and click Add Package. Make sure you select BrazeKit at a minimum.

Step 1.1: Install CocoaPods

For a full walkthrough, see CocoaPods’ Getting Started Guide. Otherwise, you can run the following command to get started quickly:

1

$ sudo gem install cocoapods

If you get stuck, checkout CocoaPods’ Troubleshooting Guide.

Step 1.2: Constructing the Podfile

Next, create a file in your Xcode project directory named Podfile.

Add the following line to your Podfile:

1
2
3

target 'YourAppTarget' do
  pod 'BrazeKit'
end

BrazeKit contains the main SDK library, providing support for analytics and push notifications.

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

About additional libraries

The Braze Swift SDK separates features into standalone libraries to provide developers with more control over which features to import into their projects. In addition to BrazeKit, you may add the following libraries to your Podfile:

Library Details
pod 'BrazeLocation' Location library providing support for location analytics and geofence monitoring.
pod 'BrazeUI' Braze-provided user interface library for in-app messages and Content Cards.
Extension libraries

BrazeNotificationService and BrazePushStory are extension modules that provide additional functionality and should not be added directly to your main application target. Instead, you will need to create separate extension targets for each of these modules and import the Braze modules into their corresponding targets.

Library Details
pod 'BrazeNotificationService' Notification service extension library providing support for rich push notifications.
pod 'BrazePushStory' Notification content extension library providing support for Push Stories.

Step 1.3: Install the SDK

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

1

pod install

At this point, you should be able to open the new Xcode project workspace created by CocoaPods. Make sure to use this Xcode workspace instead of your Xcode project.

A Braze Example folder expanded to show the new `BrazeExample.workspace`.

Updating the SDK using CocoaPods

To update a CocoaPod, simply run the following command within your project directory:

1

pod update

Step 1.1: Download the Braze SDK

Go to the Braze SDK release page on GitHub, then download braze-swift-sdk-prebuilt.zip.

"The Braze SDK release page on GitHub."

Step 1.2: Choose your frameworks

The Braze Swift SDK contains a variety of standalone XCFrameworks, which gives you the freedom to integrate the features you want—without needing to integrate them all. Reference the following table to choose your XCFrameworks:

Package Required? Description
BrazeKit Yes Main SDK library that provides support for analytics and push notifications.
BrazeLocation No Location library that provides support for location analytics and geofence monitoring.
BrazeUI No Braze-provided user interface library for in-app messages and Content Cards.
BrazeNotificationService No Notification service extension library that provides support for rich push notifications. Do not add this library directly to your main application target, instead add the BrazeNotificationService library separately.
BrazePushStory No Notification content extension library that provides support for Push Stories. Do not add this library directly to your main application target, instead add the BrazePushStory library separately.
BrazeKitCompat No Compatibility library containing all the Appboy and ABK* classes and methods that were available in the Appboy-iOS-SDK version 4.X.X. For usage details, refer to the minimal migration scenario in the migration guide.
BrazeUICompat No Compatibility library containing all the ABK* classes and methods that were available in the AppboyUI library from Appboy-iOS-SDK version 4.X.X. For usage details, refer to the minimal migration scenario in the migration guide.
SDWebImage No Dependency used only by BrazeUICompat in the minimal migration scenario.

Decide whether you want to use Static or Dynamic XCFrameworks, then prepare your files:

  1. Create a temporary directory for your XCFrameworks.
  2. In braze-swift-sdk-prebuilt, open the dynamic directory and move BrazeKit.xcframework into your directory. Your directory should be similar to the following: 
    1
2

     temp_dir
 └── BrazeKit.xcframework
  3. Move each of your chosen XCFrameworks into your temporary directory. Your directory should be similar to the following: 
    1
2
3
4
5

     temp_dir
 ├── BrazeKit.xcframework
 ├── BrazeKitCompat.xcframework
 ├── BrazeLocation.xcframework
 └── SDWebImage.xcframework
Prepare your frameworks
  1. Create a temporary directory for your XCFrameworks.
  2. In braze-swift-sdk-prebuilt, open the static directory and move BrazeKit.xcframework into your directory. Your directory should be similar to the following: 
    1
2

    temp_frameworks_dir
└── BrazeKit.xcframework
  3. Move each of your chosen XCFrameworks into your temporary directory. Your directory should be similar to the following: 
    1
2
3
4
5

    temp_frameworks_dir
├── BrazeKit.xcframework
├── BrazeKitCompat.xcframework
├── BrazeLocation.xcframework
└── SDWebImage.xcframework
Prepare your bundles
  1. Create a temporary directory for your bundles.
  2. Open the bundles directory and move BrazeKit.bundle into your directory. Your directory should be similar to the following: 
    1
2

    temp_bundles_dir
└── BrazeKit.bundle
  3. If you’re using the BrazeLocation, BrazeUI, BrazeUICompat, or SDWebImage XCFrameworks, move their corresponding bundles into your temporary directory. Your directory should be similar to the following: 
    1
2
3
4
5

    temp_bundles_dir
├── BrazeLocation.bundle
├── BrazeUI.bundle
├── BrazeUICompat.bundle
└── SDWebImage.bundle

Step 1.4: Integrate your frameworks

Next, integrate the Dynamic or Static XCFrameworks you prepared previously:

In your Xcode project, select your build target, then General. Under Frameworks, Libraries, and Embedded Content, drag and drop the files you prepared previously.

"An example Xcode project with each Braze library set to 'Embed & Sign.'"

In your Xcode project, select your build target, then General. Under Frameworks, Libraries, and Embedded Content, drag and drop the frameworks you prepared previously. Next to each framework, choose Do Not Embed.

"An example Xcode project with each Braze library set to 'Do Not Embed.'"

While in your build target, select Build Phases. Under Copy Bundle Resources drag and drop the bundles you prepared previously.

"An example Xcode project with bundles added under 'Copy Bundle Resources.'"

Common errors for Objective-C projects

If your Xcode project only contains Objective-C files, you may get “missing symbol” errors when you try to build your project. To fix these errors, open your project and add an empty Swift file to your file tree. This will force your build toolchain to embed Swift Runtime and link to the appropriate frameworks during build time.

1

FILE_NAME.swift

Replace FILE_NAME with any non-spaced string. Your file should look similar to the following:

1

empty_swift_file.swift

Step 2: Update your app delegate

Add the following line of code to your AppDelegate.swift file to import the features included in the Braze Swift SDK:

1

import BrazeKit

Next, add a static property to your AppDelegate class to keep a strong reference to the Braze instance throughout your application’s lifetime:

1
2
3

class AppDelegate: UIResponder, UIApplicationDelegate {
  static var braze: Braze? = nil
}

Finally, in AppDelegate.swift, add the following snippet to your application:didFinishLaunchingWithOptions: method:

1
2
3
4
5
6

let configuration = Braze.Configuration(
    apiKey: "YOUR-APP-IDENTIFIER-API-KEY",
    endpoint: "YOUR-BRAZE-ENDPOINT"
)
let braze = Braze(configuration: configuration)
AppDelegate.braze = braze

Update YOUR-APP-IDENTIFIER-API-KEY and YOUR-BRAZE-ENDPOINT with the correct value from your App Settings page. Check out our API identifier types for more information on where to find your app identifier API key.

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

1

@import BrazeKit;

Next, add a static variable to your AppDelegate.m file to keep a reference to the Braze instance throughout your application’s lifetime:

1
2
3
4
5
6
7
8
9
10
11

static Braze *_braze;

@implementation AppDelegate
+ (Braze *)braze {
  return _braze;
}

+ (void)setBraze:(Braze *)braze {
  _braze = braze;
}
@end

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

1
2
3
4

BRZConfiguration *configuration = [[BRZConfiguration alloc] initWithApiKey:"YOUR-APP-IDENTIFIER-API-KEY"
                                                                  endpoint:"YOUR-BRAZE-ENDPOINT"];
Braze *braze = [[Braze alloc] initWithConfiguration:configuration];
AppDelegate.braze = braze;

Update YOUR-APP-IDENTIFIER-API-KEY and YOUR-BRAZE-ENDPOINT with the correct value from your Manage Settings page. Check out our API documentation for more information on where to find your app identifier API key.

Optional configurations

Logging

Log levels

The default log level for the Braze Swift SDK is .error—it’s also the minimum supported level when logs are enabled. These are the full ist of log levels:

Setting the log level

You can assign the log level at runtime in your Braze.Configuration object. For complete usage details, see Braze.Configuration.Logger.

1
2
3
4
5
6
7

let configuration = Braze.Configuration(
  apiKey: "<BRAZE_API_KEY>",
  endpoint: "<BRAZE_ENDPOINT>"
)
// Enable logging of general SDK information (such as user changes, etc.)
configuration.logger.level = .info
let braze = Braze(configuration: configuration)

1
2
3
4
5

BRZConfiguration *configuration = [[BRZConfiguration alloc] initWithApiKey:self.APIKey
                                                                  endpoint:self.apiEndpoint];
// Enable logging of general SDK information (such as user changes, etc.)
[configuration.logger setLevel:BRZLoggerLevelInfo];
Braze *braze = [[Braze alloc] initWithConfiguration:configuration];
Github   Edit this page on GitHub
HOW HELPFUL WAS THIS PAGE?
New Stuff!