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. Use 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 retries up to 8 times with an exponential backoff.

Vega EPG Provider API Guidelines

1. For the best performance, and access to the newest features, use the latest interface versions. Interface have versions with a suffix at the end of the name. For instance, ProgramLineupProvider2 is the recommended upgrade for ProgramLineupProvider. All references to interfaces or APIs assume 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. Call the commit API at the end to complete the transaction. You cannot reuse the object after calling commit(). Create a new object if necessary.
   2. Destroying the ChannelLineupProvider, ProgramLineupProvider, and LiveEventProvider objects without calling a commit ends the transaction.
   3. Commit a new channel lineup (if needed) before updating programs or using ProgramLineupProvider. You cannot interleave channel and program updates.
   4. The ProgramLineupProvider.upsert() operation fails if the channel corresponding to the program's ChannelDescriptor has not been committed.
5. Call the Lineup Provider functions on the same thread, since they are not thread safe.
6. The ChannelMetadata.name field indicates the marketing name for the channel in the Fire TV carousel. If ChannelMetadata.name isn't provided, or an empty string is provided, channel ingestion fails. Fire TV displays up to 25 alphanumeric characters, but the full channel name won't be displayed 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 are called during any subscription modifications. The include ingestChannelLineup(), ingestProgramLineup(), and ingestLiveEvents() respectively.
9. If using ProgramLineupProvider, you must provide at least 48 hour's worth of program data.
10. Specify channel logos through ChannelMetadata.logoUrl with multi-tone images of 120x68 pixels.

Error handling

Catch all errors during data ingestion and pushed them 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 ProgramLineupProvider upsert and LiveEventProvider add operations return a list of IUpsertProgramFailure or IAddLiveEventFailure objects that were not added to the commit queue. If all programs or live events are added to the commit queue successfully, the system returns an empty list.
   2. Push the failed programs and live events to your backend and trigger alarms to address invalid data issues quickly before the next sync.
   3. On failures, stop the program or live event ingestion process to address failures and retry, or partially commit the successful programs or live events.
2. StorageLimitError throws an error 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. InvalidArgumentError throws an error 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 system truncates the string and adds "…" to the end or InvalidArgumentError throws an error. The details for each field are 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 automatically retries 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 a large or difficult to parse program lineup ingestion.
• It eliminates the need to provide any channel metadata other than ChannelType during channel ingestion. The cloud service automatically obtains the rest.
• Better scalability as your customer base grows.

CDF is the most direct integration, which cuts latency, so you can enable future features more quickly. Make a choice between using a cloud-based catalog or ingestion through an on-device program lineup for each channel. This means you can have one channel that uses Gracenote ID, another that uses CDF, and a third that ingests through the on-device program lineup.

The following is a feature-level comparison between CDF, Gracenote, and on-device ingestion for Fire TV features.

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 your Refresh Method
Automatic using catalog lookup	✓	✓
On-device			✓

Providing a CDF station ID (preferred)

If you provide a CDF Station ID, the information syncs to the cloud daily through the Live TV app. These Station IDs provide a way to look up channels. The Fire TV catalog contains up to 14 days of programming information, which appears in the "Home" and "Live" tabs, as well as in the Channel Guide. It automatically refreshes 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 syncs to the cloud daily through the Live TV app. If the Gracenote ID is present, users can look up a channels with that ID in the Fire TV catalog. This catalog contains up to 14 days of programming information, and appears in the "Home" and "Live" tabs, as well as in the Channel Guide. It automatically refreshes 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.

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 of on-device program ingestion.

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 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 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 the developer doesn't use SortRank, the channel is placed at the bottom. Tiebreakers are 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 displays before Channel 3.10. Tiebreakers are 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 are displayed in the order based on the SortRank field value of the LiveEvent metadata provided during live event ingestion. If the developer doesn't use SortRank, the live event is placed at the bottom. Tiebreakers are ordered 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 updates, this rate refers to those customers in that paid tier.

UX field list

Metadata fields provide context in the Fire TV UX. Here are some example values.

UX Field	Description	Required for Certification (Y/N)	Associated Metadata Field
Program Name	The 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	The 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 the "Attribute" section of the Data Type Reference page.	N	Program.attributes
Program Image	16:9 show / movie image that fills the carousel tile. Use a resolution of 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. Use a resolution of 1280x720 or higher.	Y	Program.posterArtUrl
Channel Name	The 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 falls 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	Attribute genres to a channel so the channel shows 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: Jan 22, 2026