Engage SDK for TV integration guide

Important: Express interest in developing the Video Discovery API.

Continue Watching leverages the Continuation cluster to show unfinished videos, and next episodes to be watched from the same TV season, from multiple apps in one UI grouping. You can feature their entities in this continuation cluster. Follow this guide to learn how to enhance user engagement through the Continue Watching experience using Engage SDK.

Pre-work

Before you begin, complete the following steps:

1. update to Target API 19 or higher

2. Add the com.google.android.engage library to your app:

   There are separate SDKs to use in the integration: one for mobile apps and one for TV apps.

   Mobile

   
     dependencies {
       implementation 'com.google.android.engage:engage-core:1.5.5
     }
   

   TV

   
     dependencies {
       implementation 'com.google.android.engage:engage-tv:1.0.2
     }
   

3. Set the Engage service environment to production in the AndroidManifest.xml file.

   Important: This should only be done before creating a release build. For your local testing with verification app, remove this.

   Mobile

   
   <meta-data
       android:name="com.google.android.engage.service.ENV"
       android:value="PRODUCTION" />
   

   TV

   
   <meta-data
       android:name="com.google.android.engage.service.ENV"
       android:value="PRODUCTION" />
   

4. Add permission for WRITE_EPG_DATA for tv apk

   <uses-permission android:name="com.android.providers.tv.permission.WRITE_EPG_DATA" />
   

5. Verify reliable content publishing by using a background service, such as androidx.work, for scheduling.

6. To provide a seamless viewing experience, publish continue watching data when these events occur:

   1. First Login: When a user logs in for the first time, publish data to make sure their viewing history is immediately available.
   2. Profile Creation or Switching (Multi-Profile Apps): If your app supports multiple profiles, publish data when a user creates or switches profiles.
   3. Video Playback Interruption: To help users pick up where they left off, publish data when they pause or stop a video, or when the app exits during playback.
   4. Continue Watching Tray Updates (If Supported): When a user removes an item from their Continue Watching tray, reflect that change by publishing updated data.
   5. Video Completion:
      1. For movies, remove the completed movie from the Continue Watching tray. If the movie is part of a series, add the next movie to keep the user engaged.
      2. For episodes, remove the completed episode and add the next episode in the series, if available, to encourage continued viewing.

Integration

Note: The Continue Watching API works differently from the Watch Next API. Instead of adding or removing items one by one, it replaces the entire list of "continue watching" items each time it updates. This means you need to send all the items you want to show every time you update. Also, the new API combines the steps for publishing the list and the items into one, making it simpler. Keep in mind that Google TV might not show all the items you send, as it combines lists from different apps.

AccountProfile

To allow a personalized "continue watching" experience on Google TV, provide account and profile information. Use the AccountProfile to provide:

1. Account ID: A unique identifier that represents the user's account within your application. This can be the actual account ID or an appropriately obfuscated version.

2. Profile ID (optional): If your application supports multiple profiles within a single account, provide a unique identifier for the specific user profile (again, real or obfuscated).

Note: If you choose to obfuscate the account ID or profile ID, use the same obfuscation logic consistently.

// If your app only supports account
val accountProfile = AccountProfile.Builder()
    .setAccountId("your_users_account_id")
    .build()

// If your app supports both account and profile
val accountProfile = AccountProfile.Builder()
    .setAccountId("your_users_account_id")
    .setProfileId("your_users_profile_id")
    .build()

Create entities

The SDK has defined different entities to represent each item type. Continuation cluster supports following entities:

1. MovieEntity
2. TvEpisodeEntity
3. LiveStreamingVideoEntity
4. VideoClipEntity

Note: TvShowEntity and TvSeasonEntity are not supported for the Continuation cluster for continue watching. When a user finishes one TV Episode, the next TvEpisodeEntity should be published for the user to continue watching the next episode.

Specify the platform-specific URIs and poster images for these entities.

Also, create playback URIs for each platform—such as Android TV, Android, or iOS—if you haven't already. So when a user continues watching on each platform, the app uses a targeted playback URI to play the video content.

Note: In the rare case when the playback URIs are identical for all platforms, you will still have to repeat it for every platform that you want to continue watching to happen.

// Required. Set this when you want continue watching entities to show up on
// Google TV
val playbackUriTv = PlatformSpecificUri.Builder()
    .setPlatformType(PlatformType.TYPE_ANDROID_TV)
    .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_tv"))
    .build()

// Required. Set this when you want continue watching entities to show up on
// Google TV Android app, Entertainment Space, Playstore Widget
val playbackUriAndroid = PlatformSpecificUri.Builder()
    .setPlatformType(PlatformType.TYPE_ANDROID_MOBILE)
    .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_android"))
    .build()

// Optional. Set this when you want continue watching entities to show up on
// Google TV iOS app
val playbackUriIos = PlatformSpecificUri.Builder()
    .setPlatformType(PlatformType.TYPE_IOS)
    .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_ios"))
    .build()

val platformSpecificPlaybackUris =
    Arrays.asList(playbackUriTv, playbackUriAndroid, playbackUriIos)

Poster images require a URI and pixel dimensions (height and width). Target different form factors by providing multiple poster images, but verify that all images maintain a 16:9 aspect ratio and a minimum height of 200 pixels for correct display of the "Continue Watching" entity, especially within Google's Entertainment Space. Images with a height less than 200 pixels may not be shown.

val images = Arrays.asList(
    Image.Builder()
        .setImageUri(Uri.parse("http://www.example.com/entity_image1.png"))
        .setImageHeightInPixel(300)
        .setImageWidthInPixel(169)
        .build(),
    Image.Builder()
        .setImageUri(Uri.parse("http://www.example.com/entity_image2.png"))
        .setImageHeightInPixel(640)
        .setImageWidthInPixel(360)
        .build()
    // Consider adding other images for different form factors
)

MovieEntity

This example show how to create a MovieEntity with all the required fields:

val movieEntity = MovieEntity.Builder()
   .setWatchNextType(WatchNextType.TYPE_CONTINUE)
   .setName("Movie name")
   .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
   .addPosterImages(images)
   // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
   .setLastEngagementTimeMillis(1701388800000)
   // Suppose the duration is 2 hours, it is 72000000 in milliseconds
   .setDurationMills(72000000)
   // Suppose last playback offset is 1 hour, 36000000 in milliseconds
   .setLastPlayBackPositionTimeMillis(36000000)
   .build()

Providing details like genres and content ratings gives Google TV the power to showcase your content in more dynamic ways and connect it with the right viewers.

val genres = Arrays.asList("Action", "Science fiction")
val rating1 = RatingSystem.Builder().setAgencyName("MPAA").setRating("PG-13").build()
val contentRatings = Arrays.asList(rating1)
val movieEntity = MovieEntity.Builder()
    ...
    .addGenres(genres)
    .addContentRatings(contentRatings)
    .build()

Entities automatically remain available for 60 days unless you specify a shorter expiration time. Only set a custom expiration if you need the entity to be removed before this default period.

// Set the expiration time to be now plus 30 days in milliseconds
val expirationTime = DisplayTimeWindow.Builder()
    .setEndTimestampMillis(now().toMillis()[phone]).build()
val movieEntity = MovieEntity.Builder()
    ...
    .addAvailabilityTimeWindow(expirationTime)
    .build()

TvEpisodeEntity

This example show how to create a TvEpisodeEntity with all the required fields:

val tvEpisodeEntity = TvEpisodeEntity.Builder()
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Episode name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(72000000) // 2 hours in milliseconds
    // 45 minutes and 15 seconds in milliseconds is 2715000
    .setLastPlayBackPositionTimeMillis(2715000)
    .setEpisodeNumber("2")
    .setSeasonNumber("1")
    .setShowTitle("Title of the show")
    .build()

Episode number string (such as "2"), and season number string (such as "1") will be expanded to the proper form before being displayed on the continue watching card. Note that they should be a numeric string, don't put "e2", or "episode 2", or "s1" or "season 1".

If a particular TV show has a single season, set season number as 1.

To maximize the chances of viewers finding your content on Google TV, consider providing additional data such as genres, content ratings, and availability time windows, as these details can enhance displays and filtering options.

val genres = Arrays.asList("Action", "Science fiction")
val rating1 = RatingSystem.Builder().setAgencyName("MPAA").setRating("PG-13").build()
val contentRatings = Arrays.asList(rating1)
val tvEpisodeEntity = TvEpisodeEntity.Builder()
    ...
    .addGenres(genres)
    .addContentRatings(contentRatings)
    .setSeasonTitle("Season Title")
    .setShowTitle("Show Title")
    .build()

VideoClipEntity

Here's an example of creating a VideoClipEntity with all the required fields.

VideoClipEntity represents a user generated clip like a Youtube video.

val videoClipEntity = VideoClipEntity.Builder()
    .setPlaybackUri(Uri.parse("https://www.example.com/uri_for_current_platform")
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Video clip name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(600000) //10 minutes in milliseconds
    .setLastPlayBackPositionTimeMillis(300000) //5 minutes in milliseconds
    .addContentRating(contentRating)
    .build()

You can optionally set the creator, creator image, created time in milliseconds, or availability time window .

LiveStreamingVideoEntity

Here's an example of creating an LiveStreamingVideoEntity with all the required fields.

val liveStreamingVideoEntity = LiveStreamingVideoEntity.Builder()
    .setPlaybackUri(Uri.parse("https://www.example.com/uri_for_current_platform")
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Live streaming name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(72000000) //2 hours in milliseconds
    .setLastPlayBackPositionTimeMillis(36000000) //1 hour in milliseconds
    .addContentRating(contentRating)
    .build()

Optionally, you can set the start time, broadcaster, broadcaster icon, or availability time window for the live streaming entity.

For detailed information on attributes and requirements, see the API reference.

Provide Continuation cluster data

AppEngagePublishClient is responsible for publishing the Continuation cluster. You use the publishContinuationCluster() method to publish a ContinuationCluster object.

First, you should use isServiceAvailable() to check if the service is available for integration.

client.publishContinuationCluster(
    PublishContinuationClusterRequest
        .Builder()
        .setContinuationCluster(
            ContinuationCluster.Builder()
                .setAccountProfile(accountProfile)
                .addEntity(movieEntity1)
                .addEntity(movieEntity2)
                .addEntity(tvEpisodeEntity1)
                .addEntity(tvEpisodeEntity2)
                .setSyncAcrossDevices(true)
                .build()
        )
        .build()
)

When the service receives the request, the following actions take place within one transaction:

• Existing ContinuationCluster data from the developer partner is removed.
• Data from the request is parsed and stored in the updated ContinuationCluster.

In case of an error, the entire request is rejected and the existing state is maintained.

The publish APIs are upsert APIs; it replaces the existing content. If you need to update a specific entity in the ContinuationCluster, you will need to publish all entities again.

ContinuationCluster data should only be provided for adult accounts. Publish only when the AccountProfile belongs to an adult.

Warning: Don't call delete and publish APIs subsequently to replace the content as the publish APIs do that inherently.

Cross-device syncing

SyncAcrossDevices flag controls whether a user's ContinuationCluster data is synchronized across devices such as TV, phone, tablets, etc. Cross-device syncing is disabled by default.

Values:

• true: ContinuationCluster data is shared across all the user's devices for a seamless viewing experience. We strongly recommend this option for the best cross-device experience.
• false: ContinuationCluster data is restricted to the current device.

Obtain Consent:

The media application must provide a clear setting to enable/disable cross-device syncing. Explain the benefits to the user and store the user's preference once and apply it in publishContinuationCluster accordingly.

// Example to allow cross device syncing.
client.publishContinuationCluster(
    PublishContinuationClusterRequest
        .Builder()
        .setContinuationCluster(
            ContinuationCluster.Builder()
                .setAccountProfile(accountProfile)
                .setSyncAcrossDevices(true)
                .build()
        )
        .build()
)

To get the most out of our cross-device feature, verify that the app obtains user consent and enable SyncAcrossDevices to true. This allows content to seamlessly sync across devices, leading to a better user experience and increased engagement. For example, a partner who implemented this saw a 40% increase in "continue watching" clicks because their content was surfaced on multiple devices.

Delete the Video discovery data

To manually delete a user's data from the Google TV server before the standard 60-day retention period, use the client.deleteClusters() method. Upon receiving the request, the service will delete all existing video discovery data for the account profile, or for the entire account.

Important: It is important to set syncAcrossDevices flag to true even in the delete requests so that the data is deleted from the server (even when the delete reason is USER_LOGOUT).

The DeleteReason enum defines the reason for data deletion. The following code removes continue watching data on logout.

// If the user logs out from your media app, you must make the following call
// to remove continue watching data from the current google TV device,
// otherwise, the continue watching data will persist on the current
// google TV device until 60 days later.
client.deleteClusters(
    DeleteClustersRequest.Builder()
        .setAccountProfile(AccountProfile())
        .setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT)
        .setSyncAcrossDevices(true)
        .build()
)

Warning: Don't call delete and publish APIs subsequently to replace the content as the publish APIs do that inherently.

Testing

Use the verification app to verify that Engage SDK integration is working correctly. This Android application provides tools to help you verify your data and confirm that broadcast intents are being handled properly.

Note: Check if your app is correctly calling isServiceAvailable and publishClusters APIs in logcat. Before submitting the APK, check if you are able to see publishClusters() is called logs in your logcat during development to verify that you are calling the APIs at the correct events.

After you invoke the publish API, confirm that your data is being correctly published by checking the verification app. Your continuation cluster should be displayed as a distinct row within the app's interface.

• Set Engage Service Flag only for non-production builds in your app's Android Manifest file.
• Install and open the Engage Verify app
• If isServiceAvailable is false, click the "Toggle" button to enable.
• Enter your app's package name to automatically view published data once you begin publishing.
• Test these actions in your app:
  • Sign in.
  • Switch between profiles(if applicable).
  • Start, then pause a video, or return to the home page.
  • Close the app during video playback.
  • Remove an item from the "Continue Watching" row (if supported).
• After each action, confirm that your app invoked the publishContinuationClusters API and that the data is correctly displayed in the verification app.

• The verification app will show a green "All Good" check for correctly implemented entities.

  

  Figure 1. Verification App Success

• The verification app will flag any problematic entities.

  

  Figure 2. Verification App Error

• To troubleshoot entities with errors, use your TV remote to select and click the entity in the verification app. The specific problems will be displayed and highlighted in red for your review (see example below).

  

  Figure 3. Verification App Error Details

REST API

Engage SDK offers a REST API to provide a consistent continue watching experience across non-Android platforms such as iOS, Roku TV. The API allows developers to update the "Continue-Watching" status for opted-in users from non-Android platforms.

Prerequisites

• You must first finish the on-device Engage SDK-based integration. This critical step establishes the necessary association between Google's user ID and your app's AccountProfile.
• API Access and Authentication: To view and enable the API in your Google Cloud Project, you must go through an allowlist process. All API requests require authentication.

Gaining Access

In order to gain access to view and enable the API in your Google Cloud Console, your account need to be enrolled.

1. Google Workspace Customer Id should be available. If not available you may need to set up a Google Workspace as well as any Google account(s) you want to use to call the API.
2. Setup an account with Google Cloud Console using an email associated with the Google Workspace.
3. Create a new project
4. Create a service account for API Authentication. Once you create the service account, you will have two items:
   • A service account ID.
   • A JSON file with your service account key. Keep this file secure, you'll need it to authenticate your client to the API later.
5. Workspace and associated Google Accounts can now be able to use REST APIs. Once the change has propagated you will be notified whether the API is ready to be called by your service accounts.
6. Follow these steps to preparing to make a delegated API call.

Publish Continuation Cluster

To publish the Video Discovery Data, perform a POST request to the publishContinuationCluster API using the following syntax.

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/profiles/{profile_id}/publishContinuationCluster

Where:

• package_name: The media provider package name
• accountId: The unique ID for the user's account in your system. It must match the accountId used in the on-device path.
• profileId: The unique ID for the user's profile within the account in your system. It must match the profileId used in the on-device path.

The URL for the account without profile is:

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/publishContinuationCluster

The payload to the request is represented in the entities field. entities represents a list of content entities which can be either MovieEntity or TVEpisodeEntity. This is a required field.

Request Body

Field	Type	Required	Description
entities	List of MediaEntity Objects	Yes	List of content entities (max 5), only the top five will be retained and the rest dropped.Empty list is allowed to signify the user has finished watching all entities.

Field entities contains individual movieEntity and tvEpisodeEntity.

Field	Type	Required	Description
movieEntity	MovieEntity	Yes	An object representing a movie within the ContinuationCluster.
tvEpisodeEntity	TvEpisodeEntity	Yes	An object representing a tv episode within the ContinuationCluster.

Each object in the entities array must be one of the available MediaEntity types namely MovieEntity and TvEpisodeEntity,along with common and type-specific fields.

Following code snippet showcase the request body payload for the publishContinuationCluster API.

{
  "entities": [
    {
      "movieEntity": {
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "name": "Movie1",
        "platform_specific_playback_uris": [
          "https://www.example.com/entity_uri_for_android",
          "https://www.example.com/entity_uri_for_iOS"
        ],
        "poster_images": [
          "http://www.example.com/movie1_img1.png",
          "http://www.example.com/movie1_imag2.png"
        ],
        "last_engagement_time_millis": 864600000,
        "duration_millis": 5400000,
        "last_play_back_position_time_millis": 3241111
      }
    },
    {
      "tvEpisodeEntity": {
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "name": "TV SERIES EPISODE 1",
        "platform_specific_playback_uris": [
          "https://www.example.com/entity_uri_for_android",
          "https://www.example.com/entity_uri_for_iOS"
        ],
        "poster_images": [
          "http://www.example.com/episode1_img1.png",
          "http://www.example.com/episode1_imag2.png"
        ],
        "last_engagement_time_millis": 864600000,
        "duration_millis": 1800000,
        "last_play_back_position_time_millis": 2141231,
        "episode_display_number": "1",
        "season_number": "1",
        "show_title": "title"
      }
    }
  ]
}

Delete the video discovery data

Use the clearClusters API to remove the video discovery data.

Use POST URL to remove the entities from video discovery data. To delete the continuation cluster data, perform a POST request to the clearClusters API using the following syntax.

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/profiles/{profile_id}/clearClusters

Where:

• package_name: The media provider package name.
• accountId: The unique ID for the user's account in your system. It must match the accountId used in the on-device path.
• profileId: The unique ID for the user's profile within the account in your system. It must match the profileId used in the on-device path.

The payload for the clearClusters API contains only one field, reason, which contains a DeleteReason that specifies the reason for removing data.

{
  "reason": "DELETE_REASON_LOSS_OF_CONSENT"
}

Testing

After successfully posting data, use a user test account to verify that the expected content appears in the "Continue Watching" row on target Google surfaces such as Google TV and the Android and iOS Google TV mobile apps.

In testing, allow a reasonable propagation delay of few minutes and adhere to the watch requirements, such as watching part of a movie or finishing an episode. Consult the Watch Next guidelines for app developers for details.