Engage SDK for TV integration guide

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.

    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

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).

// 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

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.

// 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()+2592000000).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.

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.

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.

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()
)

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.

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.

    Verification App Success Screenshot
    Figure 1. Verification App Success

  • The verification app will flag any problematic entities.

    Verification App Error Screenshot
    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).

    Verification App error details
    Figure 3. Verification App Error Details

Integration for non-Android platforms

Continue watching offers to integrate content from the non-Android platforms such as iOS, Roku TV. These REST API allow the developers to update the continue watching data from non-Android platforms allowing to provide seamless continue watching experience across devices.

Prerequisite

  1. Integrate Engage-SDK to device.
  2. Enable API in Google cloud project.

To view and access APIs in your Google Cloud project follow these steps.

  1. Set up Google workspace if not available already.
  2. Set up Google cloud console if not available already.
  3. Create a new project in Google cloud console.
  4. Create a service account for API authentication.
  5. Use your service account credential to make a Delegate API call.

Publish continuation cluster

Use the publishContinuationCluster API to publish your "continue watching" data to Google TV.

URL

Use POST URL to publish. Use the following syntax:

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

Where:

  • package_name is the package name for your app.
  • account_id is a unique Account ID.
  • profile_id is the unique profile ID to distinguish between different profiles for same account.
Request body

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.

Following code snippet showcase the example for the publishContinuationCluster API.

{
  "entities": [
  {
    "movieEntity": {
    "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
    "name": "Movie1", //data type = string
    "platform_specific_playback_uris": [],
    "poster_images": [],
    "last_engagement_time_millis": 864600000, //data type = long,
    "duration_millis": 5400000, //90 mins data type = long,
    "last_play_back_position_time_millis": 3241111 //data type = long,
    }
  },
  {
    "tvEpisodeEntity": {
      "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
      "name": "TV SERIES EPISODE 1", //data type = string
      "platform_specific_playback_uris": [],
      "poster_images": [],
      "last_engagement_time_millis": 864600000, // data type =long,
      "duration_millis": 1800000,// data type = long,
      "last_play_back_position_time_millis": 2141231, // data type =long,
      "episode_display_number": "1",// data type string,
      "season_number": "1",// data type string,
      "show_title": ""// data type string,
    }
  },
  ],
}

Delete Video discovery data

Use the clearClusters API to remove the video discovery data. Use the clearClusters API to remove the video discovery data.

URL

use POST URL to remove the entities from video discovery data.

https://tvvideodiscovery.googleapis.com/v1/packages/app_pkg_name/accounts/accountID1/profiles/profileID1/clearClusters

Where:

  • package_name is package name for your app.
  • account_id is unique Account ID
  • profile_id is the unique profile Id to distinguish between different profiles for same account.
Request body

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" // data type = string
}

Google surfaces will show the updated content.