@amazon-devices/kepler-aps-client

The Vega APS Client API is a bridge between React Native for Vega apps and the native code implementation for the Amazon Publisher Services(APS). The API provides the getDeviceParams() method to fetch the required parameters for your bid request. You send these parameters to APS via C2S (Client-to-Server) or S2S (Server-to-Server) integration to complete the request.

This user guide explains APS client library installation and API usage. For an introduction to Amazon Publisher Services, see Amazon Publisher Services.

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 to use the APS device side APIs.

Get started with APSClientLibrary

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.83.0",
      "@amazon-devices/kepler-aps-client": "~1.0.11"
   }

Step 2. Update your manifest file

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

1. components.interactive must include the appropriate runtime-module for your React Native version.
2. wants.module must include id = "/com.amazon.kepler.apslib@IApsDeviceParametersMap".

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

• React Native 0.72
• React Native 0.83

   [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"

   [package]
   title = "APS Sample Application"

   [components]
   [[components.interactive]]
   ...
   runtime-module = "/com.amazon.kepler.runtime.react_native_kepler_4@IReactNativeKepler_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"]}`);
   }
);
}

Build and install your app

Build your app

This example uses an app named mykeplerapp.

Step 1. Install app dependencies.

npm install

Step 2. Generate the .vpkg file.

npx react-native build-vega

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

vmsgr send pkg://com.amazondeveloper.mykeplerapp.main

API Reference

Classes

• ApsClientLibraryAPI
• ApsError — Generic APS error
• InternalError — Unrecoverable/unknown arbitrary system error
• NotFoundError — Error when the retrieved parameter is null
• UnsupportedError — Error when passing an unsupported integration type

Interfaces

• AmazonAPSClientTurboModule

Enumerations

• ApsIntegrationType — Types that Amazon offers publishers with for APS integration.

Type Aliases

• ApsDeviceParametersMap
• DeviceParamType

Functions

• parseError

Variables

• DNT_DEVICE_PARAM
• IFA_DEVICE_PARAM
• LANGUAGE_DEVICE_PARAM
• MAKE_DEVICE_PARAM
• MODEL_DEVICE_PARAM
• OS_DEVICE_PARAM
• OSV_DEVICE_PARAM
• SCREEN_HEIGHT_DEVICE_PARAM — Key of returned device parameters.
• SCREEN_WIDTH_DEVICE_PARAM
• UA_DEVICE_PARAM

Last updated: Jul 22, 2026