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.

Step 1: Pre-work

Before you begin, complete the following steps:

Ensure your app targets API level 19 or higher for this integration

  1. 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
  }

  2. 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">
</meta-data>

    TV

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

  3. Add permission for WRITE_EPG_DATA for tv apk

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

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

  5. 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, publishing their data ensures 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. This ensures each user has a personalized experience.
    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. This ensures the tray remains relevant and personalized.
    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 ensure 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.


Image image1 = new Image.Builder()
            .setImageUri(Uri.parse("http://www.example.com/entity_image1.png");)
            .setImageHeightInPixel(300)
            .setImageWidthInPixel(169)
            .build()
Image image2 = new Image.Builder()
            .setImageUri(Uri.parse("http://www.example.com/entity_image2.png");)
            .setImageHeightInPixel(640)
            .setImageWidthInPixel(360)
            .build()
// And other images for different form factors.
val images = Arrays.asList(image1, image2)
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 = new 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

This flag controls whether a user's ContinuationCluster data is synchronized across their devices (TV, phone, tablet, etc.). It defaults to false, which means 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, ensure your 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(
  new DeleteClustersRequest.Builder()
        .setAccountProfile(AccountProfile())
        .setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT)
        .setSyncAcrossDevices(true)
        .build()
)

Testing

Use the verification app to ensure your 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.

  • Ensure that the Engage Service Flag is NOT set to production 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