Watch Activity

Watch activity 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, and more.

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
  • Event type details
• When to send
• How to send
• Customer experience validation
• Troubleshooting
  • None of my content is appearing in the Continue Watching Row
  • Some content is missing, appearing in the wrong order, or removed incorrectly

What to send

For each trigger (see when to send), send a single event with the following fields. There is no need to filter the data you send or check for duplicates. Amazon does this as necessary.

Event type details

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

Active events occur actively 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 which occurred 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 on a regular basis. 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 Playback state change (start, stop, pause, or exit).
• On seek to a new playback position.
• Once every 60 seconds while in the player, regardless of playback state.
• For 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 will include a parameter indicating the time window for which you should share data. Instead of sending every playback event that occurred in that time window, you can just send the playback exit events, which will give us the content and its last viewed progress.
  • When in the foreground on a Fire TV device, your app should 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 Implement the data pull service for background or off-device data.

How to send

Use this sample code to send watch activity events.

• Java
• Kotlin

 AmazonPlaybackReceiver receiver = AmazonPlaybackReceiver.getInstance(context);
 AmazonPlaybackEvent playbackInfo = AmazonPlaybackEvent
     .builder()
     .playbackPositionMs(0)
     .creditsPositionMs(1000)
     .state(AmazonPlaybackState.PLAYING)
     .durationMs(2000)
     .contentId(AmazonContentId.builder()
         .id("string")
         .namespace(AmazonContentId.NAMESPACE_CDF_ID)
         .build())
     .profileId(AmazonProfileId.builder()
         .id("myProfileId1")
         .namespace(AmazonProfileId.NAMESPACE_APP_INTERNAL)
         .build())
     .buildActiveEvent();
 receiver.addPlaybackEvent(playbackInfo);

val receiver: AmazonPlaybackReceiver = AmazonPlaybackReceiver.getInstance(context)
val playbackInfo: AmazonPlaybackEvent = AmazonPlaybackEvent
    .builder()
    .playbackPositionMs(0)
    .creditsPositionMs(1000)
    .state(AmazonPlaybackState.PLAYING)
    .durationMs(2000)
    .contentId(
        AmazonContentId.builder()
            .id("string")
            .namespace(AmazonContentId.NAMESPACE_CDF_ID)
            .build()
    )
    .profileId(
        AmazonProfileId.builder()
            .id("myProfileId1")
            .namespace(AmazonProfileId.NAMESPACE_APP_INTERNAL)
            .build()
    )
    .buildActiveEvent()
receiver.addPlaybackEvent(playbackInfo)

Customer experience validation

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

Troubleshooting

Use this section to help you troubleshoot your watch activity integration.

None of my content is appearing in the Continue Watching Row

Refer to General Troubleshooting: No content appears in the Continue Watching Row.

Some content is missing, appearing in the wrong order, or removed incorrectly

The following are common issues that might affect your integration.

Incorrect Amazon content IDs

It's critical to confirm that the Amazon content IDs that you use in your SDK integration are exact matches to the IDs you use in your catalog. The SDK logs don't include the content ID. Therefore, during development, consider adding a debug log in your app that contains the ID. Use this log to validate whether you're sending the expected content ID. For details about catalog integration, see EMBER Catalog Integration Overview.

Reporting playback events incorrectly

Every playback event must accurately represent state. The construction of the Continue Watching Row relies on accurate data reported from your app. The following table describes behaviors to avoid.

Do Not	Do
Send a playback event with current position = 0 before the player is loaded with the user’s actual playback position	Send a playback event with the customer's correct position after the player is loaded
Advance the current playback position while an interstitial (ad, intro, preview, etc.) is playing	Send an interstitial playback event with the current playback position of the content
Not reporting updated playback position periodically while content is playing	Send a playback event every 60 seconds while content is playing
Send a PAUSE event when exiting content	Send an EXIT playback event when playback is completed

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

Off-Device Activity is not updating the Continue Watching Row

Fire TV services are currently not using off-device activity to influence the Continue Watching Row.

Content from multiple in-app profiles is appearing in my CWR

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.

Last updated: May 27, 2026