Initial SDK setup

This reference article covers how to install the Braze SDK for tvOS. Installing the Braze SDK will provide you with basic analytics functionality.

The tvOS 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.

tvOS SDK CocoaPods integration

Step 1: Install CocoaPods

Installing the SDK via the tvOS CocoaPods automates the majority of the installation process for you. Before beginning this process, ensure that you are using Ruby version 2.0.0 or greater.

Run the following command to get started:

1
$ sudo gem install cocoapods

• If you are prompted to overwrite the rake executable, refer to Getting started on CocoaPods.org for further details.
• If you have issues regarding CocoaPods, 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.

Add the following line to your Podfile:

1
2
3
target 'YourAppTarget' do
  pod 'Appboy-tvOS-SDK'
end

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

Step 3: Installing the Braze SDK

To install the Braze SDK CocoaPods, 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.

Step 4: Updating your app delegate

• objective-c
• swift

1
#import <AppboyTVOSKit/AppboyKit.h>

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

1
import AppboyTVOSKit

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

Step 5: Specify your custom endpoint or data cluster

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

Compile-time endpoint configuration (recommended)

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 Appboy dictionary to your Info.plist file. Inside the Appboy dictionary, add the Endpoint string subentry and set the value to your custom endpoint URLs authority (for example, sdk.iad-01.braze.com, not https://sdk.iad-01.braze.com).

Runtime endpoint configuration

If given a pre-exisiting 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 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. Note that when compiling your tvOS app and any other third-party libraries, Bitcode must be enabled.

Updating the Braze SDK via CocoaPods

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

1
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.

• objective-c
• swift

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

1
2
3
4
Appboy.start(withApiKey: "YOUR-API-KEY",
                 in:application,
                 withLaunchOptions:launchOptions,
                 withAppboyOptions:appboyOptions)

This method would replace the startWithApiKey:inApplication:withLaunchOptions: initialization method and is called with the following parameters:

• YOUR-API-KEY: Your application’s API key is found under Manage Settings in 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. This is because 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.

Manual integration options

You can also integrate our tvOS SDK manually - simply grab the Framework from our Public Repository and initialize Braze as outlined in the preceding sections.

Identifying users and reporting analytics

See our iOS documentation for information about setting user ids, logging custom events, setting user attributes. We also recommend familiarizing yourself with our event naming conventions.