Amazon Publisher Services - Amazon Vega Docs

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

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.8" 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.8"
   }

Step 2. Update your manifest file

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

components.interactive must include runtime-module = "/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0".
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"]}`);
   }
);
}

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.

Step 5. Complete the payload

Complete the JSON payload creation for a HeaderBidding request and makes an HTTPS request following the remaining cloud interactions using 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, 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).

Installation and setup

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

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:
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: .
Recommended Timeout: 500 ms.

See the S2S integration guide for more information.

​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