tvOS

1. Install the SDK

The fastest and easiest way to use Localytics in your project is with CocoaPods. If you cannot use CocoaPods, use the manual installation approach.

1. Install CocoaPods by executing

   gem install cocoapods
   

2. If you don't already have a Podfile in your Xcode project directory, create one with the following command

   pod init
   

3. In your Podfile add the following content

   platform :tvos, '9.0'
   pod 'Localytics-tvOS', '~> 1.0'
   

4. Install the Localytics SDK by executing the following in your Xcode project directory

   pod install
   

5. Open the project workspace file (YOUR-PROJECT-NAME.xcworkspace) instead of the project file (YOUR-PROJECT-NAME.xcodeproj) to ensure that the Localytics dependency is properly loaded.

2. Initialize the SDK

In order to run the Localytics SDK, you must initialize the SDK using your Localytics app key. You can find your app key in the Localytics Dashboard.

If you have an app with extensive, engaged usage in the background, or you require more fine control over the session lifecycle (most apps don't), use manual integration.

In your application's delegate file:

1. Import the Localytics SDK under any existing imports.

   Objective-C Swift

   @import Localytics;
   

   import Localytics
   

2. Add the following line to the start of didFinishLaunchingWithOptions:.

   Objective-C Swift

   [Localytics autoIntegrate:@"YOUR-LOCALYTICS-APP-KEY" launchOptions:launchOptions];
   

   Localytics.autoIntegrate("YOUR-LOCALYTICS-APP-KEY", launchOptions: launchOptions)
   

3. Compile and run your app.

More information on using the Localytics SDK within a Swift project is available here.

3. Next steps

Congratulations! You have successfully performed the basic Localytics integration and are now sending session data to Localytics. You have everything you need to track where your most highly engaged users are coming from.

Note that it may take a few minutes for your first datapoints to show up within the Localytics Dashboard. In the meantime, we suggest reading the next few sections to learn how to:

1. Track one user action as an event
2. Track one user property as a profile attribute

We recommend doing these things before releasing your app for the first time with Localytics.

Standard events

Standard events make it easier to analyze user behavior and optimize your app marketing around common business goals such as driving user registrations or purchases. You can also tag custom events for other user behavior in your app that doesn't match one of the standard events.

[Localytics tagPurchased:@"Shirt"
                  itemId:@"sku-123"
                itemType:@"Apparel"
               itemPrice:@15
              attributes:extraAttributes];

Localytics.tagPurchased("Shirt", itemId: "sku-123", itemType: "Apparel", itemPrice: 15, attributes: extraAttributes)

[Localytics tagAddedToCart:@"Shirt"
                    itemId:@"sku-123"
                  itemType:@"Apparel"
                 itemPrice:@15
                attributes:extraAttributes];

Localytics.tagAddedToCart("Shirt", itemId: "sku-123", itemType: "Apparel", itemPrice: 15, attributes: extraAttributes)

[Localytics tagStartedCheckout:@50
                     itemCount:@2
                    attributes:extraAttributes];

Localytics.tagStartedCheckout(50, itemCount: 2, attributes: extraAttributes)

[Localytics tagCompletedCheckout:@50
                       itemCount:@2
                      attributes:extraAttributes];

Localytics.tagCompletedCheckout(50, itemCount: 2, attributes: extraAttributes)

[Localytics tagContentViewed:@"Top 10"
                   contentId:@"e8z7319zbe"
                 contentType:@"Article"
                  attributes:extraAttributes];

Localytics.tagContentViewed("Top 10", contentId: "e8z7319zbe", contentType: "Article", attributes: extraAttributes)

[Localytics tagSearched:@"Celtics"
            contentType:@"Sports"
            resultCount:@15
             attributes:extraAttributes];

Localytics.tagSearched("Celtics", contentType: "Sports", resultCount: 15, attributes: extraAttributes)

[Localytics tagShared:@"Top 10"
            contentId:@"e8z7319zbe"
          contentType:@"Article"
           methodName:@"Twitter"
           attributes:extraAttributes];

Localytics.tagShared("Top 10", contentId: "e8z7319zbe", contentType: "Article", methodName: "Twitter", attributes: extraAttributes)

[Localytics tagContentRated:@"Headlines"
                  contentId:@"8a4z5j9q"
                contentType:@"Song"
                     rating:@5
                 attributes:extraAttributes];

Localytics.tagContentRated("Headlines", contentId: "8a4z5j9q", contentType: "Song", rating: 5, attributes: extraAttributes)

[Localytics tagCustomerRegistered:[LLCustomer customerWithBlock:^(LLCustomerBuilder *builder) {
          builder.customerId = @"3neRKTxbNWYKM4NJ";
          builder.firstName = @"John";
          builder.lastName = @"Smith";
          builder.fullName = @"Mr. John Smith, III";
          builder.emailAddress = @"john@smith.com";
      }]
                       methodName:@"Facebook"
                       attributes:extraAttributes];

Localytics.tagCustomerRegistered((LLCustomer { (builder) in
  builder.customerId = "3neRKTxbNWYKM4NJ"
  builder.firstName = "John"
  builder.lastName = "Smith"
  builder.fullName = "Mr. John Smith, III"
  builder.emailAddress = "john@smith.com"
}), methodName: "Facebook", attributes: extraAttributes)

[Localytics tagCustomerLoggedIn:[LLCustomer customerWithBlock:^(LLCustomerBuilder *builder) {
          builder.customerId = @"3neRKTxbNWYKM4NJ";
          builder.firstName = @"John";
          builder.lastName = @"Smith";
          builder.fullName = @"Mr. John Smith, III";
          builder.emailAddress = @"john@smith.com";
      }]
                     methodName:@"Native"
                     attributes:extraAttributes];

Localytics.tagCustomerLoggedIn((LLCustomer { (builder) in
  builder.customerId = "3neRKTxbNWYKM4NJ"
  builder.firstName = "John"
  builder.lastName = "Smith"
  builder.fullName = "Mr. John Smith, III"
  builder.emailAddress = "john@smith.com"
}), methodName: "Native", attributes: extraAttributes)

[Localytics tagCustomerLoggedOut:extraAttributes];

Localytics.tagCustomerLoggedOut(extraAttributes)

[Localytics tagInvited:@"SMS"
            attributes:extraAttributes];

Localytics.tagInvited("SMS", attributes: extraAttributes)

Custom event

Objective-C Swift

[Localytics tagEvent:@"Team Favorited"];

Localytics.tagEvent("Team Favorited")

Custom event with attributes

Objective-C Swift

[Localytics tagEvent:@"Team Favorited"
          attributes:@{@"Team Name" : @"Celtics", @"City" : @"Boston"}];

Localytics.tagEvent("Team Favorited", attributes: ["Team Name" : "Celtics", "City" : "Boston"])

Customer ID

Objective-C Swift

[Localytics setCustomerId:@"3neRKTxbNWYKM4NJ"];

Localytics.setCustomerId("3neRKTxbNWYKM4NJ")

Customer first name

Objective-C Swift

[Localytics setCustomerFirstName:@"John"];

Localytics.setCustomerFirstName("John")

Customer last name

Objective-C Swift

[Localytics setCustomerLastName:@"Smith"];

Localytics.setCustomerLastName("Smith")

Customer full name

Objective-C Swift

[Localytics setCustomerFullName:@"Sir John Smith, III"];

Localytics.setCustomerFullName("Sir John Smith, III")

Customer email address

Objective-C Swift

[Localytics setCustomerEmail:@"sir.john@smith.com"];

Localytics.setCustomerEmail("sir.john@smith.com")

Setting a profile attribute value

[Localytics setValue:@45 forProfileAttribute:@"Age" withScope:LLProfileScopeOrganization];

Localytics.setValue(45, forProfileAttribute: "Age", with: .organization)

[Localytics setValue:@[@8, @13] forProfileAttribute:@"Lucky Numbers" withScope:LLProfileScopeApplication];

Localytics.setValue([8, 13], forProfileAttribute: "Lucky numbers", with: .application)

[Localytics setValue:[NSDate date] forProfileAttribute:@"Last Purchase Date" withScope:LLProfileScopeOrganization];

Localytics.setValue(NSDate(), forProfileAttribute: "Last Purchase Date", with: .organization)

NSDateFormatter* dateFormatter = [[NSDateFormatter alloc] init];
[dateFormatter setDateFormat:@"MM-dd-yyyy"];
[Localytics setValue:@[[dateFormatter dateFromString:@"10-01-2015"], [dateFormatter dateFromString:@"03-17-2016"]] forProfileAttribute:@"Upcoming Milestone Dates" withScope:LLProfileScopeApplication];

let dateFormatter = DateFormatter()
dateFormatter.dateFormat = "MM-dd-yyyy"
Localytics.setValue([dateFormatter.date(from: "10-01-2015")!, dateFormatter.date(from: "03-17-2016")!], forProfileAttribute: "Upcoming Milestone Dates", with: .application)

[Localytics setValue:@"New York, New York" forProfileAttribute:@"Hometown" withScope:LLProfileScopeOrganization];

Localytics.setValue("New York, New York", forProfileAttribute: "Hometown", with: .organization)

[Localytics setValue:@[@"New York", @"California", @"South Dakota"] forProfileAttribute:@"States Visited" withScope:LLProfileScopeApplication];

Localytics.setValue(["New York", "California", "South Dakota"], forProfileAttribute: "States Visited", with: .application)

Removing a profile attribute

Objective-C Swift

[Localytics deleteProfileAttribute:@"Days Until Graduation" withScope:LLProfileScopeApplication];

Localytics.deleteProfileAttribute("Days Until Graduation", with: .application)

Adding to a set of profile attribute values

[Localytics addValues:@[@8] toSetForProfileAttribute:@"Lucky Numbers" withScope:LLProfileScopeApplication];

Localytics.addValues([8], toSetForProfileAttribute: "Lucky Numbers", with: .application)

NSDateFormatter* dateFormatter = [[NSDateFormatter alloc] init];
[dateFormatter setDateFormat:@"MM-dd-yyyy"];
[Localytics addValues:@[[dateFormatter dateFromString:@"04-19-2015"], [dateFormatter dateFromString:@"12-24-2015"]] toSetForProfileAttribute:@"Upcoming Milestone Dates" withScope:LLProfileScopeApplication];

let dateFormatter = DateFormatter()
dateFormatter.dateFormat = "MM-dd-yyyy"
Localytics.addValues([dateFormatter.date(from: "4-19-2015")!, dateFormatter.date(from: "12-24-2015")!], toSetForProfileAttribute: "Upcoming Milestone Dates", with: .application)

[Localytics addValues:@[@"North Dakota"] toSetForProfileAttribute:@"States Visited" withScope:LLProfileScopeApplication];

Localytics.addValues(["North Dakota"], toSetForProfileAttribute: "States Visited", with: .application)

Removing from a set of profile attribute values

[Localytics removeValues:@[@8, @9] fromSetForProfileAttribute:@"Lucky Numbers" withScope:LLProfileScopeApplication];

Localytics.removeValues([8, 9], fromSetForProfileAttribute: "Lucky Numbers", with: .application)

NSDateFormatter* dateFormatter = [[NSDateFormatter alloc] init];
[dateFormatter setDateFormat:@"MM-dd-yyyy"];
[Localytics removeValues:@[[dateFormatter dateFromString:@"03-17-2016"]] fromSetForProfileAttribute:@"Upcoming Milestone Dates" withScope:LLProfileScopeApplication];

let dateFormatter = DateFormatter()
dateFormatter.dateFormat = "MM-dd-yyyy"
Localytics.removeValues([dateFormatter.date(from: "03-17-2016")!], fromSetForProfileAttribute: "Upcoming Milestone Dates", with: .application)

[Localytics removeValues:@[@"California"] fromSetForProfileAttribute:@"States Visited" withScope:LLProfileScopeApplication];

Localytics.removeValues(["California"], fromSetForProfileAttribute: "States Visited", with: .application)

Incrementing a numeric profile attribute value

Objective-C Swift

[Localytics incrementValueBy:1 forProfileAttribute:@"Age" withScope:LLProfileScopeOrganization];

Localytics.incrementValueBy(1, forProfileAttribute: "Age", with: .organization)

Decrementing a numeric profile attribute value

Objective-C Swift

[Localytics decrementValueBy:3 forProfileAttribute:@"Days Until Graduation" withScope:LLProfileScopeApplication];

Localytics.decrementValueBy(3, forProfileAttribute: "Days Until Graduation", with: .application)

Setting a value

Objective-C Swift

[Localytics setValue:@"Trial" forCustomDimension:0];

Localytics.setValue("Trial", forCustomDimension: 0)

Initializing dimensions before session start

Set the value of all custom dimensions as early as possible in your app's code path even if you only set the value to "Not applicable" or "Not available". Having at least some value for each custom dimension instead of nothing will prevent the display of "[Unspecified]" values in the Dashboard and help to make it much more obvious to distinguish intentionally missing values from unintentionally missing values.

1. In your app delegate header file, ensure that your app delegate conforms to the LLAnalyticsDelegate protocol as follows.

   Objective-C Swift

   @interface YourAppDelegate : UIResponder <UIApplicationDelegate, TVApplicationControllerDelegate, LLAnalyticsDelegate>
   

   class AppDelegate: UIResponder, UIApplicationDelegate, TVApplicationControllerDelegate, LLAnalyticsDelegate {
   

2. Modify your app delegate as follows to register the Localytics analytics delegate and set any custom dimension values before the first session opens. You will need to modify the custom dimension code below to match your exact custom dimension values.

   Objective-C Swift

   - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
       // ...Localytics initialization code here...
   
       [Localytics setAnalyticsDelegate:self];
   
       // ... rest of didFinishLaunchingWithOptions ...
   
       return YES;
   }
   
   - (void)localyticsSessionWillOpen:(BOOL)isFirst isUpgrade:(BOOL)isUpgrade isResume:(BOOL)isResume {
       if (isFirst) {
           [Localytics setValue:@"Logged Out" forCustomDimension:0];
           [Localytics setValue:@"0" forCustomDimension:1];
           // ...rest of custom dimensions go here...
       }
   }
   

   func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
     // ...Localytics initialization code here...
   
     Localytics.setAnalyticsDelegate(self)
   
     // ... rest of didFinishLaunchingWithOptions ...
   
     return true
   }
   
   func localyticsSessionWillOpen(_ isFirst: Bool, isUpgrade: Bool, isResume: Bool) {
     if isFirst {
       Localytics.setValue("Logged Out", forCustomDimension: 0)
       Localytics.setValue("0", forCustomDimension: 1)
       // ...rest of custom dimensions go here...
     }
   }
   

Clearing a value

Though it may be more appropriate to set a custom dimension value back to an initial state, sometimes you may need to completely clear the value. Setting an an empty string will NOT clear the value. To clear a value use the following code:

Objective-C Swift

[Localytics setValue:nil forCustomDimension:0];

Localytics.setValue(nil, forCustomDimension:0)

Manual Installation

If you do not wish to install the SDK using CocoaPods, the following manual approach will install the SDK and its dependencies.

1. Delete any existing Localytics files from your project.
2. Download the latest version of the SDK.
3. Unzip it and drag Localytics.framework into the top level of your Xcode project in the Project Navigator (Command + 1).
1. When prompted, use the checkboxes to add the framework to the specific target for which you are compiling. Check the "copy items if needed" box.
2. By default, XCode will add the framework to the Link Binaries with Libraries section of the Project File. This is incorrect for a dynamically linked framework and will result in errors when running the app. Remove the reference to Localytics.Framework in Link Binaries with Libraries and add it to Embedded Binaries section. Note: This will add a new reference to the Link Binaries with Libraries section that does not need to be removed.
3. For each target that includes Localytics.Framework repeat the above step.
4. Add AdSupport.framework, libz.tbd, and SystemConfiguration.framework to your project.
   1. Enter Project Navigator view and click on your project icon. It should be at the top of the Project Navigator.
   2. Select your target from the sidebar or from the dropdown menu, then select the Build Phases tab.
   3. Open the Link Binaries with Libraries expander and click +. Find each library from the list, clicking Add each time.
5. Add the -ObjC other linker flag to your build settings.
   1. Enter Project Navigator view and click on your project icon. It should be at the top of the Project Navigator.
   2. Select the Build Phases tab.
   3. Select the All option and type Other Linker Flags into the search box.
   4. Double click on the right side of the Other Linker Flags and add the text -ObjC.

6. When submitting a tvOS app build to iTunes Connect for distribution you'll have to remove the simulator-compatible (x86) version of all frameworks your app uses, including Localytics.

   Rather than shipping a simulator-incompatible library or forcing our users to swap to a "skinny" version of our library at build time, the easiest way to ship without the simulator architecture is to add a script to your build process that removes the "fat" architectures used by the simulator.

   
   1. Enter Project Naviator view and click on your project icon. It should be at the top of the Project Navigator.
   2. Select your target from the sidebar or from the dropdown menu, then select the Build Phases tab.
   3. Press the + in the top left and add a new run script phase after the embed frameworks step.
   4. Inside the Run Script phase make sure that the Shell is /bin/sh and insert the following code:

      APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"
      # This script loops through the frameworks embedded in the application and
      # removes unused architectures.
      find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK
      
      do
        FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
        FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"
      
        echo "Executable is $FRAMEWORK_EXECUTABLE_PATH"
        EXTRACTED_ARCHS=()
      
        echo "ARCHS = $ARCHS"
      
        INFO_OUTPUT_STR=`lipo -info "$FRAMEWORK_EXECUTABLE_PATH"`
        if [[ $INFO_OUTPUT_STR == *"Non-fat file"* ]]
        then
          echo "Framework is not a Fat binary, skipping..."
          continue
        fi
      
        for ARCH in $ARCHS
        do
          echo "Extracting $ARCH from $FRAMEWORK_EXECUTABLE_NAME"
          lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o "$FRAMEWORK_EXECUTABLE_PATH-$ARCH"
          EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH")
        done
      
        echo "Merging extracted architectures: ${ARCHS}"
        lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"
        rm "${EXTRACTED_ARCHS[@]}"
      
        echo "Replacing original executable with thinned version"
        rm "$FRAMEWORK_EXECUTABLE_PATH"
        mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH"
      done
          
      

You are now ready to continue with the setup process here.

Manual Integration

The standard Localytics session management approach relies on the Localytics SDK to automatically listen for indications of state change (e.g. foreground / background transitions) in your app and then to track the state change accordingly. Most apps are able to use the standard approach. If you are unable to use the standard session management approach, the instructions below will help you to initialize the SDK to achieve the same result as the standard approach.

Use the following initialization instructions instead of those in Getting started. If you have an app with extensive, engaged user activity in the background, as is common with streaming media apps, you may find it necessary reposition calls to openSession and closeSession to achieve the session behavior you desire. Enabling logging when modifying session behavior is often very helpful.

In your application's delegate file:

1. Import the Localytics SDK under any existing imports.

   Objective-C Swift

   @import Localytics;
   

   import Localytics
   

2. Add the following code to the start of application:didFinishLaunchingWithOptions:.

   Objective-C Swift

   [Localytics integrate:@"YOUR-LOCALYTICS-APP-KEY"];
   
   if (application.applicationState != UIApplicationStateBackground) {
       [Localytics openSession];
   }
   

   Localytics.integrate("YOUR-LOCALYTICS-APP-KEY")
   
   if application.applicationState != .background {
     Localytics.openSession()
   }
   

3. Add the following code to the start of both applicationDidBecomeActive: and applicationWillEnterForeground:.

   Objective-C Swift

   [Localytics openSession];
   

   Localytics.openSession()
   

4. Add the following code to the start of applicationDidEnterBackground:.

   Objective-C Swift

   [Localytics closeSession];
   

   Localytics.closeSession()
   

5. Compile and run your app.

Swift

The Localytics SDK is written in Objective-C but to simplify the process of integrating it with Swift the public APIs have been annotated with nullable and nonnull annotations, collections take advantage of light weight generics, and the SDK is available as a dynamic framework. Calling SDK methods is a straight forward translation from bracket notation to dot notation.

class AppDelegate: UIResponder, UIApplicationDelegate, TVApplicationControllerDelegate {
    static var originalAppDelegate:AppDelegate!

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
    AppDelegate.originalAppDelegate = self
        

AppDelegate.originalAppDelegate.someMethod()

Callbacks

Setting a custom identifier

Once a custom identifier is set, it is attached to each subsequent datapoint, similar to the behavior of custom dimensions. Unlike custom dimensions, however, custom identifiers only end up in export data. They are useful for attaching multiple unique identifiers to a given datapoint for use in joining your Localytics export data with other sources in an enterprise data warehouse. Custom identifiers are not used by the Localytics backend or Dashboard for anything and are just passed through to the export data.

Objective-C Swift

[Localytics setValue:@"Black" forIdentifier:@"Hair Color"];

Localytics.setValue("Black", forIdentifier:"Hair Color")

Creating an explicit App ID

1. Log in to the Apple Developer console and go to Certificates, Identifiers & Profiles.
2. Under Identifiers, select App IDs and then click the Add button (+) in the upper-right corner.
3. Enter a description, select your Team ID as the App ID Prefix, enter an Explicit App ID that exactly matches your Bundle ID, and then click Continue.
4. Verify the information you entered and then click Register.