アプリ間アカウントリンク(開発者のアプリから開始する場合)


アプリ間アカウントリンク(開発者のアプリから開始する場合)

このアカウントリンクフローを使用すると、ユーザーはアプリやウェブサイトから、AlexaユーザーIDと別のサービスでのIDをリンクできるようになります。アプリからアカウントリンクフローを開始すると、ユーザーは以下のことができます。

  • アプリからAlexaスキルを検索できます。
  • アプリからスキルを有効化し、アカウントをリンクできます
  • モバイルデバイスでアプリとAlexaアプリの両方にログインしている場合、どちらのアプリにもアカウント認証情報を入力せずにアカウントをリンクできます。
  • モバイルデバイスにAlexaアプリをインストールしていない場合、アプリからLogin with Amazon(LWA)を使ってアカウントをリンクできます。

次の方法でも、アカウントリンクフローを実装することができます。

アプリやウェブサイトをお持ちの場合は、Alexaアプリのみのフローに加えて、いずれかのアプリ間アカウントリンクフローの実装をお勧めします。

これ以降に出現するアプリ間アカウントリンクという用語は、開発者のアプリから開始されたアプリ間アカウントリンクを指します。

トラブルシューティングに関する情報については、アプリ間アカウントリンク(開発者のアプリから開始する場合)のトラブルシューティングを参照してください。

用語

このトピックでは、以下の用語を使用します。

  • サービス - 開発者が提供するサービスです。たとえば、ユーザーがタクシーを手配できる、ウェブベースの「タクシー予約」サービスなどがあります。
  • アプリ - ユーザーがサービスの操作に使用するアプリです。先ほどの例であれば、「タクシー予約」アプリなどです。ここでは、読者がアプリの開発者だと想定します。
  • スキル - ユーザーがAlexaでサービスを操作するために使用するAlexaスキルです。ここでは、読者がスキルの開発者だと想定します。
  • Alexaアプリ - ユーザーがモバイルデバイスにダウンロードして使用できるAmazon Alexaアプリです。
  • Login with Amazon(LWA) - ユーザーがログインして、自身のユーザープロファイルデータへのアクセス権限を付与できる認証システムです。アプリ間アカウントリンクの場合、LWAは、ユーザーがモバイルデバイスにAlexaアプリをインストールしていない場合に備えて実装する予備システム(フォールバック)です。LWA全般については、Login with Amazonに関するドキュメントを参照してください。
  • OAuth 2.0 - ユーザーが以前に設定したアカウントから、ユーザーの権限を使ってAlexaが情報にアクセスできるようにする認証の標準です。OAuth 2.0標準については、OAuth 2.0を参照してください。
  • アプリリンク - ユーザーがアプリを起動するためにクリックするAndroidのディープリンクです。アプリリンクの詳細については、Androidのドキュメントを参照してください。
  • ユニバーサルリンク - ユーザーがアプリを起動するためにクリックするiOSのディープリンクです。ユニバーサルリンクの詳細については、iOSのドキュメントを参照してください。

ユーザーの操作

ユーザーは以下のワークフローに従って、アプリ間アカウントリンクを有効にします。

  • スキルを有効にし、アカウントをAlexaにリンクするためのオプションがアプリに表示されます。ユーザーがアカウントのリンクを選択します。モバイルデバイスにAlexaアプリがインストールされているかどうかによって、以下のいずれかのフローが適用されます。
  • (Alexaアプリのフロー)モバイルデバイスにAlexaアプリがインストールされている場合は、Alexaアプリが起動し、ユーザーに対してアカウントリンクリクエストへの同意を求めます。ユーザーがリクエストに同意すると、アプリにリダイレクトされます。
  • (LWAのフロー)モバイルデバイスにAlexaアプリがインストールされていない場合、アプリ内のブラウザウィンドウにLWAが表示されます。ユーザーはAmazonの認証情報を入力するか、Amazonアカウントを作成します。次にユーザーは、スキルにアカウントをリンクする権限を付与するように求められます。ユーザーがリクエストに同意すると、アプリにリダイレクトされます。

アカウントをリンクした後、ユーザーがスキルを使用するワークフローは、Alexaアプリのみのアカウントリンクと同じです。いずれの場合も、スキルを無効にすると、アカウントリンクが解除されます。

以下は、アプリ間アカウントリンクのスクリーンショットの例です。前述のように、フローはユーザーがAlexaアプリをインストールしているかどうかによって決まります。

Alexaアプリがインストールされている場合

以下はAlexaアプリのフローの例です。

Alexaアプリ間アカウントリンク

Alexaアプリがインストールされていない場合

以下はLWAのフローの例です。

Login with Amazonを使用したAlexaアプリ間アカウントリンク

実装するフローの選択

AlexaアプリのフローはiOSとAndroidで実装できます。したがって、実装するフローは、開発しているアプリ(iOSアプリ、Androidアプリ、ウェブサイト)によって異なります。

  • iOSアプリとAndroidアプリ - Alexaアプリのフローをメインのフローとして実装し、Alexaアプリがインストールされていない場合のフォールバックとしてLWAのフローを実装します。
  • ウェブサイト - LWAのフローを実装します。

しくみ

アプリ間アカウントリンクはOAuth 2.0に基づいて機能します。以下の図では、ユーザーがモバイルデバイスのアプリからアカウントリンクを開始した場合の処理の流れを示します(クリックで拡大します)。

Alexaアプリ間アカウントリンクフロー

処理の流れは以下のとおりです。各URLについては、URLとエンドポイントを参照してください。

  1. ユーザーがモバイルデバイスにアプリをインストールして、ログインします。
  2. アプリ画面に、スキルを有効にし、ユーザーのアカウントをAlexaにリンクするオプションが、そのメリット(「Alexaから音声で『タクシー予約』の配車を手配できます」など)とともに表示されます。ユーザーがリンクのリクエストに同意します。
  3. 次のステップは、ユーザーのデバイスにAlexaアプリがインストールされているかどうかによって、以下の2つに分かれます。
    • Alexaアプリがインストールされている場合:
      1. アプリが、AlexaアプリのURLと認可リクエストパラメーター後ほど説明します)を使ってAlexaアプリを起動します。
      2. Alexaアプリが起動し、ユーザーに対してAlexaをサービスにリンクするかをたずねる画面が表示されます。
      3. ユーザーがリンクのリクエストに同意します。
      4. Alexaアプリが、ユーザーのリダイレクト先のURLを使ってユーザーをアプリに戻します。このリダイレクトでは、ユーザーのAmazon認可コードも送信されます。
    • Alexaアプリがインストールされていない場合:
      1. アプリがLWAフォールバックURLと認可リクエストパラメーター後ほど説明します)を使って、(ネイティブのブラウザアプリではなく)アプリ内ブラウザタブでLWAを起動します。
      2. LWAが起動し、ユーザーにAmazonアカウントへのログインを求めます。
      3. LWAに、ユーザーに対してAlexaをサービスにリンクするかをたずねる画面が表示されます。ユーザーがリンクのリクエストに同意します。
      4. LWAが、ユーザーのリダイレクト先のURLを使ってユーザーをアプリに戻します。このリダイレクトでは、ユーザーのAmazon認可コードも送信されます。
  4. バックエンドサーバーがLWA認可サービスのURLを呼び出し、前のステップで取得したAmazon認可コードをAmazonアクセストークンと交換します。
  5. バックエンドサーバーが認可サーバーを呼び出し、ユーザーの認可コード(サービスでユーザーが保有するアカウントの認可コード)を取得します。
  6. バックエンドサーバーが、ユーザーのAmazonアクセストークンおよびサービスでのユーザーの認可コードを使ってAlexaスキル有効化APIを呼び出し、スキルの有効化とアカウントのリンクを行います。
  7. AlexaがアプリのアクセストークンのURLを呼び出し、サービスに対するユーザーの認可コードをサービスでのアクセストークンと交換します。これでアカウントリンクの処理は完了です。

URLとエンドポイント

このセクションでは、アプリ間アカウントリンク関連のURLとエンドポイントについて説明します。パラメーターの説明がその後に続きます。

名前 用途 詳細

AlexaアプリのURL

リンクリクエストへの同意を得るために、ユーザーをAlexaアプリにリダイレクトするユニバーサルリンク(iOS)またはアプリリンク(Android)です。パラメーターの詳細については、AlexaアプリのURLとLWAフォールバックURLのパラメーターを参照してください。ユニバーサルリンク全般については、AppleによるAllowing Apps and Websites to Link to Your Contentのドキュメントを参照してください。

AlexaアプリのURLとLWAフォールバックURLは、バックエンドに保存してGETリクエストで取得できます。またこれらのURLをローカルに保存しておけば、余分のネットワーク呼び出しを回避できます。ただし、今後、スキルのセキュリティプロファイルを変更する際には、新しいビルドが必要になる可能性があります。

形式: https://alexa.amazon.com/spa/skill-account-linking-consent?fragment=skill-account-linking-consent&client_id={ClientId}&scope=alexa::skills:account_linking&skill_stage={skillStage}&response_type=code&redirect_uri={yourRedirectUrl}&state={yourState}

例: https://alexa.amazon.com/spa/skill-account-linking-consent?fragment=skill-account-linking-consent&client_id=amzn1.application-oa-client-1&scope=alexa::skills:account_linking&skill_stage=development&response_type=code&redirect_uri=https://yourAppRedirectUri&state=aGVsbG8

LWAフォールバックURL

Amazon認証情報の入力を求めるため、ユーザーをLWAに送信するリンクです。iOS、Android、ウェブサイトのいずれにも使用できます。ユーザーのデバイスにAlexaアプリがインストールされていない場合に、このリンクを使用します。パラメーターの詳細については、AlexaアプリのURLとLWAフォールバックURLのパラメーターを参照してください。

URLの保存については、前述のAlexaアプリのURLに関する説明を参照してください。

形式:https://www.amazon.com/ap/oa?client_id={ClientId}&scope=alexa::skills:account_linking&response_type=code&redirect_uri={yourRedirectUrl}&state={yourState}

例: https://www.amazon.com/ap/oa?client_id=amzn1.application-oa-client-1&scope=alexa::skills:account_linking&response_type=code&redirect_uri=https://yourAppRedirectUri&state=aGVsbG8

アプリのリダイレクト先のURL

ユーザーがAlexaアプリまたはLWAでリンクリクエストに同意した後、Alexaアプリ(Alexaアプリがインストールされていない場合は、LWA)がユーザーをアプリに戻すためのユニバーサルリンクまたはアプリリンクです。アプリは、このリダイレクトで返されるパラメーターから、ユーザーのAmazon認可コードを取得します。このコードの有効期限は5分間です。

Alexa開発者コンソール、ASK CLI、またはSMAPIを使用して、このようなURLを1つ以上指定します。必須の構文については、URI specificationを参照してください。

認証画面のURL

認可サーバーのURLです。認可サーバーはユーザーの認証情報を受け付け、ユーザーを認証し、認可コードを生成する必要があります。その後、Alexaアプリは、生成された認可コードを認可サーバーに渡し、サービスでユーザーを一意に識別するアクセストークンを取得します。

このリンクは、通常の(アプリ間ではない)アカウントリンクにのみ使用されます。開発者コンソール、ASK CLI、またはSMAPIを使用して指定します。

アクセストークンのURL

Alexaが、ユーザーに対するサービスの認可コードをアクセストークンと交換するトークンサーバーです。これで、アカウントリンクが完了します。

開発者コンソール、ASK CLI、またはSMAPIを使用して指定します。

LWA認可サービス

このリンクは、バックエンドサーバーが、ユーザーのAmazon認可コードをAmazonアクセストークンと交換するために使用します。アプリはAlexaサービスを呼び出したうえで、このアクセストークンを使ってユーザーにスキルを有効化し、アカウントをリンクします。

Host: https://api.amazon.com、POSTリクエストの送信先は/auth/o2/token

Alexaスキル有効化APIのエンドポイント

このエンドポイントは、バックエンドサーバーが、ユーザーに対してスキルを有効にするために呼び出します。Alexaスキル有効化APIの詳細については、Alexaスキル有効化APIを参照してください。

形式: https://api.amazonalexa.com/v1/users/~current/skills/{yourSkillId}/enablement

ユーザーの所在地に応じて、ベースURLはhttps://api.amazonalexa.comhttps://api.eu.amazonalexa.comhttps://api.fe.amazonalexa.comのいずれかです。

AlexaアプリのURLとLWAフォールバックURLのパラメーター

フィールド 説明

Client ID

開発者コンソールでアプリ間アカウントリンクを有効にするときに、Alexa開発者コンソールで提供されるAlexaクライアントIDです。

Client secret

開発者コンソールでアプリ間アカウントリンクを有効にするときに、開発者コンソールで提供されるAlexaクライアントシークレットです。

Redirect URL

開発者コンソールでアプリ間アカウントリンクを有効にするときに指定するユニバーサルリンクまたはアプリリンクです。ユーザーがアカウントリンクリクエストに同意すると、AlexaアプリとLWAがユーザーをこのURLに戻します。

Scope

アプリがスキルを有効にする権限を得るには、このフィールドをalexa::skills:account_linkingに設定する必要があります。

Skill ID

一意のスキルIDです。この情報は開発者コンソールで確認できます。

Stage

スキルのステージです。スキルが公開されているかどうかを表します。スキルを公開するまでは、stagedevelopmentに設定します。スキルの公開時にliveに変更します。

response type

応答タイプはcodeに設定する必要があります。アプリ間アカウントリンクは現在、Authorization code grantにのみ対応しているためです。

state

現在のリクエストと応答の間のステートを管理するために使用するopaqueな値です。AlexaアプリのURLには、ステート値が必須です。Alexaは、ユーザーのリダイレクト先のURLを使ってユーザーをアプリに戻すとき、このステートをそのまま応答に入れて返送します。リクエスト強要(CSRF)を防ぐには、ステートを使用してリクエストを検証する必要があります。

生成したステートに、&=/\<>#|が含まれていないことを確認します。base64 URIを使用すると、確実です。実装例については、ステップ4: ユーザーのAmazon認可コードを取得するのステートヘルパーコード例を参照してください。

セキュアな乱数ジェネレーターを使用してステートを生成し、セッションに保存して検証することができます。またはバックエンドサーバーでステートを生成し、キーを使用して暗号化と復号化を行うことも可能です。

主な手順

このセクションでは、主な手順を説明し、以下のライブラリと言語を使用したiOSアプリ(10.0以降)およびAndroidアプリのコード例を紹介します。

以下の図では、主な手順を示します。図に続いて手順を説明し、コード例を示します。

Alexaアプリ間アカウントリンクの手順

クリックすると、各ステップにジャンプします。 1  2  3  4  5  6  7  8

ステップ1: アプリのアカウントリンクオプションを表示する

アプリには、ユーザーがスキル有効化とアカウントリンクを開始できる画面が必要です。このページには、ユーザーが自分のアカウントとAlexaをリンクして実現できる機能を表示します。たとえば、音声でタクシーの手配ができるなどです。

ステップ2: アプリのユニバーサルリンク(iOS)またはアプリリンク(Android)を有効にする

Alexaアプリがアプリにユーザーをリダイレクトできるように、ユニバーサルリンク(iOSアプリの場合)またはアプリリンク(Androidアプリの場合)を有効にする必要があります。

ステップ3: スキルでアプリ間アカウントリンクを使用するためのコンフィギュレーションを行う

開発者コンソールAlexa Skills Kitコマンドラインインターフェース(ASK CLI)、またはAlexaスキル管理API(SMAPI)を使用してスキルの設定を行います。このコンフィギュレーションでは、アプリのリダイレクト先のURL、アクセストークンのURLなどを指定します。

ステップ4: ユーザーのAmazon認可コードを取得する

アプリは、ユーザーのAmazon認可コードを取得する必要があります。認可コードは後でAmazonアクセストークンと交換できます。Amazonアクセストークンがあれば、アプリがスキルを有効にし、アカウントリンクを完了できます。Amazon認可コードの有効期限は5分間です。

iOSの例

Androidの例

ステートの生成と検証

ステップ5: Amazon認可コードをAmazonアクセストークンと交換する

ユーザーのAmazon認可コードを取得したら、それを使ってAmazonアクセストークンを取得する必要があります。Alexaサービスを呼び出してスキルを有効にし、アカウントリンクを完了するには、アクセストークンが必要です。

ステップ6: スキルを有効にしてアカウントリンクを完了する

ユーザーのAmazonアクセストークンを取得したら、バックエンドサーバーがAlexaスキル有効化APIを呼び出してスキルを有効にし、アカウントリンクを完了することができます。

ステップ7: アカウントリンクのステータスをアプリに表示する

アカウントリンクのステータスをアプリに表示して、ユーザーに知らせることができます。ユーザーの操作エラーのスクリーンショットを参考にしてください。

ステップ8: スキルでアクセストークンを使用する

ユーザーがスキルを有効にしてAlexaをサービスにリンクすると、スキルに送信されるリクエストにユーザーのアクセストークンが含まれるようになります。スキルコードは、リクエストからアクセストークンを取得して検証し、それを使ってリソースサーバーから必要なユーザー情報を取得する必要があります。

エラー

このセクションでは、アカウントリンクやスキル有効化が失敗したときに発生するエラーについて説明します。エラーが発生すると、アプリにエラーメッセージが表示されます。以下の図に一例を示します。このセクションでは、他のエラーメッセージについても説明します。

Alexaアプリ間アカウントリンクのエラー

エラーの説明

このセクションでは、アプリ間アカウントリンクの接続時にユーザーが遭遇する可能性のあるエラーについて説明します。アプリは、アカウントリンクが失敗したことをユーザーに通知し、エラーメッセージを示す必要があります。このセクションでは、エラーメッセージおよび考えられる原因について説明します。良質のユーザーエクスペリエンスを提供するため、ここで示すエラーメッセージを使用することをお勧めします。

アプリ間アカウントリンクのフローで、Alexaからアプリへのエラーが発生する可能性があるのは以下の3つの時点です。

Amazon認可コード取得時のエラー

アプリがAmazon認可コードの取得を試みたときにエラーが発生した場合、Alexaアプリがアプリへのユーザーのリダイレクト先として使用するredirect_uriに、OAuth 2.0仕様の説明に従ってエラークエリーパラメーターが格納されます。AlexaアプリとLWAフォールバックはどちらもOAuth 2.0仕様に準拠しているので、同じエラーコードがアプリに返されます。Amazon認可コードを取得するリクエストが失敗した理由については、error_descriptionクエリパラメーターを確認し、返されたエラーコードについてOAuth 2.0仕様の説明を参照してください。

エラーコード ユーザーに表示するメッセージ 考えられる原因

invalid_request

Alexaに接続してアカウントをリンクする際に問題が発生しました。後でもう一度試してください。

リクエストで、statescoperesponse_typeのいずれかが指定されていません。

unauthorized_client

Alexaに接続してアカウントをリンクする際に問題が発生しました。後でもう一度試してください。

指定したclient_idには、ユーザーにアカウントリンクの同意を求めるアクセス権がありません。

access_denied

ありません(アクセスを拒否しているのはユーザーの方なので、ユーザーにはエラーメッセージが表示されません)。

ユーザーが自分のアカウントリンクのリクエストを拒否しました。

unsupported_response_type

Alexaに接続してアカウントをリンクする際に問題が発生しました。後でもう一度試してください。

パラメーターresponse_typecodeと一致しません。

invalid_scope

Alexaに接続してアカウントをリンクする際に問題が発生しました。後でもう一度試してください。

scopeパラメーターが無効です。

server_error

アカウントリンクの接続中に、Alexaで予期しないエラーが発生しました。後でもう一度試してください。

予期しないサーバーエラー。

temporarily_unavailable

アカウントリンクの接続中に、Alexaで一時的なエラーが発生しました。後でもう一度試してください。

一時的なサーバーエラー。

Amazon認可コードとAmazonアクセストークンの交換時のエラー

Amazon認可コードをAmazonアクセストークンと交換する際にエラーが発生した場合、OAuth 2.0仕様の説明に従って、Amazonトークン・サーバーが ”400Bad Request” ステータスコードを返し、ボディのJSON応答にエラーパラメーターが含まれます。Amazonアクセストークンを取得するリクエストが失敗した理由については、JSON応答のerror_descriptionパラメーターを確認し、返されたエラーコードについてOAuth 2.0仕様の説明を参照してください。

エラーコード ユーザーに表示するメッセージ 考えられる原因

invalid_request

Alexaに接続してアカウントをリンクする際に問題が発生しました。後でもう一度試してください。

client_idclient_secretgrant_typecodeのいずれかが指定されていません。

invalid_client

Alexaに接続してアカウントをリンクする際に問題が発生しました。後でもう一度試してください。

client_idまたはclient_secretが無効です。

invalid_grant

Alexaに接続してアカウントをリンクする際に問題が発生しました。後でもう一度試してください。

リクエストのcode(Amazon認可コード)が無効です。

unauthorized_client

Alexaに接続してアカウントをリンクする際に問題が発生しました。後でもう一度試してください。

指定したclient_idには、ユーザーのアカウントをリンクすることについて同意を求める権限がありません。

unsupported_grant_type

Alexaに接続してアカウントをリンクする際に問題が発生しました。後でもう一度試してください。

リクエストのgrant_typeauthorization_codeではありません。

Alexaスキル有効化APIの呼び出し時のエラー

アプリがAlexaスキル有効化APIを呼び出してユーザーのアカウントを有効にし、リンクしようとしてエラーが発生した場合、APIはリクエストが失敗した理由を示すステータスコードを返します。それ以外の場合、APIはHTTP 2XXステータスコードで応答します。スキル有効化リクエストが失敗した理由については、JSON応答のmessageパラメーターを確認してください。

HTTPステータスコード: ユーザーに表示するメッセージ 考えられる原因

400 Bad Request

Alexaに接続してアカウントをリンクする際に問題が発生しました。後でもう一度試してください。

  • skill_idstageaccountLinkingRequest.authCodeaccountLinkingRequest.redirectUriaccountLinkingRequest.Typeのいずれかが指定されていません。
  • アプリのアクセストークンと更新トークンのペアをリクエスト中に、エラーが発生しました。

403 Forbidden

Alexaに接続してアカウントをリンクする際に問題が発生しました。後でもう一度試してください。

  • Amazonアクセストークンが無効です。
  • Amazonアクセストークンに、スキルの有効化についてのユーザーの同意が含まれていません。
  • Amazonアクセストークンが、リクエストで指定されたskill_idに属していません。
  • ユーザーには、リクエストで指定されたskill_idのスキルを有効にする権限がありません。

404 Not Found

Alexaに接続してアカウントをリンクする際に問題が発生しました。後でもう一度試してください。

  • skill_idまたはstageが無効です。

500 Server Error

アカウントリンクの接続中に、Alexaで予期しないエラーが発生しました。後でもう一度試してください。

  • 予期しないサーバーエラー。
  • アカウントをアプリのOAuthサーバーにリンク中に問題が発生しました。

ベストプラクティス

アプリ間アカウントリンクの実装時には、次のベストプラクティスを参考にしてください。

アプリ間アカウントリンクの見つけやすさ

アプリからアプリ間アカウントリンクを簡単に使用するには、次のベストプラクティスを参考にしてください。

クリック数を少なくする

アカウントリンクフローを開始するために必要なクリック数をできるだけ少なくしてください。アプリのホーム画面からアカウントリンクフローに移動するまでに、3回以上クリックする必要はありません。アプリのホーム画面から始まる、一般的なフローの例です。

フローの例1
ユーザーは次の操作を行います。

  1. アプリのハンバーガーメニューをクリックします。
  2. Alexaとリンクをクリックします。
  3. 許可をクリックして、アプリからアカウントリンクのフローを開始します。
  4. Alexaアプリ内でアカウントリンクに同意します。
  5. アプリにリダイレクトされます。

フローの例2
ユーザーは次の操作を行います。

  1. アプリのハンバーガーメニューをクリックします。
  2. サードパーティ統合(または類似の文言)をクリックします。
  3. Alexaとリンクをクリックします。
  4. 許可をクリックして、アプリからアカウントリンクのフローを開始します。
  5. Alexaアプリ内でアカウントリンクに同意します。
  6. アプリにリダイレクトされます。

Alexaとの統合がわかるようにする

ユーザーが初めてアプリを使用するときに、Alexaとの統合について知らせます。たとえば、アプリのセットアップの最後に、Alexaロゴ付きの画面を追加して、アプリ間アカウントリンクのフローにユーザーを誘導します。

ユーザーがAlexaロゴをクリックすると、アプリ間アカウントリンクのフローが始まります。ユーザーがアカウントリンクをスキップしたい場合は、メニュー画面で後からリンクできることを知らせます。

音声アシスタントの設定を確認する

アプリに音声アシスタントに関する設定がある場合は、その設定からアカウントリンクが開始できるようにしてください。

ユーザビリティ

アプリ間アカウントリンクを簡単に使用するには、次のベストプラクティスを参考にしてください。

アカウントリンクの正確な状態を表示する

アプリに正しいボタン(リンクまたはリンク解除)を表示するには、Alexaスキル有効化APIに対してアカウントリンクとスキルのステータスの取得リクエストを行い、特定のユーザーのスキル有効化とアカウントリンクのステータスを取得します。ただし、これはアプリ間アカウントリンクを使用してアカウントをリンクしたユーザーに対してのみ正常に応答します。したがって、ユーザーがスキルを無効にしてアカウントのリンクを解除したときに通知を受け取るには、スキル無効化イベントにも対応することを推奨します。ユーザーがアカウントをリンクしているかどうかを確認するために、バックエンドに存在するAlexaトークンペアを頼りにすることはできません。

明確なメッセージを提供する

アプリ間アカウントリンクのエクスペリエンスを考慮し、すべてのフローにおいてユーザーに明確なメッセージを提供します。ユーザーがアカウントリンクの途中でキャンセルしたり、タイムアウトしたりするケースを適切に処理します。エラーに関して明確な情報を提供します。

ユーザーをリダイレクトする前に、必要な情報をすべて取得する

アカウントリンクに必要な情報がそのほかにある場合は、ユーザーをAlexaアプリやLWAにリダイレクトする前にたずねます(追加の詳細情報、同意、PINなど)。

ユーザーのリクエストが金融取引や個人情報が関係する処理の場合、リクエストを実行する前に、事前に設定されたセキュリティの質問に答えるようにユーザーに求めます。

ブランドガイドラインに従う

アプリのユーザーインターフェースは、Amazon開発者のためのAlexaブランドガイドラインに従ってデザインします。これにより、サービスをAlexaと使用するためにアカウントリンクが求められることが一目でわかります。

リンク解除

アカウントリンク済みのユーザーのリンク解除と、リンク解除をユーザーに知らせるためのベストプラクティスです。

アプリ内でリンク解除を実装する

アプリ内からアカウントリンクを解除する方法をユーザーに提供する必要があります。そのためには、アプリ間アカウントリンクのフロー中にアプリが受け取ったAmazonのアクセストークンペアを保持して、後のアプリからのリンク解除のために使用します。ユーザーに対してスキルを無効にし、アカウントをリンク解除するには、Alexaスキル有効化APIにスキルの無効化とアカウントのリンク解除リクエストを行います。

リンク済みのユーザーで、アプリ間アカウントリンクを使用していない場合は、リンク解除ボタンを押したときにAlexaアプリのスキルページに遷移して、ユーザーがスキルを無効にできるようにします。Alexaアプリのスキルのページのリンクは、次の例のようになります。

  • Androidhttps://alexa.amazon.com/spa/index.html#skills/dp/{skillAsin}
  • iOShttps://alexa.amazon.com/spa/index.html#skills/dp/{skillAsin}
  • フォールバック(Alexaアプリがインストールされていない場合): ユーザーをhttps://www.amazon.co.jp/dp/{skillAsin}にリダイレクトします。

スキルのAmazon Standard Identification Number(ASIN)を確認するには、Alexaスキルストアでスキルを表示します。ASINは、URL内にある10桁の英数字のIDです。たとえば、URLがwww.amazon.com/gp/product/A1A1A1A1A1の場合、ASINはA1A1A1A1A1となります。

リンクしていないユーザーに知らせる

リンクしていないユーザーに、アカウントリンク機能について知らせます。ユーザーに知らせるには、プッシュ通知、アプリを新しいバージョンに更新した後の「新機能」のポップアップ画面、アプリストアのリリースノート、ブログ投稿、電子メールなど、さまざまな方法があります。

バックエンドコード

アプリ間アカウントリンクがスムーズに機能するように、次のベストプラクティスを参考にしてください。

バックエンドでURLを組み立てる

ユーザーのAmazon認可コードを取得するコードでは、可能な限り、AlexaアプリのURLとLWAフォールバックURLをバックエンドサーバーで組み立てから、組み立てたURLをアプリに渡すことをお勧めします。これにより、アプリを再ビルドせずにパラメーター(ステージなど)をすぐに変更できます。

リダイレクトURIが機能することを確認する

ステップ4でLWA auth_codeを返すときに、LWAがユニバーサルリンクとアプリリンクをトリガーしない場合があります。ユーザーがアカウントリンクを断念しないように、LWA認証ページと同じウェブビュー内で開かれている場合は、redirect_uri がアカウントリンクリクエストに確実に応えるようにすることをお勧めします。この機能を実装するには、ウェブページがステップ4redirect_uriで受信するauth_code をバックエンドサーバーに送信して、ステップ5ステップ6を実行します。最後に、成功画面(ステップ7)をウェブページに直接表示します。

テストのガイドライン

スキルはまず、すべてのスキルに適用される認定の要件に適合する必要がありますが、それに加え、以下の点のテストを行うことをお勧めします。

  • Alexaアプリがインストールされている場合に、Alexaアプリのフローを使って、アプリからアカウントリンクを開始したときに正常に完了できることを確認します。Androidでは、AlexaアプリのURLを開くときに別のアプリで開くセレクターが表示される場合は、お使いのバージョンのAlexaアプリに無効なアプリリンクがあることを意味します。この問題を解決するには、Alexaアプリを削除して再インストールします。
  • Alexaアプリがインストールされていない場合に、LWAフローを使って、アプリまたはウェブサイトからアカウントリンクを開始したときに正常に完了できることを確認します。LWAのフローをサポートしない実装の場合は、アプリまたはウェブサイトが正常なエラーメッセージをユーザーに返す必要があります。
  • アカウントリンクが失敗した場合、アプリやウェブサイトが正常なエラーメッセージをユーザーに返すことを確認します。
  • アカウントリンクが完了すると、アプリを使用してアカウントリンクを解除できます。また、アカウントリンク状況に応じて、正しいボタン(リンクまたはリンク解除)が表示されるはずです。

また必ずスキルのベータテストを行ってください。ベータテストを有効にするときは、ベータテスターを追加することを忘れないでください。

スキルは公開されるまで、stage値をdevelopmentに設定してAlexaアプリのURLAlexaスキル有効化APIを使用する必要があります。スキルの公開時にliveに変更します。

よくある質問

以下は、アプリから開始する場合のアプリ間アカウントリンクについてのよくある質問です。

質問: ユーザーのモバイルデバイスにAlexaアプリがインストールされていない状態を、どのように確認できますか?

iOSで確認する場合の例については、 例:URLを開くステップ4: ユーザーのAmazon認可コードを取得するで参照してください。

質問: 複数のスキルを持っています。すべてのスキルでアカウントを一度にリンクできますか?

ユーザーの信用を保護するため、アプリ間アカウントリンクには、スキルごとにユーザーの同意が必要です。ユーザーのアカウントを複数のAlexaスキルにリンクする場合、ユーザーは複数回リンクフローを操作する必要があります。

質問: スキルが既に有効で、アカウントが既にリンクされていることはどのように確認できますか?

Alexaスキル有効化APIに対してアカウントリンクとスキルのステータスを取得するリクエストを行います。このAPIを呼び出すときは、次のアクセストークンのいずれかを使用する必要があります。

  • ユーザーのアプリ間アカウントリンクを設定したときに受け取ったトークン。
  • (スマートホームスキルのみ)相互認証後にAcceptGrantディレクティブから受け取ったトークン。
質問: スキルが既に有効で、アカウントが既にリンクされている場合どうなりますか?

Alexaスキル有効化APIに対してスキルの有効化とアカウントリンクリクエストを行うと、ユーザーのアカウントが再リンクされ、成功応答が返されます。

質問: アカウントリンクが完了したときに開発者が通知を受け取るにはどうすればよいですか?

アカウントリンクイベントのサブスクリプションを行ってください。

質問: ユーザーがアプリで現在ログインしているアカウントとは別のユーザーアカウントをAlexaとリンクさせたい場合、どうすればいいですか?

Alexaをほかのアカウントとリンクするには、まずほかのアカウントでアプリにログインし、アプリ内からアカウントリンクを開始します。アカウントリンクフローの中でアカウントを切り替えるオプションをアプリに表示することもできます。

質問: ユーザーがAlexaを使用しておらず、Alexaアプリをインストールしていない場合はどうすればいいですか?

ユーザーがAmazonアカウントを持っているがAlexaは使用していない場合、Amazonの認証情報を使ってLWAページにサインインし、リンクリクエストに同意します。ユーザーがAmazonアカウントを持っていない場合、LWA画面で新規のAmazonアカウントを作成し、スキルのアカウントリンクを行います。ただし、ユーザーがAlexa機能を使用するには、Alexa搭載デバイスまたはAlexaアプリが必要です。

質問: ユーザーがアカウントリンクを取り消すにはどうすればよいですか?

スキルを無効にすると、ユーザーのアカウントのリンクが解除されます。スキルを無効にするには、「アレクサ、 {skill name}を無効にして」と話しかけるか、スキルの詳細ページからスキルを削除します。ユーザーに対してスキルを無効にし、アカウントをリンク解除するには、Alexaスキル有効化APIにスキルの無効化とアカウントのリンク解除リクエストを行います。

質問: 公開しているスキルをユーザーが無効にすると、開発者にどのようなことが発生しますか? 開発者には通知されますか?

公開しているスキルをユーザーが無効にしたときに通知を受け取るには、スキル無効化イベントのサブスクリプションを行います。スキルが無効になった場合、開発者はアクセストークンを取り消し、ユーザーのAmazonアクセストークンを削除する必要があります。Alexaもサービスから提供されたアクセストークンを削除し、Amazonアクセストークンを取り消します。

質問: スキルに権限が必要な場合、 アプリ間アカウントリンクの接続時に権限も取得できますか?

権限(デバイスのアドレスやユーザープロファイル情報など)は現在、このアカウントリンクフローでは取得できません。権限が必要なインテントでユーザーがスキルを呼び出す場合、実行時に権限カードでユーザーにプロンプトを出して、必要な権限を求める必要があります。

ただし、ユーザーがもう1つのアプリ間アカウントリンクフロー(アプリ間アカウントリンク(Alexaアプリから開始する場合))を使用してアカウントをリンクする場合、権限を付与するよう求めるプロンプトがユーザーに対して出されます。そのフローを使用して必要な権限を付与できます。

質問: モバイルデバイスにAlexaアプリがインストールされていない状態を、どのように確認できますか?

AlexaアプリがiOSデバイスまたはAndroidデバイスにインストールされているかどうかを確認する方法については、 例:URLを開くステップ4: ユーザーのAmazon認可コードを取得するで参照してください。

質問: サービスからユーザーアカウントの認可コードを取得するにはどうすればよいですか?

認可サーバーを使用して、ユーザーの認可コードを生成する必要があります。従来のアカウントリンクフローでは、この認可コードは、ユーザーがサービスにログインし、Alexaとのリンクに同意するステップで生成されていました。アプリ間アカウントリンク(アプリから開始)の場合は、ユーザーはすでにログインしているため、OAuthプロバイダーからユーザーの新しい認可コードをプログラムで生成する必要があります。ユーザーは、再度ログインして同意する必要はありません。


このページは役に立ちましたか?

最終更新日: 2024 年 04 月 23 日