@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.

components.interactive must include the appropriate runtime-module for your React Native version.
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"]}`);
   }
);
}

Step 4. Check the required parameters

Besides device parameters, 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 for more information.

Required parameters

Parameter	Description	IntegrationType: S2S	IntegrationType: C2S	Provided by This API
`h`	Physical height of the screen in pixels.	Y	Y	Y
`w`	Physical width of the screen in pixels.	Y	Y	Y
`dnt`	Standard “Do Not Track” flag as set in the header by the browser, where 0 = tracking is unrestricted, and 1 = Do Not Track.	Y	Y	Y
`ifa`	The Advertising ID for your Device.	Y	Y	Y
`ua`	Device user agent (a string).	Y	Y	Y
`make`	Device manufacturer (for example, Amazon).	Y	Y	Y
`language`	Device language using ISO-639-1-alpha-2.	Y	Y	Y
`model`	Device model (for example, AFTT).	Y	Y	Y
`os`	Device operating system (for example, Android).	Y	N	Y
`osv`	Device operating system version (for example, 5.1.1).	Y	N	Y
`ip`	IPv4 address closest to device (public IP) (for example, 204.78.58.34).	Y	N	N (Note for S2S only: Capture the IP from the HTTPS request sent to the server).

Step 5. Complete the payload

Complete the JSON payload creation for a HeaderBidding request and make an HTTPS request following the remaining cloud interactions using the C2S or S2S integration guides.

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

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

​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

​Required parameters

​Step 5. Complete the payload

​Build and install your app

​Build your app

​Install your package

​Install the app and launch it

​API Reference

​Classes

​Interfaces

​Enumerations

​Type Aliases

​Functions

​Variables