スキルで使用するためにユーザーの連絡先情報をリクエストする



スキルで使用するためにユーザーの連絡先情報をリクエストする

ユーザーがAlexaスキルを有効にすると、スキルはユーザーに連絡先情報を使用する権限をリクエストできます。ユーザーが承諾すると、スキルで名前、Eメールアドレス、電話番号などの連絡先情報を使用できます。このデータを使用することで、アカウントリンクを行わずにパーソナライズされたインテントをサポートでき、ユーザーエクスペリエンスを改善することができます。たとえば、スキルはユーザーの連絡先情報を使用して近くのレストランを予約し、ユーザーに確認メッセージを送ることができます。

このドキュメントでは、この機能を有効化してAlexaユーザープロフィールAPIにユーザーの連絡先情報のクエリーを行う方法について説明します。

ユーザープロフィールAPIは、アクティブなデフォルトのAlexaプロフィールからの情報を使用します。このプロフィールはAlexaに話しかけている人を表している場合も表さない場合もあります。

ユーザー名、Eメールアドレス、電話番号といった情報項目をリクエストした時点でスキルが利用できない場合もあるため、スキルサービスコードで不足している情報を適切に処理する必要があります。

デバイスの住所情報をリクエストする方法の詳細は、所在地情報を使用してスキルを拡張するを参照してください。

アカウントリンクをユーザーの連絡先への権限で置き換える

ユーザー情報を取得して予約などの1回限りのユーザーリクエストを実行する、Eメールやテキストメッセージでユーザーに詳細情報を送信するといった処理にアカウントリンクを使用している場合、代わりにユーザーに連絡先情報へのアクセス権限をリクエストすることを検討してください。その方が操作がシームレスになり、管理も簡単になります。スキルがスロットを使ってユーザーのEメールアドレスや電話番号を収集している場合、代わりにユーザーの連絡先への権限を使うと、より正確で使いやすくなります。

始める前に

ユーザーのデータを保護するため、ユーザーの連絡先情報を使用するスキルはすべて、以下の要件を満たす必要があります。スキルが以下の要件のいずれかに違反しているとAmazonが判断した場合、スキル認定の申請を却下または保留にし、開発者アカウントに関連付けられたEメールアドレスに通知します。

  • スキルに適用するプライバシーポリシーへのリンクを開発者コンソールの公開ページに含める必要があります。
  • 子ども向けスキルは認められません。子ども向けスキルの詳細については、こちらを参照してください。
  • スキルで提供する機能やサービスをサポートするために必要な場合にのみ、ユーザーの連絡先情報を受け取る権限をリクエストする必要があります。リクエストする個人情報は、ユーザーの許可、プライバシー通知、適用される法令に従ってのみ利用するようにしてください。
  • 連絡先情報(名前、Eメールアドレス、電話番号)を使用して、バックグラウンドでユーザーのアカウントにリンクすることはできません。つまり、Alexaユーザーを同じ連絡先情報を持つアカウントプールのユーザーに関連付けることは認められません。ユーザーのAmazonアカウント情報は検証済みのものではなく、古い情報の可能性があります。
  • スキルは、ユーザーがスキルを呼び出すたびにAlexaユーザープロフィールAPIを使用して最新のユーザー情報を取得する必要があります。

ユーザーの連絡先情報をリクエストする方法

スキルでユーザーの連絡先情報をリクエストするには、以下の手順で行います。

  1. 開発者コンソールで、スキルがユーザーの連絡先情報を必要であることを表示するよう設定します。その結果、ユーザーがスキルを有効にすると、Alexaアプリで連絡先情報の提供に同意するよう、ユーザーにプロンプトが表示されます。ユーザーがスキルの有効化時にこれらの権限を付与しないことを選択した場合、情報が必要になったら、スキルの呼び出し中に権限カードからリクエストすることができます。ユーザーがこの情報へのアクセス権限の付与に同意しなかった場合にも、適切に処理できるようにする必要があります。
  2. ユーザーがスキルを呼び出すと、AlexaのLaunchRequestメッセージからapiAccessTokenを取得します。apiAccessTokenには期限があるため保存せず、代わりに後続の各リクエストから新たなトークンを取得します。
  3. ユーザーの連絡先情報を取得するの記載に従い、apiAccessTokenを含む正しいエンドポイントにリクエストしてください。

ユーザーの権限をリクエストするようスキルを設定する

開発者コンソールを使ってスキルを管理している場合、スキルを以下のように設定します。

  1. 開発者コンソールを使用してスキルを編集します
  2. コンソールのビルド>アクセス権限ページに移動します。

スキルに必要なユーザーリソースに応じて、以下のいずれか(1つまたは複数)を選択します。

  • ユーザー名 - 姓名または名前
  • ユーザーのEメールアドレス
  • 電話番号

SMAPIまたはASK CLIを使ってスキルを管理している場合、スキルマニフェストを編集して目的の権限をリクエストします。

APIアクセストークンを取得する

スキルに送信される各リクエストには、スキルに与える権限をカプセル化するAPIアクセストークン(apiAccessToken)が含まれています。このトークンを取得して、ユーザーの連絡先情報のリクエストに含める必要があります。

apiAccessTokenSystemオブジェクトに含まれ、Systemオブジェクトはcontextオブジェクトに含まれます。リクエストの本文全体を見るには、リクエストの形式を参照してください。

{
  "context": {
    "System": {
      "apiAccessToken": "AxThk...",
      "apiEndpoint": "https://api.amazonalexa.com",
	  ...
    }
  }
}

したがって、accessToken = this.event.context.System.apiAccessTokenとなります。

データをリクエストする場合、この形式の認可ヘッダーにアクセストークンを含めます。

Bearer < ACCESS_TOKEN >

< ACCESS_TOKEN >は、この例のようにAlexaリクエストメッセージのapiAccessTokenの値になります。

Authorization: Bearer AxThk...6fnLok

apiAccessTokenはスキルに対するすべてのリクエストに含まれます。これは、ユーザーがリクエストを完了するのに必要な権限をスキルに付与したかどうかは関係ありません。そのため、スキルがリクエストを完了するのに必要な正しい権限セットが、トークンに含まれていない可能性があります。スキルは特別な権限カードを表示して、ユーザーに動的に同意を求めることができます。

新しいカードAskForPermissionsConsentCard
インターフェースCardRenderer
定義{ "type": "AskForPermissionsConsent", "permissions": << list of scope strings >> }
アトリビュートpermissions:Alexaの権限にマッピングされるスコープ文字列のリストを含みます。スキルに必要で、かつ開発者コンソールのスキルメタデータで宣言されたAlexa権限のみを含めます。

apiAccessTokenはすべてのスキルリクエストに含まれるため、apiAccessTokenが存在するかどうかで必要な権限があるかを判断することはできません。代わりにAPIを呼び出して、応答コードを確認します。スキルに権限がない場合は403 Forbiddenの応答が返されるため、その時点でスキルのAlexaへの応答にAskForPermissionsConsentカードを含めることができます。ユーザーにカードの内容が通知され、ユーザーは権限を付与するかどうか判断します。

権限カードありの応答のサンプル

セッション内の対話で、新しいAskForPermissionsConsentカードを含む応答を返すことができます。

permissionsには、以下の表の値が含まれます。

姓名alexa::profile:name:read
名前alexa::profile:given_name:read
Eメールアドレスalexa::profile:email:read
電話番号alexa::profile:mobile_number:read

以下は、名前と電話番号をリクエストするカードの応答のサンプルです。

{
  "version": "1.0",
  "response": {
    "card": {
      "type": "AskForPermissionsConsent",
      "permissions": [
        "alexa::profile:name:read",
        "alexa::profile:mobile_number:read"
      ]
    }
  }
}

permissionsの値は、開発者コンソールのビルド>アクセス権限ページでスキルに対して宣言したスコープと常に同じになります。

スキルでSkillPermissionAcceptedイベントを使用する

スキルでSkillPermissionAcceptedイベントを使用すると、ユーザーがスキルに権限を付与したときに通知を受け取れます。

スキル作成時にAPIをテストする

開発者コンソールのテストページでは、一部のテストのみを実施できます。Alexaシミュレーターを使ってスキルをテストすると、スキルでAlexaユーザープロフィールAPIを呼び出して、独自の情報を含むエラーでない応答を受け取ることができます。ユーザーが権限を付与しなかった場合のフローをテストすることもできます。

ユーザーがスキルに権限を付与した場合のテストをするには、Alexaコンパニオンアプリでスキルに連絡先情報への権限を付与しておくようにしてください。スキルを開くと(「アレクサ、skill_nameを開いて」)、LaunchRequestが送信されます。権限が付与されていれば、リクエストからapiAccessTokenを取得できます。

ユーザーがスキルに権限を付与しなかった場合のテストをするには、Alexaコンパニオンアプリでスキルに連絡先情報への権限を付与していないことを確認してください。スキルを開くと(「アレクサ、skill_nameを開いて」)、LaunchRequestが送信されます。このリクエストにはapiAccessTokenの値が含まれますが、apiAccessTokenは正しい権限を指定していません。AlexaユーザープロフィールAPIにこのトークンを渡すと、403 Forbidden応答コードが返されます。

ユーザーがスキルを有効にすると、Alexaアプリでこのユーザーにリクエストされた権限付与に同意するようプロンプトが表示されます。スキルがこれらの権限を必要とする理由を、音声プロンプトで説明する必要があります。ユーザーが同意しない場合、スキルはAlexaアプリに(ユーザーが画面付きのAlexaが使えるデバイスを使用している場合はその画面に)権限カードを送信し、ユーザーにインテントで必要な権限付与に同意するようプロンプトを表示することができます。スキルのコードには、必要に応じて適切なフォールバックメッセージを含める必要があります。

一部の機能はリクエストした権限がなくても利用できるよう、スキルを作成することをおすすめします。ユーザーのリクエスト完了に必要な場合は、その都度ユーザーに権限付与のプロンプトを出す必要があります。

ユーザーに権限カードで権限付与プロンプトを出すサンプルメッセージ

「<ユーザーのリクエスト>を完了するには、skill_nameがEメールアドレスにアクセスする必要があります。Alexaアプリのホーム画面で、スキルに権限を付与してください。」

ユーザーの連絡先情報が利用できない場合のフォールバックメッセージ

スキルがユーザーの連絡先情報をリクエストしてユーザーが権限を付与しても、ユーザーがAlexaに電話番号を提供していないなどの場合はその情報を利用できません。リクエストしたユーザー情報が利用できない場合、204 No Content応答が返されます。

この状況で、何らかの情報がないとスキルがリクエストを完了できない場合、Amazonアカウントにこの情報を設定するようユーザーにプロンプトを出すことができます。

resource_nameが利用できない場合のサンプルメッセージ

「resource_nameが設定されていません。Amazonアカウントでこれらの詳細を入力してから、スキルをもう一度呼び出してください。」

ユーザーの連絡先情報が利用できない場合の推奨ベストプラクティス

ユーザーが連絡先情報を設定していない場合、適切な応答をスキル開発者が設定することができます。

この情報がないとスキルが機能できないことを表す適切なフォールバックメッセージを提供し、セッションを終了します。

代わりに、スキルは動作を続けるが、リクエストした情報がある場合に比べて実行できる機能が限定されることを表すメッセージを提供することもできます。

スキルを使いやすくするため、目的の情報を取得できなかった場合のすべてのシナリオを網羅したスキルワークフローを作成するようにしてください。

ベースURIとスキルの地域

AlexaユーザープロフィールAPIのエンドポイントはスキルの地域によって異なります。このJSONスニペットのように、正しいベースURLはSystemオブジェクトのapiEndpoint値(context.System.apiEndpoint)から取得できます。

{
  "version": "1.0",
  "session": {},
  "context": {
    "System": {
      "application": {
        "applicationId": "amzn1.ask.skill.<skill-id>"
      },
      "user": {},
      "apiAccessToken": "AxThk...",
      "apiEndpoint": "https://api.fe.amazonalexa.com/"
    }
  },
  "request": {}
}

このドキュメントの例では、日本のエンドポイント(api.fe.amazonalexa.com/)を使用しています。

複数言語用にスキルを設定する詳細については、多言語に対応するスキルを開発するを参照してください。

ユーザーの連絡先情報を取得する

以下のエンドポイントを使ってユーザーの連絡先情報を取得します(これらはリテラル文字列であることに注意してください)。エンドポイントでは大文字小文字が区別されます。

姓名/v2/accounts/~current/settings/Profile.name
名前/v2/accounts/~current/settings/Profile.givenName
Eメールアドレス/v2/accounts/~current/settings/Profile.email
電話番号/v2/accounts/~current/settings/Profile.mobileNumber

「~current」は、現在のユーザー(スキルを呼び出したアカウント)のuserIdを表します。

リクエストの例

Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer MQEWY...6fnLok
GET https://api.amazonalexa.com/v2/accounts/~current/settings/Profile.name
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer MQEWY...6fnLok
GET https://api.amazonalexa.com/v2/accounts/~current/settings/Profile.mobileNumber

リクエストヘッダー

ヘッダー 説明 必須
Authorization 次の形式での現在のアクセストークンです。 Bearer アクセストークン 文字列

応答の例

ヘッダー

Host: api.amazonalexa.com
X-Amzn-RequestId: xxxx-xxx-xxx
Content-Type: application/json

本文

{
  "countryCode" : "+1",
  "phoneNumber" : "999-999-9999"
}

以下は、戻り値の型のリストです(すべてのJSON値)。

姓名"文字列"
名前"文字列"
Eメールアドレス"文字列"
電話番号{ "countryCode": "文字列", "phoneNumber": "文字列" }

(モバイル)電話番号は、countryCodephoneNumberの組み合わせです。phoneNumberには追加でcountryCodeが含まれる場合があり、国内の電話番号のみであることは保証されません。phoneNumberの値は、それ自体でダイヤルできる有効な番号である必要があります。

このように、電話番号はさまざまな形式を持つ可能性があります。たとえば、+9177998277107799827710+91 7799 82 77 11+91 7799-82-77-11などです。国コードだけの場合、次のような形式が考えられます。+10011など。

応答ヘッダー

ヘッダー 説明
Content-Type application/json
X-Amzn-RequestId リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。

有効な応答

応答 説明
200 OK リクエストした情報が正常に取得されました。
204 No Content クエリーが値を返しませんでした。
401 Unauthorized 認証トークンの形式が正しくないか、無効です。
403 Unauthorized 認証トークンにリソースに対する権限がありません。
429 Too Many Requests リクエスト件数の超過によりスキルが制限されています。
500 Internal Error 予期しないエラーが発生しました。