@amazon-devices/kepler-aps-client

Vega APSクライアントAPIは、Vega向けReact NativeアプリとAmazon Publisher Services（APS）のネイティブコード実装の連係を可能にするブリッジです。このAPIには、入札リクエストに必要なパラメーターを取得するためのgetDeviceParams()メソッドが用意されています。これらのパラメーターをC2S（クライアントからサーバー）またはS2S（サーバー間）統合経由でAPSに送信し、リクエストを完了します。このユーザーガイドでは、APSクライアントライブラリのインストール方法とAPIの使用方法について説明します。Amazon Publisher Servicesの概要については、Amazon Publisher Servicesを参照してください。

前提条件

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

APSClientLibraryの使用を始める

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

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

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

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

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

components.interactiveには、React Nativeのバージョンに応じた適切なruntime-moduleを含める必要があります。
wants.moduleには、id = "/com.amazon.kepler.apslib@IApsDeviceParametersMap"を含める必要があります。
wants.serviceにはid = "com.amazon.admanager.service.main"を含める必要があります。これはdntパラメーターとifaパラメーターで必要です。

サンプルアプリのmanifest.tomlの例を以下に示します。

React Native 0.72
React Native 0.83

[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"

[[wants.service]]
id = "com.amazon.admanager.service.main"  

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

[components]
[[components.interactive]]
...
runtime-module = "/com.amazon.kepler.runtime.react_native_kepler_4@IReactNativeKepler_0"
...

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

[[wants.service]]
id = "com.amazon.admanager.service.main"  

手順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を取得し、リクエストペイロードの一部として含める必要があります。詳細については、「必須パラメーター」の表を参照してください。

必須パラメーター

パラメーター	説明	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リクエストから取得します）

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

HeaderBiddingリクエストのJSONペイロードの作成を完了し、C2SまたはS2Sの統合ガイドに従って、残りのクラウドとのやり取りの後に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

APIリファレンス

クラス

ApsClientLibraryAPI
ApsError - 一般的なAPSのエラー
InternalError - 回復不可能／不明な任意のシステムエラー
NotFoundError - 取得されたパラメーターがnullの場合のエラー
UnsupportedError - サポート対象外の統合の型を渡した際のエラー

インターフェイス

AmazonAPSClientTurboModule

列挙型

ApsIntegrationType - AmazonがAPS統合用にパブリッシャーに提供している型。

型エイリアス

関数

parseError

変数

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 - 返されたデバイスパラメーターのキー。
SCREEN_WIDTH_DEVICE_PARAM
UA_DEVICE_PARAM

​前提条件

​APSClientLibraryの使用を始める

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

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

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

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

​必須パラメーター

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

​アプリのビルドとインストール

​アプリのビルド

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

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

​APIリファレンス

​クラス

​インターフェイス

​列挙型

​型エイリアス

​関数

​変数