@amazon-devices/kepler-aps-client
重要须知： Kepler模拟器不支持此API。要测试您的实现，请使用Fire TV Stick。
Kepler APS客户端API是连接适用于Vega的React Native应用和亚马逊出版商服务 (APS) 的原生代码实现之间的桥梁。该API提供了getDeviceParams() 方法来获取您的竞价请求所需的参数。您可以通过C2S（客户端到服务器）或S2S（服务器到服务器）集成将这些参数发送到APS以完成请求。
本用户指南解释了APS客户端库的安装和API的使用。
备注
APS在KeplerTV平台上为发布者提供了两种不同的集成路径。这些集成允许发布者提交竞价请求以填充其广告间隙清单。
S2S集成： 发布者使用S2S后端调用检索APS键值对，该调用返回要传递给发布者广告服务器的竞价信息。您只能从服务器调用服务器。APS不支持客户端调用。调用参数为：
- API协议： 支持HTTP和HTTPS。
- 终端节点：https://aax-ott.amazon-adsystem.com/e/mdtb/ads
- 建议的超时时间： 500毫秒
C2S集成： 发布者使用C2S调用返回竞价信息，该竞价信息将以自定义键值的形式传递至发布者广告服务器。您只能从自己的应用调用服务器，APS支持使用此终端节点进行服务器端调用。调用参数为：
- API协议： HTTPS
- 终端节点：https://aax-ott-C2S.amazon-adsystem.com/e/C2S/ads
- 建议的超时时间： 1000ms
有关更多信息，请参阅S2S集成指南。
开始使用
先决条件
在开始之前，请确保您已经安装了Kepler SDK并创建了自己的适用于Kepler的React Native应用。此外，您需要遵循C2S或S2S集成指南来完成云端入门培训，并且您应该了解创建有效负载的工作原理。
设置
-
将以下库依赖项添加到package.json文件的
dependencies部分。"@amazon-devices/kepler-aps-client": "~1.0.0" -
在manifest.toml中添加以下组件和权限。
[components] [[components.interactive]] ... runtime-module = "/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0" ... [wants] [[wants.module]] id = "/com.amazon.kepler.apslib@IApsDeviceParametersMap"
用法
步骤1： 导入所需的组件
要使用APS API，请从@amazon-devices/kepler-aps-client导入所需的组件。
import {
ApsDeviceParametersMap,
ApsClientLibraryAPI,
ApsIntegrationType,
SCREEN_HEIGHT_DEVICE_PARAM,
SCREEN_WIDTH_DEVICE_PARAM,
DNT_DEVICE_PARAM,
IFA_DEVICE_PARAM,
UA_DEVICE_PARAM,
MAKE_DEVICE_PARAM,
LANGUAGE_DEVICE_PARAM,
MODEL_DEVICE_PARAM,
OS_DEVICE_PARAM,
OSV_DEVICE_PARAM,
} from '@amazon-devices/kepler-aps-client';
步骤2： 获取设备参数
ApsClientLibraryAPI.getDeviceParams() 是异步的，它返回一个Promise，您可以使用await或then() 构造在其上进行等待。成功后，Promise的有效负载是ApsDeviceParametersMap（其中包含来自必需参数的键）到其相应值的映射。如果发生错误，Promise将被拒绝，并显示一条错误消息。
使用该函数的建议方法是在应用加载时调用该函数，然后缓存返回值。
此示例假设是服务器到服务器 (S2S) 集成，如果是C2S集成，则改为传递ApsIntegrationType.C2S。以下示例演示如何使用then() 构造处理成功和错误的情况。
const apsGetS2SWait = async (key: string) => {
console.debug(`[APS][${key}] executing apsGetS2SWait`);
ApsClientLibraryAPI.getDeviceParams(ApsIntegrationType.S2S).then((deviceParams: ApsDeviceParametersMap) => {
console.debug(`[APS][${key}] S2S aps device config: ${SCREEN_HEIGHT_DEVICE_PARAM}, val: ${deviceParams.height}`);
console.debug(`[APS][${key}] S2S aps device config: ${SCREEN_WIDTH_DEVICE_PARAM}, val: ${deviceParams.width}`);
console.debug(`[APS][${key}] S2S aps device config: ${DNT_DEVICE_PARAM}, val: ${deviceParams.dnt}`);
console.debug(`[APS][${key}] S2S aps device config: ${IFA_DEVICE_PARAM}, val: ${deviceParams.ifa}`);
console.debug(`[APS][${key}] S2S aps device config: ${UA_DEVICE_PARAM}, val: ${deviceParams.ua}`);
console.debug(`[APS][${key}] S2S aps device config: ${MAKE_DEVICE_PARAM}, val: ${deviceParams.make}`);
console.debug(`[APS][${key}] S2S aps device config: ${LANGUAGE_DEVICE_PARAM}, val: ${deviceParams.language}`);
console.debug(`[APS][${key}] S2S aps device config: ${MODEL_DEVICE_PARAM}, val: ${deviceParams.model}`);
console.debug(`[APS][${key}] S2S aps device config: ${OS_DEVICE_PARAM}, val: ${deviceParams.os}`);
console.debug(`[APS][${key}] S2S aps device config: ${OSV_DEVICE_PARAM}, val: ${deviceParams.osv}`);
},
function (error: Error) {
console.error(`[APS][${key}] FAIL 无法获取配置：${error["message"]}`);
}
);
}
检查必需参数
除了从API检索到的设备参数外，还从发送到服务器的HTTP请求中捕获IP。将其作为请求有效负载的一部分纳入。有关更多信息，请参阅下面的必需参数表。
完成有效负载
完成HeaderBidding请求的JSON有效负载创建，并在剩余的云交互之后基于C2S或S2S集成指南提出HTTPS请求。
必需参数
| 参数 | 描述 | 集成类型：S2S（是/否） | 集成类型：C2S（是/否） | 由此API提供 |
|---|---|---|---|---|
| h | 屏幕的物理高度（以像素为单位） | 是 | 是 | 是 |
| w | 屏幕的物理宽度（以像素为单位） | 是 | 是 | 是 |
| dnt | 浏览器在标题中设置的标准“Do Not Track”（不要追踪）标记，其中0 = 追踪不受限制，1 = 不要追踪。 | 是 | 是 | 是 |
| ifa | 您设备的广告ID | 是 | 是 | 是 |
| ua | 设备用户代理字符串 | 是 | 是 | 是 |
| make | 设备制造商（例如，“Amazon”）。 | 是 | 是 | 是 |
| language | 使用ISO-639-1-alpha-2的设备语言 | 是 | 是 | 是 |
| model | 设备型号（例如，“AFTT”）。 | 是 | 是 | 是 |
| os | 设备操作系统（例如，“Android”）。 | 是 | 否 | 是 |
| osv | 设备操作系统版本（例如，“5.1.1”）。 | 是 | 否 | 是 |
| ip | 离设备最近的IPv4地址（公共IP）（例如，“204.78.58.34”）。 | 是 | 否 | 否（注：从发送到服务器的http请求中捕获IP）。 |
模块
- index
- turbo-modules/AmazonAPSClientTurboModule
- turbo-modules/AmazonAPSClientTurboModule
- turbo-modules/ApsClientLibraryAPI
- turbo-modules/ApsClientLibraryAPI
- turbo-modules/helpers/ApsHelpers
- turbo-modules/helpers/ApsHelpers
- turbo-modules/helpers/ApsHelpers
- turbo-modules/types/ApsErrors
- turbo-modules/types/ApsErrors
- turbo-modules/types/ApsErrors
- turbo-modules/types/ApsTypes
- turbo-modules/types/ApsTypes
- turbo-modules/types/ApsTypes
Last updated: 2025年10月2日
