Vega应用中的深层链接
深层链接是一类URL或意图，会将用户直接引导至应用内部的特定位置，而不是仅仅打开应用的主屏幕。在Fire OS上，通常通过意图URI处理深层链接，并且必须对应用进行设置才能接收和处理这些链接。Vega使用Vega消息传递库来支持深层链接。Fire TV支持以下深层链接用例。
1. 从Fire TV深层链接到您的应用
Fire TV会显示精选内容，即：Fire TV主屏幕上显示的推广模块或推广材料。这些内容本质上是广告，旨在帮助用户发现新的流媒体内容、应用或服务。用户点击精选内容模块后，深层链接会启动应用并直接导航到相关内容或推广页面。有关如何在Vega应用中实现特色转盘深层链接的信息，请参阅在Vega应用中处理精选内容深层链接。
有关精选内容的更多信息，请参阅Fire OS文档中的Fire TV UI精选内容的深层链接。
2. 从您的应用深层链接到亚马逊客户端
可以从您的应用深层链接到亚马逊应用商店或零售网站，以将用户引导至特定的应用、搜索结果或开发者页面。例如，可以使用深层链接将用户引导至亚马逊应用商店中的应用详情页，从而在Fire TV上启动应用的强制更新。此深层链接包括应用的ASIN和一个intent=app_update参数。有关在应用内部提供亚马逊客户端的深层链接时支持哪些链接的信息，请参阅在您的应用内部提供深层链接。
3. 应用之间的深层链接
借助应用之间的深层链接，应用可以通过自定义URI将深层链接发送至其他应用。应用通常会使用该功能来根据应用之间的合约，在其他应用中打开特定内容，例如电影、电视节目或直播频道。
在Vega中实现深层链接
消息寻址方案
Vega消息传递主要使用基于URI的系统。但是，为了保持与现有Fire OS应用的兼容性，对意图样式URI的支持有限。为了让精选内容实现向后兼容，Vega同样支持Fire OS应用所使用的深层链接URI，尤其是基于Fire OS的意图样式方案。
有关Vega支持的消息寻址方案的信息，请参阅消息寻址方案。
使用支持的方案（例如自定义URI [myapp://…] 或HTTPS链接 [https://…]）来定义URI。不要在URI中使用query参数，只需定义基础路径即可。有关如何定义URI的信息，请参阅消息寻址方案。
示例URI：
"deep-link-sample-app://home",
"deep-link-sample-app://details",
"https://deep-link-sample-app.com/search"
步骤1： 添加清单条目
步骤1.1： 添加消息和权限
对于每个支持的URI，在应用的清单中添加相应的 [[message]] 块。要限制可以发送或接收消息的人员，请将发送者和接收者权限附加到message部分。有关如何设置发送者和接收者权限的信息，请参阅消息传递用户指南中的“添加安全规则”一节。
[[message]]
uri = "deep-link-sample-app://home"
sender-privileges = ["*"] # 任何人都可以调用此深层链接
receiver-privileges = ["self"] # 只有此应用可以接收此深层链接
[[message]]
uri = "deep-link-sample-app://details"
sender-privileges = ["*"] # 任何人都可以调用此深层链接
receiver-privileges = ["self"] # 只有此应用可以接收此深层链接
[[message]]
uri = "https://deep-link-sample-app.com/search"
sender-privileges = ["*"] # 任何人都可以调用此深层链接
receiver-privileges = ["self"]
步骤1.2 将消息映射到launch组件
深层链接使用pkg://方案后跟组件名称来按名称启动生命周期组件。
其他URI方案无法直接识别要启动的组件。对于每个深层链接，都必须在offers.message-target部分的清单中指定其他信息，并定义要启动的组件。
[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"
步骤1.3 定义模块
定义一个模块并列出与之相关的所有消息。有关可接受的模块ID的正确格式和相关指南的信息，请参阅清单 [offers] 部分的“[[offers.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"
]
以下示例展示了最终清单结构。
注意： 将com.amazondeveloper.kepler.deeplink.sampleapp替换为您应用的实际程序包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. 定义深层链接消息
[[message]]
uri = "deep-link-sample-app://home"
sender-privileges = ["*"] # 任何人都可以调用此深层链接
receiver-privileges = ["self"] # 只有此应用可以接收此深层链接
[[message]]
uri = "deep-link-sample-app://details"
sender-privileges = ["*"] # 任何人都可以调用此深层链接
receiver-privileges = ["self"] # 只有此应用可以接收此深层链接
[[message]]
uri = "https://deep-link-sample-app.com/search"
sender-privileges = ["*"] # 任何人都可以调用此深层链接
receiver-privileges = ["self"] # 只有此应用可以接收此深层链接
# 2. 将消息映射到launch组件
[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. 定义模块
[[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"
]
步骤2： 在您的应用中接收消息
Vega使用react-native linking来发送和接收消息。以下步骤展示了如何在您的应用中接收和处理深层链接消息。
步骤2.1 导入链接库
import {Linking} from 'react-native';
步骤2.2 应用已打开时接收消息
如果触发深层链接时，应用正在前台或后台运行，则该应用会收到url事件。为了侦听该事件，需要使用Linking.addEventListener()。
const subscription = Linking.addEventListener('url', ({url}) => {
console.log('运行时收到深层链接：', url);
handleDeepLink(url); // 您的自定义函数
}
});
步骤2.3 应用未打开时接收消息
如果触发深层链接时，应用处于未运行状态，则使用Linking.getInitialURL() 来获取启动过应用的URL。在应用启动时调用此方法（例如在 () 内），以检查是否使用过深层链接来启动应用。
const handleInitialDeep link = async () => {
try {
const initialUrl = await Linking.getInitialURL();
console.log('初始深层链接URL：', initialUrl);
if (initialUrl) {
handleDeepLink(initialUrl); // 您的自定义函数
}
} catch (error) {
console.error('处理初始深层链接时出错', error);
}
};
以下整合代码示例展示了如何接收和处理深层链接事件。请注意，您必须实现自定义handleDeepLink() 函数来解析URL和执行所需的操作。
import {Linking} from 'react-native';
useEffect(() => {
const handleInitialDeep link = async () => {
try {
const initialUrl = await Linking.getInitialURL();
console.log('初始深层链接URL：', initialUrl);
if (initialUrl) {
handleDeepLink(initialUrl); // 您的自定义函数
}
} catch (error) {
console.error('处理初始深层链接时出错', error);
}
};
const handleUrlEvent = ({ url }) => {
console.log('运行时收到深层链接：', url);
handleDeepLink(url); // 您的自定义函数
};
const subscription = Linking.addEventListener('url', handleUrlEvent);
handleInitialDeepLink();
return () => {
subscription.remove();
};
}, []);
步骤3： 从您的应用发送消息
以下示例函数展示了如何使用Linking API在其他应用中启动URL。此步骤是可选项，仅当您的应用需要打开其他应用时才适用。
const launchAppWithUrl = async (url) => {
try {
const supported = await Linking.canOpenURL(url);
if (supported) {
console.log('将启动URL：', url);
await Linking.openURL(url);
} else {
console.log('无法打开URL：', url);
}
} catch (error) {
console.error('使用URL启动应用时出错：', error);
}
};
测试深层链接
要测试深层链接，可以向您的应用发送CLI命令。根据您的应用对query参数的处理方式，在需要时添加任何query参数。您的应用会被调用，以接收和处理消息。
vda shell vlcm launch-app "deep-link-sample-app://details?asin=B00MULA"
vda shell vlcm launch-app "deep-link-sample-app://home"
有关如何在应用收不到深层链接消息时对其进行调试的信息，请参阅消息传递用户指南的“调试常见问题解答”一节。
相关主题
Last updated: 2025年10月15日
