Step 4: Implement EPG Sync Task

Electronic Programming Guide (EPG) sync task design guidelines

1. Review Vega Headless Tasks and Services before implementing your EPG sync task.
2. Use a Cloud Catalog to make your tasks lightweight.
3. Leverage the getLastCommittedLineupVersion function to perform a light-weight version check to skip over ingestion if the system already has the latest lineup. The commit version is an opaque string that you can set using whatever algorithm works best for you. It can be a hash of the lineup, a timestamp, or some other versioning strategy.
4. Limit the memory usage of your task to avoid exceeding the system thresholds or termination:
   1. Only download the data you need for the API integration.
   2. Download data from your backend in chunks/pages using techniques like the HTTP 1.1 Range request header (RFC 7233, Section 3).
   3. Do not use an XML data schema for your EPG data. JSON schemas are easier and more memory efficient to parse in JS.
5. If EPG Sync task fails with Promise.reject(error) for any reason, the system will automatically retry up to 8 times with an exponential backoff.

Vega EPG Provider API Guidelines

1. For optimal performance and access to the newest features, use the latest interface versions. Interfaces are versioned using a suffix at the end of the name. For instance, ProgramLineupProvider2 is the recommended upgrade for ProgramLineupProvider. All references to interfaces or APIs assumes you are using the latest version.
2. The ChannelLineupProvider interface expects the entire channel lineup. It’s a complete set/replacement of the current list.
3. The LiveEventProvider interface expects the entire live event lineup. It’s a complete set or replacement of the current list.
4. The ChannelLineupProvider, ProgramLineupProvider, and LiveEventProvider interfaces are transactional.
   1. The commit API must be called at the end to complete the transaction. After calling commit(), the object cannot be reused. A new object must be created if necessary.
   2. Destroying the ChannelLineupProvider, ProgramLineupProvider, and LiveEventProvider objects without calling a commit aborts the transaction.
   3. Commit a new channel lineup (if needed) prior to updating programs/using ProgramLineupProvider. Channel and programs updates cannot be interleaved.
   4. The ProgramLineupProvider.upsert() operation will fail if the channel corresponding to the program’s ChannelDescriptor has not been committed.
5. The Lineup Provider functions must be called on the same thread (they are not thread safe).
6. The ChannelMetadata.name field indicates the marketing name for the channel that will be presented in the FireTV carousel. Channel ingestion will fail if this is field is not provided or an empty string is provided. Fire TV displays up to 25 alphanumeric characters, but won't display the full channel name if the length exceeds this limit. This max limit is applicable for both half-width and full-width character sets. Examples:
   1. The Walking Dead Universe (Max length-pass).
   2. Ed's Purple Plane (Max length-pass).
   3. How Sally Fell off her Horse and Learned to Play Piano on a Saturday (Max length-fail, since it's over 25 characters long).
   4. エドのパープルプレイン (Max length-pass).
7. If using ProgramLineupProvider, provide at least 48 hours worth of program data.
8. When a user upgrades or downgrades their subscription package, the number of entitled channels and live events changes accordingly. To accommodate these changes, make sure the channel, program, and live event ingestion APIs, ingestChannelLineup(), ingestProgramLineup(), and ingestLiveEvents() respectively, are called during any subscription modifications.
9. If using ProgramLineupProvider, you must provide at least 48 hour's worth of program data.
10. Channel logos specified through ChannelMetadata.logoUrl must be multi-tone images with the dimensions of 120x68 pixels.

Error handling

All errors during data ingestion should be caught and pushed to your backend. Create alarms to make sure errors are addressed as soon as possible.

1. ProgramLineupProvider and LiveEventProvider support partially successful commits and provides error feedback for programs and live events that failed to commit.
   1. The upsert for ProgramLineupProvider and add operations for LiveEventProvider return a list of IUpsertProgramFailure or IAddLiveEventFailure objects that failed to be added to the commit queue. An empty list is returned if all programs or live events are added to the commit queue successfully.
   2. Push the failed programs and live events to your backend and trigger alarms so invalid data issues can be addressed quickly before the next sync.
   3. On failures, abort the program or live event ingestion process in order to address failures and retry, or partially commit the successful programs or live events.
2. A StorageLimitError is thrown during the EPG sync task if attempting to write beyond the size limit for your provider’s allocated storage.
   1. Stop the ingestion, and trigger an alarm.
   2. Consult your Amazon contact if you run into this error.
3. An InvalidArgumentError is thrown if any of the provided channels are invalid when you call ChannelLineupProvider.add(). This error message includes the total number of failed insertions and the reasons for the first 5 failed channels.
   1. This error message is in the following format.

      Copy code Copied to clipboard.

      Found 1 invalid channels in provided data, list some examples: [{"channelIdentifier":"xxx","channelMajorNumber":xx,"channelMinorNumber":xx,"errorMessage": "xxx"}]
      

4. Every string field has a size limit. If a field exceeds the limit, then the string will either be truncated and “…” will be appended at the end of the string or an InvalidArgumentError will be thrown. The details for each field is in the inline documentation of the EPG Provider interfaces.
5. If the EPG Sync task fails with Promise.reject(error) for any reason, the system will automatically retry up to 8 times with an exponential backoff.

Cloud catalog vs. on-device ingestion

As mentioned in the Prerequisites, we recommend you integrate your catalog with a cloud service such as Amazon Catalog Service or Gracenote. Leveraging the CDF or Gracenote integration model has several benefits:

• It eliminates the need for program lineup ingestion, which can be quite large and difficult to parse.
• It eliminates the need to provide any Channel Metadata other than ChannelType during channel ingestion. The rest is obtained automatically through the cloud service.
• Better scalability as your customer base grows.

CDF is the most direct integration, which will cut latency and allow future features to be enabled more quickly. Keep in mind that the choice of using a cloud-based catalog vs. on-device program lineup ingestion must be made for each individual channel. This means you can have one channel that uses Gracenote ID, another that uses CDF, and a third that uses on-device program lineup ingestion.

Below is a feature-level comparison between CDF, Gracenote, and on-device program ingestion on the 1P features that are supported on Fire TV.

Features	CDF	Gracenote	On-Device Program Ingestion
Browse Dedicated Carousel
Live Provider Row	✓	✓	✓
App Peak	✓	✓	✓
Browse Mixed Carousel
Recent	✓	✓	✓
Home On Now	✓	✓	✓
Genre Row	✓	✓	✓
Browse
Electronic Program Guide	✓	✓	✓
Search
Channel	✓	✓	✓
Program	✓	✓
Voice
Tune by Channel Name	✓	✓	✓
Tune by Program Name (New/Live only)	✓	✓
Schedule Refresh Method
Automatic via Catalog lookup	✓	✓
On-device			✓

Providing a CDF station ID (preferred)

If you provide a CDF Station ID, the information will sync to the cloud daily through the Live TV app. The CDF Station ID is used when looking up a channel in the Fire TV catalog, which contains up to 14 days of programming information. This information will appear in the ‘Home’ and ‘Live’ tabs, as well as in the Channel Guide. It will automatically refresh to stay current, and is discoverable through Search, and voice with Alexa.

Refer to the External ID section of the Data Type Reference page for the corresponding values to use for this data source.

Providing a Gracenote ID

If you provide a Gracenote channel ID (either onTV or GVD (Global Video Data)), the information will sync to the cloud on a daily basis through the Live TV app. If the Gracenote ID is found, it is used when looking up a channel in the Fire TV catalog, which contains up to 14 days of programming information. This information will appear in the ‘Home’ and ‘Live’ tabs, as well as in the Channel Guide. It will automatically refresh to stay current, and will be discoverable through Search and voice with Alexa.

Refer to the External ID section of the Data Type Reference page for the corresponding values to use for this data source.

On-device program ingestion

If you do not provide a CDF Station ID or a Gracenote channel ID for your channels, insert the following:

• All Channel metadata
• Your logo URLs
• All upcoming programming information regularly across all of your channels using the Program Lineup Provider

The Vega Sample App provides an example for how to do this.

Metadata values

Refer to the Data Type Reference page for supported values for various metadata fields for channels, programs, and live events.

Channel and Live Event ordering

Channel ordering

Channel ordering determines the rank of channels displayed on the Fire TV Device UI. The provider determines the baseline order. However, customers can favorite channels using the context menu or channel manager. These channels will have the highest display priority. Therefore, the priority is: favorites > channel ordering option.

Fire TV offers the following types of channel ordering:

1. Alphabetical: Channels in the Fire TV UI are displayed in the order based on the name field in ascending order. This is the default ordering.
2. Custom channel ordering: Channels in the Fire TV UI are displayed in the order of the SortRank field value of the channel metadata provided during channel ingestion. If a SortRank is not provided then the channel will be placed at the bottom of the ordering. Tiebreakers will be ordered alphabetically by the channel’s name. If you prefer this ordering method, notify your Amazon contact.
3. Channel num ordering: Channels in the Fire TV UI are displayed in ascending order according to the provided channel descriptor major and minor numbers. The channels are sorted by major number first, and then minor number. For example, channel 3.1 is displayed before Channel 3.10. Tiebreakers will be ordered alphabetically by the channel’s name. If you prefer this ordering method, notify your Amazon contact.

For a consistent experience, choose a channel order that’s closest to the order found inside your app. Work with your Amazon contact to select a channel ordering method as part of your onboarding process.

Live Event Ordering

Live events in the Fire TV UI will be displayed in the order based on the SortRank field value of the LiveEvent metadata provided during live event ingestion. If a SortRank is not provided, the live event will be placed at the bottom of the ordering. Tiebreakers will be done alphabetically by the live event’s title. Place your most important content at the front for the most visibility.

Maximum rate of rollout

Perform a staged rollout of channels to your customers at a maximum rate of 500k / hour.

This value refers to the number of customer Fire TV devices with channel entitlement. Channel entitlement means one click to full-screen playback from the Fire TV Linear Integration UX.

Examples:

• App ABC offers Video on Demand, but has Live TV as a premium add-on. The rate would refer to ABC customers that have the Live add on only.
• App XYZ has a free baseline package of channels and a second paid tier that includes more channels. If the channel lineup of the paid tier is updated, this rate refers to those customers in that paid tier.

UX field list

Here are examples of how metadata fields are used in the Fire TV UX to help provide context when populating values.

UX Field	Description	Required for Certification (Y/N)	Associated Metadata Field
Program Name	Name of the program. This is the large text at the top left of the screen.	Y	Program.title
Time of Playback	Time it airs (Example: 11:00 PM – 12:00 AM). Found directly under the program name.	Y	Program.startTimeMs Program.endTimeMs
Episode Name	Name of the episode that is airing. This is in bold underneath the time of playback and badges.	Y	Program.subtitle
Episode Description	Description of the episode. It fills in the rest of the section after the episode name.	Y	Program.description
Season & Episode Information	Common in a series (such as a sitcom). This is the season and episode info provided for this airing. This is part of the mini-details after the episode name.	N	Program.seriesInfo.season Program.seriesInfo.episode
Rating	Local rating of the episode in badge form. In the same line as the time of playback.	N	Program.ratings
Various Attributes used for Badging	Refer to 'Attribute' section of the Data Type Reference page.	N	Program.attributes
Program Image	16:9 show / movie image that fills the carousel tile. The resolution should be 768x432 or higher.	Y	Program.thumbnailUrl
Background Image	16:9 show / movie image that fills the section of the top right corner next to the mini-details section. The resolution for this should be 1280x720 or higher.	Y	Program.posterArtUrl
Channel Name	Name of the channel displayed on the tile in the carousel. See EPG Ingestion Best Practices for guidance on display naming limitations.	Y	ChannelMetadata.name
Channel Logo	A 120x68 multi-tone image that is used in the EPG. If there is no channel logo, it will fall back to the channel name (in the marquee).	Y	ChannelMetadata.logoUrl Or reach out to your Amazon contact to provide the info if you are unable to provide the logo URL in ChannelMetadata.
Channel Genres	Genres can be attributed to a channel so the channel will show up in additional ingress points in the Fire TV UI.	N	ChannelMetadata.genres

• Previous – Step 3: Define Your Task
• Next – Step 5: Schedule EPG Sync Task

---

Last updated: Sep 30, 2025