Initial SDK Setup

Note: Our tvOS SDK currently supports analytics functionality and fetching News Feed data. To add a tvOS app in your dashboard please contact support@appboy.com.

Installing the Appboy SDK will provide you with basic analytics functionality.

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

Time Estimate: 5-10 Minutes

tvOS SDK CocoaPod Integration

Step 1: Install CocoaPods

Installing the SDK via the tvOS 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 CocoaPods.org 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 8+, add the following line to your Podfile:

target 'YourAppTarget' do
  pod 'Appboy-tvOS-SDK', '~>2.26'
end

If you are using Xcode 7 or earlier, please use SDK version 2.23.

Note: We suggest you version Appboy 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 integrate the latest version of Appboy SDK automatically even with major changes, you can use pod 'Appboy-tvOS-SDK' in your Podfile.

.

Example Podfile

If you would like to see an example, see the Podfile within our Stopwatch Sample Application.

Step 3: Installing the Appboy SDK

To install the Appboy 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 <AppboyTVOSKit/AppboyKit.h>

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

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

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

#import AppboyTVOSKit

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:

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

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

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

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

Implementation Example

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

SDK Integration Complete

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

Updating the Appboy SDK via CocoaPods

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

pod update

Customizing Appboy On Startup

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

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

[Appboy startWithApiKey:@"YOUR-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 Appboy 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 Appboy Dashboard
  • application – The current app
  • launchOptions – The options NSDictionary that you get from application:didFinishLaunchingWithOptions:
  • appboyOptions – An optional NSDictionary with startup configuration values for Appboy

See Appboy.h for a list of Appboy 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.

TVML Example

See the TVML target of our sample application for an example of creating a javascript bridge to the Appboy interface.

Manual Integration Options

You can also integrate our tvOS SDK manually - simply grab the Framework from our Public Repo and initialize Appboy as outlined above.

Identifying Users and Reporting Analytics

See our iOS documentation for information about setting user ids, logging custom events, settting user attributes.

News Feed

The News Feed is a fully customizable in-app content feed for your users. Our targeting and segmentation allows you to create a stream of content that is individually catered to the interests of each user. Depending on their position in the user life cycle and the nature of your app, this could be an on-boarding content server, an advertisement center, an achievement center, or a generic news center.

tvOS Feed Integration

Our tvOS SDK supports fetching your News Feed data, such that you can display the News Feed in your application with your own custom UI. To fetch the news feed, call

NSArray *feedCards =  [[Appboy sharedInstance].feedController getNewsFeedCards];

and then parse each card by inspecting it’s class, as we do in our Sample application.