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.
How to send
Use this sample code to send watch activity events as the user is interacting with your app: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
- Set up and register your Fire TV device.
- The app content should be catalog integrated with Fire TV.
- Install your Vega content personalization enabled app onto the device and launch the app.
-
You must consent to the continued watching feature for this account. To do this, follow these instructions:
- Go to Settings > Preferences > Privacy Settings > Manage Sharing from Apps > Share App Viewing and Content Info > Turn On
- 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.- In your app, open a video and play it. Watch or scroll over at least 2% of the video.
- Stop playing the video by clicking the stop or back button.
-
Check the logs to verify the playback event was successfully reported. If it’s reported successfully, you’ll see the following log line.
- Return to the home screen using the remote, by exiting the app, or clicking the home button.
- You should see the updated Continue Watching row. The video you watched should be showing. If it is, it’s working correctly.
- 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.
-
You can also remove tiles from the Continue Watching row by doing the following:
- 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.- Open your app and start watching a video with content already listed in the Continue Watching row.
- 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.
-
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.
- Return to the Home tab.
- The Continue Watching row should no longer display the content.
- 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 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 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.
