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
- None of my content is appearing in the Continue Watching Row
- Some content is missing, appearing in the wrong order, or removed incorrectly
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 below fields. There is no need to filter the data you send or check for duplicates. Amazon does this as necessary.

Field Name	Required (Y/N)	Description
Event Type	Y	The event can be either Active or Off-Device. See details.
Content ID	Y	ID of the content the customer is watching as specified through catalog integration.
Live Channel Station ID	Y*	ID of the live linear channel playing the content as specified through catalog integration. * Required for live content only.
Internal Profile ID	Y	Provide an obfuscated Profile ID so Fire TV can associate the activity with the correct app customer.
Duration	Y	Length of content in milliseconds.
Current Playback Position	Y	Offset from start of content in milliseconds, excluding interstitial content (previews, ads, etc.).
Credits Position	N	Position of the credits in the content. Offset from start of content in milliseconds, excluding interstitial content (previews, ads, etc.). This field will help Fire TV understand when a customer has finished watching the content.
Event Timestamp	N*	* This is required for Off-Device events, but not for Active events.
Playback State	Y	Enum with the following possible values: PLAYING, PAUSED, EXIT, or INTERSTITIAL.

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)

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

Here are some common pitfalls that may be causing issues in your integration:

Incorrect CDF IDs: It's critical to confirm that the Catalog Data Format (CDF) IDs used in the SDK are exact matches to the IDs used in your catalog ingestion. The SDK logs will not include the CDF ID so we recommend adding a debug log in your app containing the 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 state. The construction of the Continue Watching Row relies on accurate data reported from your application. Here are some behaviors to ensure you are avoiding:

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.

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.

Note: If you do not see content appear immediately in the Continue Watching Row you may need to wait up to 5 minutes for the row to refresh. You can force the row to refresh by going to Settings > Account & Profile Settings > Sync Amazon Content.

Validation Expecation	Validation Steps
Title is not yet added to the Continue Watching Row	1. Start playback of a movie title not in progress 2. Pause immediately 3. Navigate to the Fire TV Home page
Title appears as the first entry in the Continue Watching Row on home	1. Resume playback of the movie title 2. Fast Forward to at least 2% into the movie 3. Navigate to the Fire TV Home page
Title is removed from the Continue Watching Row	1. Start playback of a new TV episode 2. Pause immediately 3. Navigate to the Fire TV Home page
TV episode is not yet added to the Continue Watching Row	1. Start playback of a new TV episode 2. Pause immediately 3. Navigate to the Fire TV Home page
TV episode with the correct season and episode number is added as the first entry in the Continue Watching Row	1. Resume playback of the TV episode 2. Allow playback to continue until you are at least 2% into the title 3. Navigate to the Fire TV Home page
TV episode with the correct season and episode number remains as the first entry in the Continue Watching Row	1. Resume playback of a TV episode in progress 2. Immediately navigate to the Fire TV Home page
TV series with the subsequent episode appears in the Continue Watching Row	1. Resume playback of a TV episode in progress 2. Fast forward to the end of the episode 3. Navigate to the Fire TV Home page

Troubleshooting

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

Here are some common pitfalls that may be causing issues in your integration:

Incorrect CDF IDs: It's critical to confirm that the Catalog Data Format (CDF) IDs used in the SDK are exact matches to the IDs used in your catalog ingestion. The SDK logs will not include the CDF ID so we recommend adding a debug log in your app containing the 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 state. The construction of the Continue Watching Row relies on accurate data reported from your application. Here are some behaviors to ensure you are avoiding:

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.

Now let's learn about another data type: Individual Content Entitlements.

Last updated: Mar 01, 2024