Amazon Publisher Services - Amazon Vega Docs

Amazon Publisher Services（APS）が提供するHeaderBiddingソリューションを利用すると、パブリッシャーはリアルタイム入札を通じて取引を行い、コンテンツの広告枠を獲得できます。 APSClientLibraryはAmazon Publisher向けのライブラリの1つで、自身のアプリでデバイスパラメーターを取得するための単一のAPIを提供します。これにより、入札リクエストをコンパイルし、クライアントからサーバー（C2S）またはサーバー間（S2S）の統合を介してAPSに送信できます。このドキュメントでは、APSClientLibraryのインストールとAPIの使用方法について説明します。

前提条件

まず、Vega SDKをインストール済みであることと、自身のJavaScriptアプリを作成済みであることを確認してください。また、クラウド側のオンボーディングを完了するには、C2SまたはS2Sの統合ガイドのいずれかに従っている必要があり、ペイロードの作成方法について理解しておく必要があります。 APSデバイス側APIの使用方法は以下の通りです。

APSClientLibraryを始める

React Native APIの統合には、APSクライアントライブラリ"@amazon-devices/kepler-aps-client": "^1.0.0"を使用します。

手順1：パッケージの依存関係をアプリに追加する

ライブラリを、パッケージのpackage.jsonファイルに依存関係として追加します。

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

手順2：マニフェストファイルを更新する

manifest.tomlファイルを更新して、必要な依存関係を含めます。

components.interactiveには、runtime-module = "/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0"を含める必要があります。
wants.moduleには、id = "/com.amazon.kepler.apslib@IApsDeviceParametersMap"を含める必要があります。

以下は、サンプルアプリのmanifest.tomlの例です。

   [package]
   title = "APSサンプルアプリ"

   [components]
   [[components.interactive]]
   ...
   runtime-module = "/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0"
   ...

   [wants]
   [[wants.module]]
   id = "/com.amazon.kepler.apslib@IApsDeviceParametersMap"

手順3：APIをアプリにインポートする

JavaScriptアプリに必要なデバイスパラメーターをインポートします。

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は非同期に動作し、awaitまたはthen()コンストラクトと使用できるPromiseを返します。成功すると、Promiseのペイロードとして、必須パラメーターとそれに対応する値のマッピングを含むApsDeviceParametersMapが返されます。エラーが発生した場合、Promiseは拒否され、エラーメッセージが表示されます。この関数では、アプリの読み込み時に呼び出し、戻り値をキャッシュすることが推奨されます。以下のコード例は、then()コンストラクトを使用して成功とエラーの両方のケースを処理する方法を示しています。この例では、C2S統合の代わりに、S2S統合でApsIntegrationType.c2sを渡すことを想定しています。次のコードサンプルは、then()コンストラクトを使用して成功ケースとエラーケースの両方を処理する方法を示しています。

const apsGetS2SWait = async (key: string) => {
console.debug(`[APS][${key}] apsGetS2SWaitを実行します`);
   ApsClientLibraryAPI.getDeviceParams(ApsIntegrationType.S2S).then((deviceParams: ApsDeviceParametersMap) => {
      console.debug(`[APS][${key}] S2S APSデバイス構成：${SCREEN_HEIGHT_DEVICE_PARAM}、値：${deviceParams.height}`);
      console.debug(`[APS][${key}] S2S APSデバイス構成：${SCREEN_WIDTH_DEVICE_PARAM}、値：${deviceParams.width}`);
      console.debug(`[APS][${key}] S2S APSデバイス構成：${DNT_DEVICE_PARAM}、値：${deviceParams.dnt}`);
      console.debug(`[APS][${key}] S2S APSデバイス構成：${IFA_DEVICE_PARAM}、値：${deviceParams.ifa}`);
      console.debug(`[APS][${key}] S2S APSデバイス構成：${UA_DEVICE_PARAM}、値：${deviceParams.ua}`);
      console.debug(`[APS][${key}] S2S APSデバイス構成：${MAKE_DEVICE_PARAM}、値：${deviceParams.make}`);
      console.debug(`[APS][${key}] S2S APSデバイス構成：${LANGUAGE_DEVICE_PARAM}、値：${deviceParams.language}`);
      console.debug(`[APS][${key}] S2S APSデバイス構成：${MODEL_DEVICE_PARAM}、値：${deviceParams.model}`);
      console.debug(`[APS][${key}] S2S APSデバイス構成：${OS_DEVICE_PARAM}、値：${deviceParams.os}`);
      console.debug(`[APS][${key}] S2S APSデバイス構成：${OSV_DEVICE_PARAM}、値：${deviceParams.osv}`);
   },
   function (error: Error) {
      console.error(`[APS][${key}] 失敗：構成を取得できませんでした：${error["message"]}`);
   }
);
}

手順4：必須パラメーターを確認する

デバイスパラメーターのほかに、サーバーに送信されたHTTPリクエストからIPを取得し、リクエストペイロードの一部として含める必要があります。詳細については、必須パラメーターの表を参照してください。

手順5：ペイロードを完成させる

HeaderBiddingリクエストのJSONペイロード作成を完了し、C2SまたはS2Sインテグレーションガイドを使用して残りのクラウドとのやり取りの後にHTTPSリクエストを作成します。

必須パラメーター

パラメーター	説明	IntegrationType: S2S	IntegrationType: C2S	このAPIにより提供
`h`	画面の物理的な高さ（ピクセル）	○	○	○
`w`	画面の物理的な幅（ピクセル）	○	○	○
`dnt`	ブラウザのヘッダーに設定される標準の「Do Not Track」フラグ。0 = トラッキングに制限なし、1 = トラッキング禁止。	○	○	○
`ifa`	デバイスの広告ID	○	○	○
`ua`	デバイスのユーザーエージェント（文字列）。	○	○	○
`make`	デバイスの製造元（Amazonなど）。	○	○	○
`language`	ISO-639-1-alpha-2で定義されるデバイスの言語。	○	○	○
`model`	デバイスのモデル（AFTTなど）。	○	○	○
`os`	デバイスのオペレーティングシステム（Androidなど）。	○	×	○
`osv`	デバイスのオペレーティングシステムのバージョン（5.1.1など）。	○	×	○
`ip`	デバイスに最も近いIPv4アドレス（パブリックIP）（204.78.58.34など）。	○	×	×（S2S向けの注：IPはサーバーに送信されたHTTPSリクエストから取得します）

インストールとセットアップ

アプリのビルド

この例では、mykeplerappという名前のアプリを使用しています。手順1：アプリの依存関係をインストールします。

npm install

手順2：.vpkgファイルを生成します。

npx react-native build-vega

パッケージのインストール

パッケージをインストールして実行します。

vda push ./kepler-build/vpkg/mykeplerapp_armv7.vpkg /tmp

アプリのインストールと起動

vda shell

vpm install /tmp/mykeplerapp.vpkg

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

APSストリーミングTV統合

Amazon Publisher Servicesでは、Vega TVプラットフォーム向けに2種類の統合方法を提供しています。これらの統合を利用して、パブリッシャーは入札リクエストを送信して広告ブレークインベントリーを埋めることができます。

C2S統合

パブリッシャーは、入札情報をパブリッシャーの広告サーバーにカスタムキー値として返すC2S呼び出しを使用します。この統合では、サーバー側の呼び出しはサポートされないため、Amazonのサーバーを呼び出すことができるのはアプリからに限られます。

APIプロトコル：HTTPS
エンドポイント：
推奨タイムアウト：1000ミリ秒

詳細については、C2S統合ガイドを参照してください。

S2S統合

パブリッシャーは、入札情報をパブリッシャーの広告サーバーに返すS2Sバックエンド呼び出しを使用して、APSキーと値のペアを取得します。クライアント側の呼び出しはサポートされないため、Amazonのサーバーを呼び出すことができるのは開発者のサーバーからに限られます。

APIプロトコル：HTTPS
エンドポイント：.
推奨タイムアウト：500ミリ秒

詳細については、S2S統合ガイドを参照してください。

​前提条件

​APSClientLibraryを始める

​手順1：パッケージの依存関係をアプリに追加する

​手順2：マニフェストファイルを更新する

​手順3：APIをアプリにインポートする

​手順4：必須パラメーターを確認する

​手順5：ペイロードを完成させる

​必須パラメーター

​インストールとセットアップ

​アプリのビルド

​パッケージのインストール

​アプリのインストールと起動

​APSストリーミングTV統合

​C2S統合

​S2S統合