Handle Featured Content Deep Link in Vega Apps
Fire TV includes promotional placements such as banners or tiles on the home screen that advertise specific content from your app. The content shown in the promotional placement is called Featured Content. Featured Content deep links take users directly to your promoted content bypassing the app's home page. A deep link is a specially formatted URL that launches a particular screen within the app.
For example, a merchandising slot in Fire TV highlights a football playoff game from ACME Media. Clicking the promotion will:
- Launch the ACME app
- Navigate the user directly to the game's detail or playback screen
If the app isn't installed, Fire TV redirects the user to the app's detail page for download. After installation and launch, the deep link automatically takes the user to the intended content, preserving the context.
This document provides guidance on implementing featured content deep links in Vega apps.
Featured Content deep links
Vega apps use the same Featured Content deep links as those on Fire OS. Featured Content deep links for Fire OS apps are generated following the steps documented in the Generate an Encoded Deep Link Intent for your Content section of "Deep Linking to Featured Content from the Fire TV UI".
The following example shows Fire OS app's encoded deep link. This URI is used to configure the featured content in Fire TV.
amzns://apps/android?asin=B080PZMHSN#Intent;S.intentToFwd=https%3A%2F%2Fwww.acme.com%2Fsome%2Fshow%2Frrn%3Acontent%3Ashows%3A123456789;end
For the purposes of respondinng to deep links, the URI consists of two parts a "header" the the Home Launcher uses to route the deep link to your app and the deep link that your app needs to parse.
Your Vega app receives the decoded version of the URI that comes after S.intentToFwd. You can use any online tools to get this decoded version.
https://www.acme.com/some/show/rrn:content:shows:123456789
Featured Content deep links are OS agnostic. They are identical on Vega and Fire OS and use Android intent-style URIs.
When you receive the deep link you must map the components of the intent fragment to the appropriate React Navigation components.
For information on encoded deep links, see the Encode your Deep Link Intent Using Android Studio step of "Deep Linking to Featured Content from the Fire TV UI".
Handle Featured Content deep links in your Vega app
Vega uses react-native linking to send and receive messages. The following procedure shows how to receive a message and process it in your app.
Step 1: Import the linking library
import {Linking} from 'react-native';
Step 2: Receive message when app is already open
If the app is running in the foreground or in the background when the deep link is received, the app receives a url event. To listen for the event, subscribe to the url event by calling Linking.addEventListener().
const subscription = Linking.addEventListener('url', ({url}) => {
console.log('Received deep link while running:', url);
handleDeepLink(url); // your custom function
}
});
Step 3: Receive message when app is not open
Call Linking.getInitialURL() on app launch (for example, inside useEffect()) to check whether a deep link initiated the app's start.
const handleInitialDeepLink = async () => {
try {
const initialUrl = await Linking.getInitialURL();
console.log('Initial deep link URL:', initialUrl);
if (initialUrl) {
handleDeepLink(initialUrl); // your custom function
}
} catch (error) {
console.error('Error handling initial deep link', error);
}
};
The following consolidated code sample shows how to receive and handle deep link events. Note, you must implement a custom handleDeepLink() function to parse the URL, retrieve the data, and perform the required action.
import {Linking} from 'react-native';
useEffect(() => {
const handleInitialDeepLink = async () => {
try {
const initialUrl = await Linking.getInitialURL();
console.log('Initial deep link URL:', initialUrl);
if (initialUrl) {
handleDeepLink(initialUrl); // your custom function
}
} catch (error) {
console.error('Error handling initial deep link', error);
}
};
const handleUrlEvent = ({ url }) => {
console.log('Received deep link while running:', url);
handleDeepLink(url); // your custom function
};
const subscription = Linking.addEventListener('url', handleUrlEvent);
handleInitialDeepLink();
return () => {
subscription.remove();
};
}, []);
export const handleDeepLink = (
url: string | null,
navigationRef: NavigationContainerRef<RootStackParamList>,
): boolean => {
try {
if (!url) {
return false;
}
// Implement code to parse the incoming deep link and use react navigation
// to route the request in your app as appropiate.
console.log(`deeplink-sample - received: ${url}`);
// url = https://www.acme.com/some/show/rrn:content:shows:123456789
return true;
} catch (error) {
console.error('Error handling deep link', error);
return false;
}
};
Test your deep link to Featured Content on Vega
When you sideload the app, it must be linked with the app's ASIN to test deep link. In the Fire TV Appstore, ASIN stands for Amazon Standard Identification Number. ASIN is 10-character alphanumeric string that will look like B080PZMHSN. Your Amazon contact can help you to get your app's ASIN.
Use following command to install the app linking ASIN. Replace the sample ASIN B080PZMHSN that comes after "store-id=" with your app's actual ASIN.
vda push "keplerdeeplinksampleapp_armv7.vpkg" /tmp
vda shell vpm install-async tmp/"keplerdeeplinksampleapp_armv7.vpkg" —store-id="B080PZMHSN"
You can test deep link by sending CLI commands to your app. Include the 'amzns' part in the CLI command
vda shell "vmsgr send '<add amzns URL here> ' "
Use the following deep link to validate the integration. Note that deep link has your app's ASIN after "asin=".
vda shell "vmsgr send 'amzns://apps/android?asin=B080PZMHSN#Intent;S.intentToFwd=https%3A%2F%2Fwww.acme.com%2Fsome%2Fshow%2Frrn%3Acontent%3Ashows%3A123456789;end'"
The handleDeepLink() function in the sample code displays the following message.
deeplink-sample - received: https://www.acme.com/some/show/rrn:content:shows:123456789
Related topics
Last updated: Sep 30, 2025
