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

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: 500 ms

C2S Integration: Publishers use a C2S call that returns the bid information to pass to the publisher ad server as of custom key values. You can only call the server from your app, APS supports 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: 1000 ms

For more information, see the S2S integration guide.

Get Started

Prerequisites

Before you begin, make sure you have installed the Vega SDK and created your own React Native for Vega 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

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

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

Add the following component and privilege in your 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"

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 thay you can wait 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. 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

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, 1 = do not track.	Y	Y	Y
ifa	The Advertising ID for your Device.	Y	Y	Y
ua	Device user agent 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: capture the IP from the http request sent to the server)

​Remarks

​Get Started

​Prerequisites

​Setup

​Usage

​Step 1: Import the required components

​Step 2: Get the device paramaters

​Check Required Parameters

​Complete the payload

​Required Parameters

​Modules