Facebook SDK for TVML/TVJS apps

The new Apple TV supports client-server apps using TVML and TVJS files.

The Facebook SDK for tvOS provides TVML and TVJS extensions so you can build great social experiences for this style of app. This guide will describe what extensions are available and how to use them.

You should review the general Facebook SDK for tvOS guide for general information, available features and how to add the SDK to your project.

TVML

Getting started

The Facebook SDK for tvOS provides extensions to TVML via the FBSDKTVInterfaceFactory class. You should initialize a new instance of this class and assign it to the extendedInterfaceCreator property of the TVInterfaceFactory shared instance.

Example (in Swift):

TVInterfaceFactory.sharedInterfaceFactory().extendedInterfaceCreator = FBSDKTVInterfaceFactory()

The Facebook SDK for tvOS adds the following tags to TVML:

FBSDKLoginButton

Use the FBSDKLoginButton tag in your TVML files to easily add a "Login with Facebook" button to your template (this behaves just like the FBSDKDeviceLoginButton in native code).

The FBSDKLoginButton tag supports an optional attribute of either readPermissions or publishPermissions (not both) whose value is a comma delimited list of permissions to request.

The FBSDKLoginButton tag can dispatch the following events to Javascript, which map to corresponding messages of FBSDKDeviceLoginButtonDelegate:

  • onFacebookLogin
  • onFacebookLogout
  • onFacebookLoginCancel
  • onFacebookLoginError

For additional reference, consult the documentation on FBSDKTVLoginButtonElement class.

FBSDKLoginViewController

Use the FBSDKLoginViewController tag to present a FBSDKDeviceLoginViewController to ask for additional permissions. This FBSDKLoginViewController should be part of a document that is presented modally and not embedded in a typical TVML template.

Example (in TVJS script):

var createLogin = function() {
 var s = `<?xml version="1.0" encoding="UTF-8" ?>
 <document>
 <FBSDKLoginViewController publishPermissions="publish_actions" />
 </document>`
 return new DOMParser().parseFromString(s, "application/xml");
 }

 // in your code
 navigationDocument.presentModal(createLogin());

The FBSDKLoginViewController tag supports an optional attribute of either readPermissions or publishPermissions (not both) whose value is a comma delimited list of permissions to request.

The FBSDKLoginViewController tag can dispatch the following events to Javascript, which map to corresponding messages of FBSDKDeviceLoginViewControllerDelegate:

  • onFacebookLoginViewControllerFinish
  • onFacebookLoginViewControllerCancel
  • onFacebookLoginViewControllerError

For additional reference, consult the documentation on FBSDKTVLoginViewControllerElement class.

FBSDKShareButton

Use the FBSDKShareButton tag in your TVML files to easily add a "Share" button to your template (this behaves just like the FBSDKDeviceShareButton in native code). Tapping the button starts a Sharing For Devices flow.

You must set the share content by either: * setting the href attribute to a valid URL to share a link; or, * setting the action_type, object_url, and key attributes to share Open Graph content.

For additional reference, consult the documentation on FBSDKTVShareButtonElement class.

TVJS

Getting started

The Facebook SDK for tvOS provides extensions to TVJS via the FBSDKJS class. You should export this class type to the JSContext of your TVApplicationControllerDelegate.

Example (in Swift):

// In your TVApplicationControllerDelegate implementation
func appController(appController: TVApplicationController, evaluateAppJavaScriptInContext jsContext: JSContext) {
    // Add the TVML/TVJS extensions for FBSDK
    jsContext.setObject(FBSDKJS.self, forKeyedSubscript: "FBSDKJS")
}

Then, the following TVJS functions are available to your TVJS scripts. For additional reference, consult the documentation on the FBSDKJS class.

FBSDKJS.accessTokenString()

Returns the current access token string, if available. Use this to construct Graph API requests from your TVJS scripts.

FBSDKJS.hasGranted(permission)

Returns true if the user is logged in and has granted the permission. Use this to conditionally execute TVJS code. For example, you could use this to check if you need to ask for publish permissions in your app.

FBSDKJS.isLoggedIn()

Return true if the user is logged in. Use this to conditionally execute TVJS code. For example, you could check this on load of your initial TVML document to decide where to navigate.

FBSDKJS.logEventParameters(eventName, parameters)

Logs an event for app analytics (equivalent to FBSDKAppEvents logEvent:parameters:).

FBSDKJS.logPurchaseCurrencyParameters(purchaseAmount, currency, parameters)

Logs a purchase event for app analytics (equivalent to FBSDKAppEvents logPurchase:currency:parameters:).