DRS事前登録の実装

Warning: ここではLegacy APIについて記載しています。新しいAPIについてはこちらを参照してください。

DRS事前登録とは
概要
- 前提条件
- パッケージの変更: シリアル番号のバーコード
実装
API定義

DRS事前登録とは

Dash Replenishmentサービスは、ユーザーを喜ばせ、ショッピング体験の手間を解消することを目的としています。DRSを利用できるすべてのデバイスでは、消耗品（コーヒーポッド、洗剤、インクなど）がなくなる前に自動的に補充するよう選択できます。事前登録により、Amazonで買い物をするユーザーがDRSを利用できるデバイスをカートに追加するときにその選択ができるようにし、そのデバイスを受け取るときに一連のセットアップ操作を提供します。

概要

現在、ユーザーが初めてDRSを利用できるデバイスをセットアップするときに、自動的に再注文を行う商品を1つ以上選択してDash Replenishmentサービスをセットアップするかどうかも尋ねられます。この段階では、デバイスの製造元はそのデバイスのシリアル番号をユーザーのAmazonアカウントに関連付け、ストックがなくなる前に新しい補充品を受け取れるようにします。

お使いのソリューションで事前登録を連携すると、ユーザーがそのデバイスをAmazonで購入し、DRS機能をセットアップした段階ですぐにそのデバイスのシリアル番号を提供します。Amazonのレジ操作中に、ユーザーは自動的に再注文を行う商品を1つ以上選択できます。その設定はAmazonのクラウドに保存されます。

これにより、皆さまはユーザーが事前登録されたデバイスを箱から取り出して利用を開始する前にそのデバイスの許可トークンを直接交換し、ユーザーの利用開始手続きの簡略化とスピードアップを図ることができます。Amazonでの購入中に事前登録が行われなかったデバイスについては、利用開始手続きは初回セットアップ時（Login with Amazon、続けてASINを選択する）に完了します。

ユーザーがAmazonでDRSを利用できるデバイスを購入し、自動的に補充する消耗品を選択します。この設定はAmazon DRSのクラウドに保存されます。
商品がユーザーに発送される前に箱に記載されているデバイスのシリアル番号がスキャンされます。これにより、そのシリアル番号が記載されたSNS通知がデバイスの製造元に送信されます。
購入した商品を受け取ったユーザーがコンパニオンアプリを開き、[Dash Replenishment Service] オプションをクリックします。デバイスの製造元がAPI呼び出しを使用してそのデバイスのシリアル番号（DSN）が事前登録されていることを確認し、登録されている場合は商品の選択をスキップすることでユーザーの操作性を改善します。

前提条件

事前登録により利用開始手続きを簡略化するには、次の3つの前提条件があります。

箱のシリアル番号のバーコード - 箱にそのシリアル番号の1D（または2D）バーコードが印刷されている必要があります。
シリアル番号検証用の正規表現 - 品質管理のため、デバイスモデル検証用の正規表現をAmazonと共有することが推奨されます。これは新しいデバイスモデルがDash Replenishmentサービス（DRS）に追加されたときは必須です。
新しいトークン交換APIの採用 - ユーザーが購入の時点で既に再注文設定を選択していることを確認するには、そのデバイスのシリアル番号でLogin with Amazon APIに対するリクエストが行われている必要があります。

パッケージの変更: シリアル番号のバーコード

デバイスの製造元は、箱にそのデバイスのシリアル番号の情報が入った1D（または2D）バーコードが印刷されていることを確認する責任があります。品質管理のため、および箱の正しいバーコードがスキャンされるように、Amazonはスキャンの一環としてシリアル番号の検証を行います。検証は、デバイスの製造元から提供されたそのデバイスモデル/ASINに対応するシリアルの正規表現に基づきます。

製造元は、新しいデバイスモデルがDRSサービスで利用開始になるまでに、シリアルの正規表現とASINを提供することが要求されます。

実装

このソリューションを連携するには次の3つの手順を実行する必要があります。

バックエンドの実装: デバイスが事前登録されているかを識別し、デバイスの登録時にトークン交換のために新しいAPIを呼び出します。
フロントエンドの実装: 事前登録を処理するにはコンパニオンアプリの利用開始手続きのフローで部分的な変更が必要になります。
認証: Amazonはコンパニオンアプリとバックエンドの実装を認証し、フルフィルメントセンターのプロセスをテストする必要があります。

手順1 - バックエンドの実装

バックエンドアーキテクチャを設計する際には、次の2つのオプションを考慮します。

プル（推奨） - ユーザーがコンパニオンアプリを開き、購入したデバイスに接続すると、必須パラメーターを使用して事前登録エンドポイントへの呼び出しが開始する場合があります。200 OKのレスポンスを受け取った場合、これには他のDRS APIエンドポイントと通信するために必要とされる必須のアクセス権限と更新トークンが含まれます。
プッシュ - SNS通知を受け取ったときにアクセス権限と更新トークンを要求します。購入されたデバイスが発送されると、deviceRegisteredNotificationを介してそのデバイスの製造元に通知します。この段階で、事前登録エンドポイントが必須パラメーターを使用して呼び出される場合があります。200 OK レスポンスを受信すると、レスポンスにはDRS APIエンドポイントを呼び出すのに必要なアクセストークンとリフレッシュトークンが含まれます。このシナリオでは、ユーザーがしばらくの間そのデバイスに接続しない（配送されたデバイスがネットワークに接続されない）場合があり、その場合はアクセストークンの有効期限が切れるため更新する必要があることを意味します。

Amazonはオプション1を実装することを強く推奨します。これにより、障害が発生したときやSNS通知を見落としたときにカスタマーエクスペリエンスが悪化するリスクを減らすことができます。

アクセストークン交換APIの呼び出し

AmazonはDash Replenishmentサービスによるaccess_tokenの交換を有効にするAPIへのアクセス権限を製造元に付与します。これにより、ユーザーがLogin with Amazonを確認する手間をなくし、手間を解消します。

デバイスの製造元はそのデバイスに接続し、シリアル番号やデバイスモデルなどのデバイスの詳細を抽出するビジネスロジックを管理します。

リクエストが行われると、Amazonのシステムは次の操作を行います。

API呼び出しを実行するクライアントを認証および許可する。
リクエストにあるデバイスがAmazonシステム内でユーザーによって構成されていることを検証する。
ユーザーがDash Replenishmentにサインアップしていることを確認する。小売のチェックアウトフローとフルフィルメントセンターのバーコードスキャンフローは、このAPIを使用したトークン交換が成功するための前提条件です。いずれかのワークフローがスキップされた/失敗した/完了しなかった場合、このAPIは有効な更新トークンをクライアントに返しません。

これを達成する方法の例については、API定義セクションをご覧ください。

SNS通知の受信

DRSに事前登録されたデバイスが発送されると、AmazonはSNSを使用してdeviceRegisteredNotificationを製造元に送信します。この通知には事前登録されたデバイスのシリアル番号が含まれています。SNS通知を受信するには、SNSトピックの作成のドキュメントに従ってインフラストラクチャをセットアップする必要があります。

SNS通知（以下を参照）内のserialNumberフィールドは、箱に印刷されているそのデバイスのシリアル番号（DSN）に設定されます。

デバイスメーカーはデバイスモデルやシリアル番号のような詳細を、メーカーのデータベースに登録することができます。また、必要に応じて登録されたSNS通知を保存します。

事前登録の通知の例を次に示します。

{
    "notificationInfo": {
        "notificationType": "DeviceRegisteredNotification",
        "lwaClientId": "amzn1.application-oa2-client.6b68exxxxxxxxxx9",
        "notificationTime": "2015-10-01T02:23:52.747Z",
        "notificationId": "amzn1.dash.notification.v1.xxxxxxxxxxxxx13",
        "version": "2015-06-05"
    },
    "deviceInfo": {
        "deviceIdentifier": {
            "serialNumber": "DeviceSerialNumber"
        },
        "productIdentifier": {
            "modelId": "myDeviceModel"
        }
    },
    "customerInfo": {
        "directedCustomerId": "amzn1.account.AHxxxxxxxxGA2O5Q"
    }
}

手順2 - フロントエンドの実装

この手順では、既にお使いのコンパニオンアプリにDRSを組み込む手順に関するガイド（iOS、Android、Webサイト（Web））に従っていることを前提としています。

事前登録の利点を活用するには、ユーザーがアプリ内のDRSティザーページを確認する前に、事前登録API呼び出しを追加する必要があります。

Pseudoコードでは、次のようになります。

verifyPreRegistration(parameters, callbackFunction)

callbackFunction(response){
  if (response.code == 200){
    // 事前登録が成功しました。access_token, refresh_token および expires_in をサーバーにSSLを用いて保存してください。
    save(response.data)
    skipDRSTeaserPage()
  }else{
    // 事前登録対象のデバイスではないと判断し、通常のDRSフローに移行します。
    openDRSTeaserPage()
  }
}

手順3 - 認定

サーバーとコンパニオンアプリに事前登録を実装した後は、QAチームが事前認定を実行してその実装を検証する必要があります。

事前登録の最後に、更新されたコンパニオンアプリを提出してAmazonによる正式な認定を受けることができます。このプロセスを完了する方法については、Amazonの担当者にお問い合わせください。

API定義

APIは細部を除いて変更されない予定です。細部変更が発生した場合は、DRS事前登録が稼働する前にお知らせします。

実稼働エンドポイント

api.amazon.com/auth/o2/token

実稼働前エンドポイント

api-preprod.amazon.com/auth/O2/token

HTTP Headerパラメーター

Content-Type:application/x-www-form-urlencoded

または

Content-Type:application/json

HTTP Bodyパラメーター

client_id:DRSで利用開始手続きを行ったクラウドアプリケーションのLWAクライアントID。
client_secret:DRSで利用開始手続きを行ったクラウドアプリケーションのLWAクライアントシークレット。
grant_type:「device_preregistration」
scope:文字列dash:replenish。標準のLWAフローの場合に「scope」として渡す同じスコープです。
scope_data:次のフィールドが含まれるJSONオブジェクト。
- "device_serial_number":デバイスのシリアル識別子。箱に印刷されているバーコードと一致する同じ識別子です。
- "device_model":デバイスのモデル識別子。標準のLWAフローの場合に「deviceModel」フィールドとして渡す同じ識別子です。

HTTPレスポンス

標準のLWAフローであった場合は、/auth/o2/tokenエンドポイントから受け取ったであろう同じデータが含まれるJSONオブジェクト。
- "access_token":ユーザーのデバイスとアカウント用のアクセストークン。
- "token_type":返されたトークンの種類。「bearer」である必要があります。
- "expires_in":アクセストークンが無効になるまでの秒数。
- "refresh_token":新しいアクセストークンのリクエストに使用できる更新トークン。

例

リクエストの例:application/json

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/json

{
  "grant_type": "device_preregistration",
  "client_id":"foodev",
  "client_secret":"Y76SDl2F",
  "scope":"dash:replenish",
  "scope_data":{
    "product_instance_attributes": {
      "device_serial_number": "<deviceSerialNumber>",
      "device_model": "<deviceModel>"
    }
  }
}

リクエストの例:application/x-www-form-urlencoded

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded

grant_type=device_preregistration&client_id=foodev&client_secret=Y76SDl2F&scope=dash%3Areplenish&scope_data=%7B%22product_instance_attributes%22%3A+%7B%22device_serial_number%22%3A+%22%3CdeviceSerialNumber%3E%22%2C%22device_model%22%3A+%22%3CdeviceModel%3E%22%7D%7D

レスポンスの例

{
   "access_token": "Atza|IQEBLjAsAhQ3yD47Jkj09BfU_qgNk4",
   "expires_in": 3600,
   "refresh_token": "Atzr|IQEBLzAtAhUAibmh-1N0EVztZJofMx",
   "token_type": "bearer"
}

エラーレスポンス

エラー	説明	レスポンス
DeviceSerialNumberが事前登録されていない	入力のdevice_modelは利用開始になっていますが、device_serial_numberが事前登録されませんでした。これは、device_serial_numberがAmazonで販売していなかったか、ユーザーが事前登録をスキップしたことが原因の可能性があります。	HTTP/1.1 400 Bad Request
デバイスモデルが利用開始になっていない	入力のdevice_modelがDRSサービスで利用開始になっていません。	HTTP/1.1 400 Bad Request
デバイスモデルが別の資格情報で利用開始になっている	LWAの資格情報がdevice_modelの利用開始手続きに使用されたセキュリティプロファイルに属していません。	HTTP/1.1 400 Bad Request

ホワイトリストに登録されたデバイス

device_model:TEST_MODEL_DRS_PREREG_01
device_serial_number:TEST_SERIAL_01またはTEST_SERIAL_02

リクエストにホワイトリストに登録されたデバイスを有効なクライアントの資格情報と共に使用すると、リクエストが成功します。有効なトークンが返されますが、そのトークンは後続の補充呼び出しには使用できません。

Last updated: Aug 07, 2018