tvOS apps for AppleTV

Similar to interacting with, retaining and engaging users on iOS, Android, Unity, Web, iMessage and Xamarin apps, via push notifications and In-App messages, marketers can interact with users who have downloaded your tvOS app for Apple TV.

The right marketing at the right time helps app publishers convert, retain and engage users effectively.

The main challenges for growing a tvOS app audience are retaining and engaging users.

tvOS apps have a unique interaction model and apps are expected to offer intuitive user experiences utilizing the Apple Siri Remote and game controllers.  tvOS also supports on-demand resources which allows tvOS apps to have access to 20GB of content. This improves download times of the initial app whilst adding richer app experiences. tvOS apps must pay special attention to app loading and gradual on boarding experience.

Thoughtfully designing while keeping the unique interaction model and gradual on boarding process in mind can help make your app more appealing to users.  Using push notifications is proven to bringing users back to your tvOS app and personalized in-app messages helps in engaging users.

In this blog post we will show you how easy it is for tvOS app developers to

1. implement Pyze with a line of code
2. add events for tracking usage
3. enable in-app notifications and
4. enable push notifications.

We will use an open-source tvOS app TVPong for this example.

Pong is a two-dimensional sports game that simulates table tennis. The player controls an in-game paddle by moving it vertically across the left side of the screen, and can compete against either a computer-controlled opponent or another player controlling a second paddle on the opposing side. Players use the paddles to hit a ball back and forth. The aim is for each player to reach eleven points before the opponent; points are earned when one fails to return the ball to the other. – wikipedia

You can download the tvOS sample app we will use from here.  It is a modified version of TVPong by Andrew Erickson that has been ported to Swift 3 and tested with Xcode 8.2.1. and Swift 3.0.2.  The original is here: https://github.com/aerickson14/TVPong

Install Pyze SDK for tvOS

You may want to refer to the Pyze documentation for tvOS. Follow along below for modifying the TVPong tvOS app. Compile the app which you downloaded from here.

Open the Terminal application and ‘cd’ to the downloaded folder source and execute pod init.

$ cd path/to/where/you/downloaded/tvOS/Sample/app
$ pod init # This will create the Podfile
$ ls Podfile
Podfile

Open the newly created Podfile and add the following line below # Pods for Pong.  Note do not use Textedit to edit Podfile, as it converts the quotes like ‘ to rich quotes like ‘ and ’ which causes errors. To open podfile using Xcode:

$ open -a Xcode Podfile

The final Podfile should look like:

# Uncomment this line to define a global platform for your project
# platform :ios, '9.0'

target 'Pong' do
    # Comment this line if you're not using Swift and don't want to use dynamic frameworks
 use_frameworks!

# Pods for Pong
 pod 'pyze-sdk-tvOS'

target 'PongTests' do
 inherit! :search_paths
 # Pods for testing
 end

end

Save and close Podfile.

In Terminal, execute pod install command, this will download and auto integrate the Pyze SDK for tvOS to the Pong source code.

$ pod install
Analyzing dependencies
Downloading dependencies
Installing pyze-sdk-tvOS (3.0.0)
Generating Pods project
Integrating client project

[!] Please close any current Xcode sessions and use `Pong.xcworkspace` for this project from now on.
Sending stats
Pod installation complete! There is 1 dependency from the Podfile and 1 total pod installed.

Get a Pyze App Key from growth.pyze.com

Open browser and go to ‘growth.pyze.com’ and create a new tvOS app and copy the PAK.

Enable Pyze

Open the AppDelegate.swift file import

import Pyze

Add …willFinishLaunchingWithOptions… method with Pyze.Initialize, using the Pyze App Key (PAK) obtained from growth.pyze.com above, in place of

func application(_ application: UIApplication, 
            willFinishLaunchingWithOptions launchOptions: 
               [UIApplicationLaunchOptionsKey : Any]? = nil) -> Bool {
     Pyze.initialize("your_PAK", 
        withLogThrottling: .PyzelogLevelMinimal)
     return true
}

Remember to replace your_PAK with the Pyze App Key (PAK) from https://growth.pyze.com

Adding events to tvOS app

Add an event when the game starts. Locate file StartMenuViewController.swift under Controllers.  Ensure you import Pyze on top of file

import Pyze

Add postGameStart event in function startGamePressed.

@IBAction func startGamePressed(_ sender: AnyObject) {
    NSLog("start game")
    PyzeGaming.postGameStart("\(gameConfig.difficulty)",
        withAttributes: [:])
}

Above is simple example to demonstrate posting of events. Pyze has extensive support for events.

Enable In-App Notifications in tvOS app

Now open storyboard and add a button called ‘Messages‘ and fix any constraints if found.  Add a ‘Primary Action Triggered’ action to StartMenuViewController.swift and create a method: showMessages.

@IBAction func showMessages(_ sender: UIButton) {
    print("Show Messages")
    Pyze.showInAppNotificationUI(forDisplayMessages: .typeAll,
                                 navigationTextColor: UIColor.white) {
                                    (inAppStatus) in
                                    print("inAppStatus printed")
    }
}

tvOS apps are controlled by the Apple remote and therefore you must call another method to properly dismiss in-app user interfaces on press of physical button e.g, Menu, +/-, Siri, Play/Pause and TV button.

You have to register one of your views as gesture recognizer. You can do so by overriding the pressesEnded method.  In this example, you can dismiss the in-app notification by pressing the Menu button.  Add this method in StartMenuViewController.swift

// Example handler dismisses in-app on pressing Apple TV remote's Menu button.
override func pressesEnded(_ presses: Set, 
                   with event: UIPressesEvent?) {
    for press in presses {
        if(press.type == UIPressType.menu) {
            Pyze.dismiss(inAppNotificationUI: true)
            super.pressesEnded(presses, with: event)
        }
    }
}

Enable Push notifications in tvOS app

For push notification support first you need to have push certificates and need to upload p12 to growth.pyze.com as described here.

Import UserNotifications in AppDelegate.swift

...
import UIKit
import Pyze
import UserNotifications
...

Add the UNUserNotificationCenterDelegate to AppDelegate

...
@UIApplicationMain
class AppDelegate: UIResponder, 
                   UIApplicationDelegate, 
                   UNUserNotificationCenterDelegate {
...

After that add the following in didFinishLaunchingwithOptions to AppDelegate.swift

    //Request user permission    
    func application(application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions:
        [NSObject: AnyObject]?) -> Bool {

        // Override point for customization after application launch.
        if #available(tvOS 10.0, *) {
            let center = UNUserNotificationCenter.current()
            center.delegate = self
            center.requestAuthorization(options: [.alert, .sound, .badge]                                        completionHandler: {
                                            (granted, error) in
                if error == nil {
                    UIApplication.shared.registerForRemoteNotifications()
                }
            })
        } else {
            print("Push service is not supported below tvOS 10.x.x")
        }
        return true
    }

Let Pyze know about the device token received from APNS. Add this method:

    //Let Pyze manage received device token
    func application(_ application: UIApplication, 
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        //print(deviceToken)
        Pyze.setRemoteNotificationDeviceToken(deviceToken)
    }

This registers push notification from App.

Add the following lines to handle the push notification upon receiving to AppleTV and add it after the AppDelegate implementation.  Note we created this as an extension.

extension AppDelegate : UNUserNotificationCenterDelegate {
    @available(tvOS 10.0, *)
    func userNotificationCenter(_           center: UNUserNotificationCenter,
                                willPresent notification: UNNotification,
                                withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
        
        print("tvOS push delivered")
        
        let content = notification.request.content.mutableCopy() as? UNMutableNotificationContent
        
        if let uid = content?.userInfo {
            // handle push notification
            Pyze.processReceivedRemoteNotification(uid)
            
            if let aps = uid["aps"] as? NSDictionary {
                if let alert = aps["alert"] as? NSDictionary {
                    if let title = alert["title"] as? NSString {
                        if let body = alert["body"] as? NSString {
                            let alertC = UIAlertController.init(title: title as String, message: body as String, preferredStyle: .alert)
                            let action = UIAlertAction.init(title: "OK", style: .default, handler: { (alertAction) in print("Alert action") })
                            alertC.addAction(action)
                            if let c = UIApplication.shared
                                .keyWindow?.rootViewController {
                                c.present( alertC, animated: true, completion: { print("Alert presented") })
                            }
                        }
                    }
                }
            }
        }
    }
}

Compile and run the app!

You can also download the final version of the source code from here.

---

Ram Naragund & Dickey Singh contributed to this blog.  Please let us know, if you have any questions implementing Pyze on your tvOS app.

---