Watch Activity

Watch activity data consists of content playback events. This data is used to give customers an easy way back into the content they were previously watching in your app. In the future we may also use this data to populate recommendation carousels like Next Up For You.

Watch activity can occur locally on the Fire TV device or remotely on a different device. For watch activity occurring on the same device, send playback start, playback progress, pause/resume, and playback exit events. For remote watch activity, only send the end state (playback exit) events. These are needed to update the UI, such as showing the customer the next episode of a TV show they were watching, or removing content they have already watched.

What to send

For each trigger (see when to send), send events with the fields below. There’s no need to filter the data you send or check for duplicates. Amazon does this as needed.

Event type details

There are two types of playback events provided: addPlaybackEvent function: Active and Off-Device.

Active events occur on the same device in real-time. For example, when a customer plays a title in your app on their Fire TV. An event can be marked Active only if it takes place on the device at the current time. The timestamp field on the playback event is not used for Active events since the system captures the timestamp at the moment the event is reported.

Off-Device events are for playback occurring on another device at another time. This is primarily used to capture the latest customer watch progress so the Fire TV UI reflects customer up-to-date engagement data across devices. The Fire TV's on-device service requests this type of data at regular intervals. A timestamp is required for this type of event.

If you send playback events outside of active playback, even on the same Fire TV device, mark them as Off-Device and provide an accurate timestamp for when they occurred. Do not filter out non-active events on the same device. Amazon will de-duplicate Active events.

When to send

When these triggers occur, send the event info:

• On a Playback state change: start, stop, pause, or exit.
• On seeking to a new playback position.
• Once every 60 seconds while in the player, regardless of playback state.
• For an activity taking place on other types of devices:
  • Fire TV’s on-device service will periodically wake up and ask your app to sync this data. This includes a parameter indicating the time window for which you should share data. Instead of sending every playback event that occurred in that time window, send the playback exit events, which gives us the content and its last viewed progress.
  • When in the foreground on a Fire TV device. Have your app sync this data from your service and send us the latest viewing progress.
  Note: For more information on how to handle Amazon requesting off-device data from your app, see Step 6. Implement your data pull service for background or off-device data.

How to send

Use this sample code to send watch activity events as the user is interacting with your app:

// Example playback event generated when user starts watching Live content

const playbackEvent: IPlaybackEvent = new PlaybackEventBuilder()
   .playbackPositionMs(0)
   .playbackState(PlaybackState.PLAYING)
   .durationMs(2000)
   .eventTimestamp(new Date())
   .contentId(
   new ContentIdBuilder()
      .id('content_CDF_ID')
      .idNamespace(ContentIdNamespaces.NAMESPACE_CDF_ID)
      .build(),
   )
   .channelDescriptor(new ChannelDescriptorBuilder()
      .majorNumber(0)
      .minorNumber(1)
      .identifier('channelID')
      .build(),
   )
   .profileId(
   new ProfileIdBuilder()
      .id('myProfileId')
      .idNamespace(ProfileIdNamespaces.NAMESPACE_APP_INTERNAL)
      .build(),
   )
   .buildActiveEvent();

// Send the event
ContentPersonalizationServer.reportNewPlaybackEvent(playbackEvent);

Use this sample TypeScript code to send off-device watch activity data when your app is invoked through the Content Personalization data service:

const playbackEventsHandler: IPlaybackEventsHandler = {
    getPlaybackEventsSince: (
      sinceTimestamp: Date,
      playbackEventsProvider: IPlaybackEventsProvider,
    ) => {
        let playbackEvents: IPlaybackEvent[] = [];
        
        const playbackEvent: IPlaybackEvent = new PlaybackEventBuilder()
            .playbackPositionMs(0)
            .creditsPositionMs(1000)
            .playbackState(PlaybackState.EXIT)
            .durationMs(2000)
            .eventTimestamp(new Date())
            .contentId(new ContentIdBuilder()
                .id('content_CDF_ID')
                .idNamespace(ContentIdNamespaces.NAMESPACE_CDF_ID)
                .build(),
             )
            .profileId(new ProfileIdBuilder()
                .id('myProfileId')
                .idNamespace(ProfileIdNamespaces.NAMESPACE_APP_INTERNAL)
                .build(),
            )
            .buildOffDeviceEvent();
            
        playbackEvents.add(playbackEvent);
        
        playbackEventsProvider.addPlaybackEventChunk(playbackEvents);
        playbackEventsProvider.commit();
    }
};

// Remeber to set your playback events handler in the onStart function of your HeadlessService
ContentPersonalizationServer.setPlaybackEventsHandler(
        playbackEventsHandler,
);

Customer experience validation

After implementing the SDK calls for each of the items under When to Send, perform the following actions and validate the outcomes.

Set up your device

1. Set up and register your Fire TV device.
2. The app content should be catalog integrated with Fire TV.
3. Install your Vega content personalization enabled app onto the device and launch the app.
4. You must consent to the continued watching feature for this account. To do this, follow these instructions:
   1. Go to Settings > Preferences > Privacy Settings > Manage Sharing from Apps > Share App Viewing and Content Info > Turn On
   2. Go to Settings > Preferences > Privacy Settings > Manage Sharing from Apps > Sync Across Devices > Turn On

Verify content updates in the Continue Watching row

Your app must periodically report watch activity events during video playback. Once the user begins watching content, the system will add it to the Continue Watching row.

1. In your app, open a video and play it. Watch or scroll over at least 2% of the video.
2. Stop playing the video by clicking the stop or back button.
3. Check the logs to verify the playback event was successfully reported. If it’s reported successfully, you’ll see the following log line.

   INFO com.amazon.com_amazon_tv_developer_dataservice.vega.vega_alberto_service:VegaAlbertoBinderService PlaybackEventsVegaMessage → message.sent_timestamp: <your_time_stamp>, page_index : 0, total_page_count: 1, content_id id : <your_content_id>, content_id namespace : cdf_id, event_timestamp_ms: <your_time_stamp>, playback_state :0, duration_ms : <your_content_duration>, credits_position_ms :<your_content_credit_position>
   

4. Return to the home screen using the remote, by exiting the app, or clicking the home button.
5. You should see the updated Continue Watching row. The video you watched should be showing. If it is, it’s working correctly.
6. In case the Continue Watching row is not updated, navigate away from the Home tab to any other tab and return to the Home tab again.
7. You can also remove tiles from the Continue Watching row by doing the following:
   1. Hover over the tile > click the menu button on the remote > select Remove from Continue Watching. You can test with the same content this way.

Verify content is removed from the Continue Watching row

During video playback, your app must report watch activity events periodically, as well as when playback is completed or interrupted. If the current play position is close to the total duration, it indicates the user has completed watching the video, and the system removes the content from the Continue Watching row.

1. Open your app and start watching a video with content already listed in the Continue Watching row.
2. Go to the end of the video by seeking to the end of the video or clicking the forward (») scroll button on the remote repeatedly.
3. Check the logs to verify that a playback stopped event was successfully reported. If successfully reported, your logs will be similar to what’s below.

   INFO com.amazon.com_amazon_tv_developer_dataservice.vega.vega_alberto_service:VegaAlbertoBinderService PlaybackEventsVegaMessage → message.sent_timestamp:  <your_time_stamp> , page_index : 0, total_page_count: 1, content_id id : <your_content_id>, content_id namespace : cdf_id, event_timestamp_ms: <your_time_stamp>, playback_state :2, duration_ms : <your_content_duration>, credits_position_ms : <your_content_credit_position>
   

4. Return to the Home tab.
5. The Continue Watching row should no longer display the content.
6. If the Continue Watching row doesn't update, navigate away from the Home tab to any other tab, then return to the Home tab to trigger a UI refresh.

Validation scenarios

Follow the relevant steps below for adding or removing tiles from the Continue Watching row. Validate each scenario.

Troubleshooting

Here are some common issues you may encounter in your integration:

Incorrect CDF IDs

The Catalog Data Format (CDF) IDs used in the SDK must be exact matches to the IDs used in your catalog ingestion. The logs will not include any CDF IDs, so we recommend adding a debug log to your app containing this ID during development to validate you are sending the expected CDF ID. See Getting Started with Catalog Ingestion.

Reporting playback events incorrectly

Every playback event must accurately represent the state. The construction of the Continue Watching row relies on accurate data reported from your app. Here are some behaviors to avoid, and some you should do:

Review When to Send for more details on when to send events.

Off-Device activity is not updating the Continue Watching row

This is expected behavior. Fire TV services do not use off-device activity to influence the Continue Watching row.

Content from multiple in-app profiles is appearing in your Continue Watching row

The Continue Watching row is based on playback events recorded from the current active Fire TV profile. If a user changes profiles in your app but continues to use the same Fire TV profile, then those events will also be included in that profile. This is expected behavior.

• Previous – Get Started with Vega Content Personalization
• Next – Individual Content Entitlements

Last updated: Sep 30, 2025