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

Your Vega OS and Fire OS will use the same Featured Content deep links. To generate Featured Content deep links for Fire OS and Vega OS apps, follow 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 a 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 purpose of responding to deep links, the URI consists of two parts: a “header” 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 that you must implement a custom handleDeepLink() function to parse the URL, retrieve the data, and perform the required action.

import { useEffect } from 'react';
import { Linking, Text, View } from 'react-native';

// Vega docs: handleDeepLink utility function
const handleDeepLink = (url: string | null): 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 appropriate.
        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;
    }
};

// React component wrapping the Vega docs useEffect
const DeepLinkApp = () => {
    useEffect(() => {
        const handleInitialDeepLink = async () => {
            try {
                const initialUrl = await Linking.getInitialURL();
                console.log('Initial deep link URL:', initialUrl);

                if (initialUrl) {
                    handleDeepLink(initialUrl);
                }
            } catch (error) {
                console.error('Error handling initial deep link', error);
            }
        };

        const handleUrlEvent = ({ url }: { url: string }) => {
            console.log('Received deep link while running:', url);
            handleDeepLink(url);
        };

        const subscription = Linking.addEventListener('url', handleUrlEvent);

        void handleInitialDeepLink();

        return () => {
            subscription.remove();
        };
    }, []);

    return (
        <View style={{ padding: 20 }}>
            <Text style={{ fontSize: 24 }}>Deep Link Example</Text>
            <Text>Listening for deep links...</Text>
        </View>
    );
};

export default DeepLinkApp;

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 the deep link. In the Fire TV Appstore, ASIN stands for Amazon Standard Identification Number. ASIN is a 10-character alphanumeric string that will look like B080PZMHSN. Your Amazon contact can help you to get your app’s ASIN. Use the following command to install the app linking ASIN. Replace the sample ASIN B080PZMHSN that comes after “store-id=” with your app’s actual ASIN.

vega exec vda push "keplerdeeplinksampleapp_armv7.vpkg" /tmp
vega exec vda shell vpm install-async /tmp/keplerdeeplinksampleapp_armv7.vpkg --store-id="B080PZMHSN"

You can test deep links by sending CLI commands to your app. Include the ‘amzns’ part in the CLI command. Use the following deep link to validate the integration. Note that the deep link has your app’s ASIN after “asin=”.

vega exec 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

​Featured Content deep links

​Handle featured content Deep Links in your Vega app

​Step 1: Import the linking library

​Step 2: Receive message when app is already open

​Step 3: Receive message when app is not open

​Test your Deep Link to featured content on Vega

​Related topics