Completing the Integration

Requirements

Before following these steps, make sure you have integrated the SDK using one of the installation options listed before this page.

Step 1: Update Your App Delegate

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

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

If you are integrating the Braze SDK with Swift Package Manager or the Manual Integration Options, add the following line of code to your AppDelegate.m file:

1
#import "AppboyKit.h"

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

1
2
3
[Appboy startWithApiKey:@"YOUR-APP-IDENTIFIER-API-KEY"
          inApplication:application
      withLaunchOptions:launchOptions];

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

1
import Appboy_iOS_SDK

If you are integrating the Braze SDK with Swift Package Manager, add the following line of code to your AppDelegate.swift file:

1
import AppboyKit

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

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

1
Appboy.start(withApiKey: "YOUR-APP-IDENTIFIER-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.

Step 2: Specify Your Data Cluster

If given a pre-existing custom endpoint…

  • Starting with Braze iOS SDK v3.0.2, you can set a custom endpoint using the Info.plist file. Add the Braze dictionary to your Info.plist file. Inside the Braze dictionary, add the Endpoint string subentry and set the value to your custom endpoint URL’s authority (for example, sdk.iad-01.braze.com, not https://sdk.iad-01.braze.com). Note that prior to Braze iOS SDK v4.0.2, the dictionary key Appboy must be used in place of Braze.

Your Braze representative should have already advised you of the correct endpoint.

Runtime Endpoint Configuration

If given a pre-existing custom endpoint…

  • Starting with Braze iOS SDK v3.17.0+, you can override set your endpoint via the ABKEndpointKey inside the appboyOptions parameter passed to startWithApiKey:inApplication:withLaunchOptions:withAppboyOptions:. Set the value to your custom endpoint URL’s authority (for example, sdk.iad-01.braze.com, not https://sdk.iad-01.braze.com).

SDK Integration Complete

Braze should now be collecting data from your application and your basic integration should be complete.

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:

1
2
3
4
[Appboy startWithApiKey:@"YOUR-APP-IDENTIFER-API-KEY"
          inApplication:application
      withLaunchOptions:launchOptions
      withAppboyOptions:appboyOptions];

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

1
2
3
4
Appboy.start(withApiKey: "YOUR-APP-IDENTIFIER-API-KEY",
                 in: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-APP-IDENTIFIER-API-KEY – Your App Identifier 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.

Documentation

Full iOS class documentation is available to provide additional guidance on any of the SDK’s methods.

WAS THIS PAGE HELPFUL?
New Stuff!