KeplerAPSClientTurboModule

KeplerAPSClientTurboModule is a bridge between KeplerScript applications and the OKIDL implementation for the Amazon Publisher Services(APS). It provides a single API for Amazon Publisher apps to retrieve required parameters, which will be used to compile their bid request and sent to APS via c2s or s2s integration.

This document will serve as a user guide and will explain APS client library installation and API usage.

Release Note

We're thrilled to announce the latest release of APS client library (kepler-aps-client)[1.0.0] for API integration. This is the latest release of the APS API builds on the pervious release to provide a complete end-to-end experience for developers and APS integrators.

APS Streaming TV Integration

Amazon Publisher Services 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 be passed to publisher ad server. You can call our server only from your server, we don’t support client side calls.

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

c2s Integration: Publishers use a c2s call that returns the bid information to be passed to publisher ad server in the form of custom key values. You can call our server only from your application, we don’t support server side calls with this endpoint.

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

Prerequisites

Before you begin, make sure you have installed the Kepler SDK and created your own JavaScript 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.

Now, let’s start using the APS device side APIs.

Use APSClientLibrary in your app

• If you are a React Native developer, proceed to Step 1 to use the KeplerAPSClientTurboModule.
• If you are a native developer, proceed to Step 2 to use KeplerAPSClientInterface.

Step 1. React Native Integration

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

  package.json

  "dependencies": {
      "@amazon-devices/kepler-aps-client": "^1.0.0"
  }

• Import the API into your 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';

• Here’s how you use the API. ApsClientLibraryAPI.getDeviceParams() is asynchronous and returns a Promise which can be waited on using an await or then() construct. On success, the payload of the Promise will be a mapping of ApsDeviceParametersMap (contains keys from Required Parameters) to their respective values; on error, the Promise will be rejected with an error message.

The recommended way to use the function is to call it when the app loads and cache the value returned. The following code example demonstrates handling both success and error cases using the then() construct:

• This example assumes it's Server-to-Server (S2S) integration pass ApsIntegrationType.c2s instead if it's Client-to-Server (C2S) integration

  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"]}`);
      }
  );
  }

Continue to Step 3.

Step 2. Native (C++) Integration

• Add the library as a dependency to your CMakeLists.txt

  CMakeLists.txt

  find_package(Apmf REQUIRED)
  find_package(Kepler REQUIRED)
  find_package(KeplerAPSClientInterface REQUIRED)
  
  kepler_add_idl_import_library(
      idl_pkg
      PACKAGES
      com.amazon.kepler.apslib
  )
    
  target_link_libraries(${PROJECT_NAME} PRIVATE
      KeplerAPSClientInterface::KeplerAPSClientInterface
  )

• Import the API into your app.

      #include <apmf/iface/com/amazon/kepler/apslib/IApsClientFactory.h>
      #include <apmf/iface/com/amazon/kepler/apslib/IApsDeviceParameters.h>
      #include <apmf/iface/com/amazon/kepler/apslib/IApsDeviceParametersMap.h>
      #include <apmf/iface/com/amazon/kepler/apslib/IApsS2SDeviceParametersMap.h>
      #include <apmf/iface/com/amazon/kepler/apslib/ApsIntegrationType.h>
      #include <apmf/iface/com/amazon/kepler/apslib/DeviceParamType.h>
      #include <apmf/iface/com/amazon/kepler/apslib/ApsError.h>
      #include <apmf/iface/com/amazon/kepler/apslib/InternalError.h>
      #include <apmf/iface/com/amazon/kepler/apslib/NotFoundError.h>
      #include <apmf/iface/com/amazon/kepler/apslib/UnsupportedError.h>
  
      using namespace apmf::iface::com::amazon::apmf;
      using namespace apmf::iface::com::amazon::kepler::apslib;

• Here’s how you use the API. IApsClientFactory is a factory build that will provide an interface to support building an IApsDeviceParametersMap object based on the integration type. On success, the returned object has accessor functions to retrieve the parameters (see Required Parameters) and their respective values; on error, the API will throw an error of types ApsError, NotFoundError, UnsupportedError, or InternalError.

  auto const process = apmf::GetProcessObject();
  
  try {
      auto const component = process->getComponent("/com.amazon.kepler.apslib");
      auto const apsFactory = component.TryQueryInterface<IApsClientFactory>();
      auto const apsParams = apsFactory->makeApsDeviceParameters();
      auto const apsIntegration = ApsIntegrationType::S2S;
      auto const apsParamsMap = apsParams->getDeviceParams(apsIntegration);
        
      std::cout << "[APS] s2s aps device config: " << DeviceParamType::SCREEN_HEIGHT.value << ", val: " << apsParamsMap->getHeight() << std::endl;
      std::cout << "[APS] s2s aps device config: " << DeviceParamType::SCREEN_WIDTH.value << ", val: " << apsParamsMap->getWidth() << std::endl;
      std::cout << "[APS] s2s aps device config: " << DeviceParamType::DNT.value << ", val: " << apsParamsMap->getDNT() << std::endl;
      std::cout << "[APS] s2s aps device config: " << DeviceParamType::IFA.value << ", val: " << apsParamsMap->getIFA() << std::endl;
      std::cout << "[APS] s2s aps device config: " << DeviceParamType::UA.value << ", val: " << apsParamsMap->getUA() << std::endl;
      std::cout << "[APS] s2s aps device config: " << DeviceParamType::MAKE.value << ", val: " << apsParamsMap->getMake() << std::endl;
      std::cout << "[APS] s2s aps device config: " << DeviceParamType::LANGUAGE.value << ", val: " << apsParamsMap->getLanguage() << std::endl;
      std::cout << "[APS] s2s aps device config: " << DeviceParamType::MODEL.value << ", val: " << apsParamsMap->getModel() << std::endl;
      std::cout << "[APS] s2s aps device config: " << DeviceParamType::OS.value << ", val: " << apsParamsMap->getOS() << std::endl;
      std::cout << "[APS] s2s aps device config: " << DeviceParamType::OSV.value << ", val: " << apsParamsMap->getOSV() << std::endl;
  
  } catch (const BaseError &ex) {
      std::cerr << "[APS] ERROR: " << ex.what();
  }

Continue to Step 3.

Step 3. Check Required Parameters

Required Parameters

Besides the device parameters retrieved from the API, also 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 below for more information.

| 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 (e.g. “Amazon”) | Y | Y | Y | | language | Device language using ISO-639-1-alpha-2 | Y | Y | Y | | model | Device model(e.g., “AFTT”)| Y | Y | Y | | os | Device operating system (e.g., “Android”) | Y | N | Y | | osv | Device operating system version (e.g., “5.1.1”). | Y | N | Y | | ip | IPv4 address closest to device (public IP) (e.g., "204.78.58.34") | Y | N | N (Note: please capture the IP from the http request sent to server) |

Note: Use a TV device to perform testing, the API will not fully function on a simulator.

Step 4.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.