@amazon-devices/kepler-aps-client

Important: Kepler Simulator does not support this API. To test your implementation, use the Fire TV Stick.

The Kepler APS Client API is a bridge between React Native for Kepler apps and the native code implementation for the Amazon Publisher Services(APS). It provides a single API for Amazon Publisher apps to retrieve required parameters which are used to compile their bid request and sent to APS via C2S (Client-to-Server) or S2S (Server-to-Server) integration.

This user guide explains APS client library installation and API usage.

Remarks

APS offers publishers two distinct integration paths on the KeplerTV platform. These integrations allow publishers to submit bid request to fill their ad break inventory.

S2S Integration: Publishers retrieve APS key value pairs using an S2S back-end call that returns the bid information to pass to the publisher ad server. You can only call the server only from your server, APS doesn't support client side calls. The call parameters are:

• API Protocol: HTTP and HTTPS are supported.
• Endpoint: https://aax-ott.amazon-adsystem.com/e/mdtb/ads
• Recommended Timeout: 500ms

C2S Integration: Publishers use a C2S call that returns the bid information to pass to the publisher ad server in the form of custom key values. You can only call the server from your app, APS support server side calls with this endpoint. The call parameters are:

• API Protocol: HTTPS
• Endpoint: https://aax-ott-C2S.amazon-adsystem.com/e/C2S/ads
• Recommended Timeout: 1000ms

For more information, see the S2S integration guide.

Get Started

Prerequisites

Before you begin, make sure you have installed the Kepler SDK and created your own React Native for Kepler app. Additionally, you need to have followed either the C2S or S2S integration guide to complete the cloud side onboarding and you should understand how payload creation works.

Setup

1. Add the following library dependency to the dependencies section of your package.json file.

   Copy code Copied to clipboard.

        "@amazon-devices/kepler-aps-client": "~1.0.0"
   

2. Add following component and privilege in your manifest.toml.

   Copy code Copied to clipboard.

   [components]
   [[components.interactive]]
   ...
   runtime-module = "/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0"
   ...
   
   [wants]
   [[wants.module]]
   id = "/com.amazon.kepler.apslib@IApsDeviceParametersMap"
   

Usage

Step 1: Import the required components

To use the APS API, import the required components from @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';

Step 2: Get the device paramaters

ApsClientLibraryAPI.getDeviceParams() is asynchronous and returns a Promise which can be waited on using an await or then() construct. On success, the payload of the Promise is a mapping of ApsDeviceParametersMap which contains keys from Required Parameters to their respective values; on error, the Promise is rejected with an error message.

The recommended way to use the function is to call it when the app loads and cache the returned value.

This example assumes it's Server-to-Server (S2S) integration pass ApsIntegrationType.C2S instead if it's a C2S integration. The example demonstrates handling both success and error cases using the then() construct.

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 Could not get configs: ${error["message"]}`);
      }
  );
}

Check Required Parameters

Besides the device parameters retrieved from the API, also capture the IP from the HTTP request sent to the server and include it as part of the request payload. Refer to the Required Parameters table below for more information.

Complete the payload

Complete the JSON payload creation for a HeaderBidding request and makes an HTTPS request following the remaining cloud interactions based on either the C2S or S2S integration guides.

Required Parameters

Modules

• 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: Oct 02, 2025