Deep Linking in Vega Apps

A deep link is a type of URL or intent that takes a user directly to a specific location within an app, instead of just opening the app's main screen. On Fire OS, deep links are typically handled through Intent URIs, and apps must be set up to receive and process these links. Vega uses the Vega Messaging Library to support deep links. Fire TV supports the following deep link use cases.

1. Deep Link from Fire TV to your app

Fire TV displays featured content, which refers to sponsored tiles or promotional material shown on the Fire TV home screen. These are essentially advertisements designed to help users discover new streaming content, apps, or services. When a user clicks a featured content tile, the deep link launches the app and navigates directly to the relevant content or promotional page. For information on how to to implement Feature Rotator deeplinks in Vega apps, see Handle Featured Content Deep Link in Kepler Apps.

For more information about featured content, see Deep Linking to Featured Content from the Fire TV UI in the Fire OS documentation.

2. Deep link from your app to amazon clients

You can deep link from your app to the Amazon Appstore or retail website to direct users to specific apps, search results, or developer pages. For example, you can initiate a forced update for your app on Fire TV using a deep link that directs the user to the app's detail page in the Amazon Appstore. This deep link includes the app's ASIN and an intent=app_update parameter. For information about supported links for deep linking to Amazon clients within your app, see Deep Linking from within Your App.

3. App to app deep links

App to app deep links allow an app to send a deep link to another app using a custom URI. Apps commonly use this to open specific content such as a movie, TV show, or live channel, in another app based on the contract between then apps

Implementing Deep Links in Vega

Message Addressing Schemes

Vega Messaging primarily uses a URI based system. However, to maintain compatibility with existing Fire OS apps, limited support for intent style URIs is available. To provide backward compatibility with featured content, Vega supports the same deep link URIs used by Fire OS apps. Particularly the Fire OS based intent style scheme.

For information about the messaging addressing schemes that Vega supports, see Message Addressing Schemes.

Define the URI using supported schemes such as custom URIs (myapp://…) or HTTPS links (https://…). Avoid query parameters in the URI, just define the base path. For information about defining URIs, see Message Addressing Schemes.

Example URIs:

"deep-link-sample-app://home",  
"deep-link-sample-app://details", 
"https://deep-link-sample-app.com/search"

Step 1: Add manifest entries

Step 1.1: Add messages and privileges

For each supported URI, add a corresponding [[message]] block in your app's manifest. To restrict who can send or receive a message, attach sender and receiver privileges to the message section. For information about setting sender and receiver privileges, see the "Add Security Rules" section in the Message User Guide.

[[message]]
uri = "deep-link-sample-app://home"
sender-privileges = ["*"]             # anyone can call this Deep Link
receiver-privileges = ["self"]        # only this app can receive this Deep Link

[[message]]
uri = "deep-link-sample-app://details"
sender-privileges = ["*"]             # anyone can call this Deep Link
receiver-privileges = ["self"]        # only this app can receive this Deep Link

[[message]]
uri = "https://deep-link-sample-app.com/search"
sender-privileges = ["*"]             # anyone can call this Deep Link
receiver-privileges = ["self"]     

Step 1.2 Map messages to the launch component

Deep links use the pkg:// scheme followed by the name of the component to launch Lifecycle components by name.

Other URI schemes don't directly identify the component to launch. You must specify additional information in the manifest in the offers.message-target section and define which component to launch for each deep link.

[offers]
[[offers.message-target]]

uris = [
  "deep-link-sample-app://home",
  "deep-link-sample-app://details",
  "https://deep-link-sample-app.com/search"
  ]
uses-component = "com.amazondeveloper.kepler.deeplink.sampleapp.main"

Step 1.3 Define module

Define a module and list all of the messages associated with it. For information on the correct format and guidelines for accepted module IDs, see the "[[offers.module]]" section of Manifest [offers] Section.

[[offers.module]]
id = "/com.amazondeveloper.kepler.deeplink.sampleapp@IDepp links"
includes-messages = [
  "deep-link-sample-app://home",
  "deep-link-sample-app://details",
  "https://deep-link-sample-app.com/search"
]

The following sample shows the final manifest structure.

Note: Replace com.amazondeveloper.kepler.deeplink.sampleapp with your app's actual package ID.

[package]
title = "Vega Deep Link Sample Application"
version = "0.1.0"
id = "com.amazondeveloper.kepler.deeplink.sampleapp"

[components]
[[components.interactive]]
id = "com.amazondeveloper.kepler.deeplink.sampleapp.main"
runtime-module = "/com.amazondeveloper.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0"
launch-type = "singleton"
categories = ["com.amazondeveloper.category.main"]

# 1. Define deep link message
[[message]]
uri = "deep-link-sample-app://home"
sender-privileges = ["*"]             # anyone can call this Deep Link
receiver-privileges = ["self"]        # only this app can receive this Deep Link

[[message]]
uri = "deep-link-sample-app://details"
sender-privileges = ["*"]             # anyone can call this Deep Link
receiver-privileges = ["self"]        # only this app can receive this Deep Link

[[message]]
uri = "https://deep-link-sample-app.com/search"
sender-privileges = ["*"]             # anyone can call this Deep Link
receiver-privileges = ["self"]        # only this app can receive this Deep Link

# 2. Map messages to launch component
[offers]
[[offers.message-target]]
uses-component = "com.amazondeveloper.kepler.deeplink.sampleapp.main"
uris = [
  "deep-link-sample-app://home",
  "deep-link-sample-app://details",
  "https://deep-link-sample-app.com/search"
]

# 3. Define module 
[[offers.module]]
id = "/com.amazondeveloper.kepler.deeplink.sampleapp@IDepp links"
includes-messages = [
  "deep-link-sample-app://home",
  "deep-link-sample-app://details",
  "https://deep-link-sample-app.com/search"
]

Step 2: Receive messages in your app

Vega uses react-native linking to send and receive messages. The following procedure shows how to to receive a deep link message and process it in your app.

Step 2.1 Import the linking library

import {Linking} from 'react-native';

Step 2.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 triggered, the app receives a url event. To listen for the event, use Linking.addEventListener().

const subscription = Linking.addEventListener('url', ({url}) => {
      console.log('Received deep link while running:', url);
        handleDeepLink(url); // your custom function
      }
 });

Step 2.3 Receive message when App is not open

If the app is not running when a deep link is triggered, use Linking.getInitialURL() to get the URL that launched it. Call this on app launch (for example, inside ()) to check if a deep link was used to start the app.

const handleInitialDeep link = 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 and perform the required action.

import {Linking} from 'react-native';

useEffect(() => {  
  const handleInitialDeep link = 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(); 
  };
}, []);

Step 3: Send a message from your app

The following sample function shows how to launch a URL in another app using the Linking API. This step is optional and should be used only when your app needs to open another app.

const launchAppWithUrl = async (url) => {
  try {
    const supported = await Linking.canOpenURL(url);

    if (supported) {
      console.log('Launching the URL:', url);
      await Linking.openURL(url);
    } else {
      console.log('Cannot open URL:', url);
    }
  } catch (error) {
    console.error('Error launching app with URL:', error);
  }
};

Testing deep links

To test a deep link you can send CLI commands to your app. Include any query parameters as needed, based on how your app handles them. You app will be invoked to receive and process the message.

vda shell vlcm launch-app "deep-link-sample-app://details?asin=B00MULA"
vda shell vlcm launch-app "deep-link-sample-app://home"

For information on debugging your app if it does not receive the deep link messages, see the "Debugging FAQs" section of the Messaging User Guide.

Releated topics

• Handle Featured Content Deep Link in Vega Apps
• Message Addressing Schemes
• Messaging User Guide

Last updated: Oct 15, 2025