Amazon Publisher Services

Amazon Publisher Services (APS) provides a HeaderBidding solution to help publishers transact through realtime bidding to get ads for their content.

The APSClientLibrary is a library that provides a single API for Amazon Publisher apps to retrieve device parameters. You can compile your bid request and send it to APS through a client-to-server (C2S) or server-to-server (S2S) integration.

This document explains the APSClientLibrary installation and API usage.

• Prerequisites
• Get started with APSClientLibrary
  • Step 1. Include the package dependencies in your app
  • Step 2. Update your manifest file
  • Step 3. Import the API into your app
  • Step 4. Check the required parameters
  • Step 5. Complete the payload
• Required parameters
• Installation and setup
  • Build your app
  • Install your package
  • Install the app and launch it
• APS Streaming TV integration
  • The C2S integration
  • The S2S integration

Prerequisites

Before you begin, make sure you have installed the Vega SDK and created your own JavaScript app. You must also have followed either the C2S or S2S integration guide to complete the cloud side onboarding, and you should understand how payload creation works.

Here's how you use the APS device side APIs.

Get started with APSClientLibrary

Use APS client library "@amazon-devices/kepler-aps-client": "^1.0.0" for react native API integration.

Step 1. Include the package dependencies in your app

Add the library as a dependency in your package's package.json file.

"dependencies": {
      "@amazon-devices/react-native-kepler": "~2.0.0",
      "react": "18.2.0",
      "react-native": "0.72.0",
      "@amazon-devices/kepler-aps-client": "^1.0.0"
   }

Step 2. Update your manifest file

Update your manifest.toml file to include the required dependencies.

1. components.interactive must include runtime-module = "/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0".
2. wants.module must include id = "/com.amazon.kepler.apslib@IApsDeviceParametersMap".

The following is an example for a sample app. manifest.toml

   [package]
   title = "APS Sample Application"

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

   [wants]
   [[wants.module]]
   id = "/com.amazon.kepler.apslib@IApsDeviceParametersMap"

Step 3. Import the API into your app

Import the required device parameters for your JavaScript app.

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';

ApsClientLibraryAPI.getDeviceParams is asynchronous and returns a Promise which can be used with an await or then() construct. On success, the payload of the Promise is a mapping of a ApsDeviceParametersMap, which contains keys from Required Parameters) to their respective values. If an error occurs, 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. The following code example demonstrates handling both success and error cases using the then() construct.

This example assumes a server-to-server (S2S) integration passing ApsIntegrationType.c2s instead of a client-to-server (C2S) integration.

The following code sample 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"]}`);
   }
);
}

Required parameters

Installation and setup

Build your app

This example uses an app named mykeplerapp.

Step 1. Source the VegaSDK environment.

source <path-to-kepler-sdk>/environment-setup-sdk.sh

Step 2. Install app dependencies.

npm install

Step 3. Generate the .vpkg file.

npx react-native build-kepler

Install your package

Install your package and run it.

vda push ./kepler-build/vpkg/mykeplerapp_armv7.vpkg /tmp

Install the app and launch it

vda shell

vpm install /tmp/mykeplerapp.vpkg

vlcm launch-app pkg://com.amazondeveloper.mykeplerapp.main

APS Streaming TV integration

Amazon Publisher Services offers publishers two distinct integration paths for the Vega TV platform. These integrations allow publishers to submit bid requests to fill their ad break inventory.

The C2S integration

Publishers use a C2S call that returns the bid information to the publisher ad server as custom key values. You can only call our server from your app, since we don’t support server-side calls with this integration.

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

See the C2S integration guide for more information.

The S2S integration

Publishers retrieve APS key value pairs using an S2S back-end call that returns the bid information to the publisher ad server. You can call our server only from your server, since we don’t support client-side calls.

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

See the S2S integration guide for more information.

Last updated: Sep 30, 2025