アカウントリンクのトラブルシューティング

アカウントリンクのトラブルシューティング

アカウントリンクで問題が発生した場合は、 よくある問題に対する解決策を参照してください。

このセクションでは、以下に挙げるアカウントリンクの問題を取り上げます。

一般的なアカウントリンクの問題

問題： アカウントリンクが失敗する

現象

アカウントをリンクしようとすると、「＜スキル名＞のアカウントリンクを完了できませんでした」または「リンクに失敗しました」というエラーが表示される。

解決方法

Authorization code grantのアカウントリンクフローで最もよくある問題の1つは、認可トークンをアクセストークンおよび更新トークンと交換するプロセスでアカウントリンクが失敗することです。ユーザーがアカウントリンクプロセスを開始すると、Alexaアプリはログインページを表示します。このページには、Alexa開発者コンソールのアカウントリンク設定で指定された認証画面のURIが使用されます。

認可サーバーはユーザーを認証し、認可コードを生成します。Alexaサービスはこの認可コードを記述したPOSTリクエストを送信し、認可サーバーのアクセストークンURIからアクセストークンと更新トークンのペアを取得します。Alexaが認可サーバーからアクセストークンと更新トークンのペアを受信できないと、エラーが表示されます。

通常、この問題は以下の項目をチェックすることで解決できます。

  • 認可サーバーのログをチェックする – 認可サーバーから送信されたエラーが原因で、アカウントリンクに失敗することがよくあります。認可サーバーからの応答をチェックして、アクセストークンと更新トークンのペアを取得するために送られた認可コードに対し、Alexaに返信している内容を確認してください。認可サーバーで確認すべき項目は次のとおりです。
    • 認可サーバーが、アクセストークンおよび更新トークンと交換するための有効な認可コードを生成していることを確認する。
    • 認可サーバーからの応答をログに記録し、アクセストークンと更新トークンをJSON応答で返していること、エラーや無効なJSON応答を送信していないことを確認する。

    GoogleでログインやFacebookログインなど、他社のOAuthサーバーを使用していて、サービスのログにアクセスできない場合は、AWS APIゲートウェイを設定して追加のログにアクセスできます。HAQM APIゲートウェイをプロキシとして設定してAlexaサービスとの間で送受信されるJSONを確認する方法については、How to Set up HAQM API Gateway as a Proxy to Debug Account Linking（英語のみ）を参照してください。

  • スマートホームスキルの場合はAcceptGrantの応答をチェックする – スマートホームスキルでアカウントリンクを使用している場合、変更レポートイベントなどのイベントを送信してデバイスの状態をプロアクティブに報告するために、「Alexaイベントを送る」権限を有効にしていることがあります。スマートホームスキルの「Alexaイベントを送る」権限がオンになっている場合、アカウントリンク中にスキルのLambda関数に送られるAcceptGrantディレクティブを処理する必要があります。スキルのエンドポイントは、AcceptGrant.Responseで同期的に応答し、状態をプロアクティブに報告するための認可コードを取得する必要があります。AcceptGrantディレクティブの詳細については、ディレクティブを参照してください。

    これがアカウントリンク失敗の原因かどうかをテストするには、Alexa開発者コンソールで「Alexaイベントを送る」権限をオフにしてからアカウントリンクを試してみてください。アカウントリンクに成功した場合は、Lambda関数が AcceptGrantディレクティブを処理することを確認します。

  • サーバーが4.5秒以内に応答することをチェックする – 認可サーバーは、アクセストークンリクエストに4.5秒以内に応答する必要があります。4.5秒を過ぎるとリクエストはタイムアウトし、アカウントリンクは失敗します。アクセストークンの要件については、アクセストークンURIの要件を参照してください。

現象

アカウントリンクは成功するが、ユーザーはその後も再度アカウントのリンクを求められる。

解決方法

この現象は通常、Alexaが提供された更新トークンを使用して新しいアクセストークンと更新トークンのペアを取得できなかったことを示しています。アクセストークンには6分以上の有効期限を設定する必要があります。expires_inパラメーターを使用してアクセストークンに6分または360秒以上の有効期限を設定してください。また、Alexa開発者コンソールのデフォルトのアクセストークンの有効期限が360秒以上に設定されていることを確認してください。以下は、アクセストークンの応答例です。

HTTP/1.1 200 OK
Content-Type: application/json;charset UTF-8
Cache-Control: no-store
Pragma: no-cache
{
   "access_token":"Atza|EXAMPLEACCESSTOKEN123456...",
   "token_type":"bearer",
   "expires_in":360,
   "refresh_token":"Atzr|EXAMPLEREFRESHTOKEN123456X..."
}

認可サーバーがアクセストークンペアを更新できるかどうか、5分の有効期限が切れる前に更新トークンを無効にしていないかをテストします。認可サーバーが更新トークンを無効にするとAlexaはアクセストークンと更新トークンのペアを更新できないため、ユーザーはAlexaアプリからアカウントを再度リンクする必要があります。

以下の項目をチェックします。

  • アクセストークンの有効期間（TTL）が5分より長いことを確認する。
  • Alexaから更新トークンを受け取ったときに、認可サーバーがアクセストークンと更新トークンのペアを更新できることを確認する。
  • 更新トークンの有効期限が短すぎないことを確認する。

アクセストークンの要件については、アクセストークンURIの要件を参照してください。

問題： 特定のデバイスでアカウントリンクが機能しない

現象

アカウントリンクがあるデバイスでは機能して別のデバイスでは機能しないことがあり、場合によってはユーザーに空白画面が表示されたり、スマートフォンに新しいウィンドウが表示されたりする。

解決方法

この現象は、Alexa開発者コンソールのアカウントリンク設定で、ドメインリストにドメインが指定されていないことが原因である可能性があります。認証画面のURIのドメイン以外のドメインからスキルのログインページにコンテンツ（画像など）を読み込む場合、そのドメインをスキルの設定に追加する必要があります。これらのドメインは、Alexa開発者コンソールのスキルのアカウントリンク>ドメインリストセクションで追加できます。

アカウントリンクのログインページが呼び出す、または使用する外部ドメインをすべて追加してください。たとえばoauth.sample.comを呼び出す場合、sample.comではなくoauth.sample.comを追加する必要があります。

問題： Googleとのアカウントリンクに問題がある

現象

Googleにアカウントをリンクしようとすると問題が発生する。

解決方法

GoogleのOAuthアーキテクチャでは、ユーザーの初回認証時にのみrefresh_tokenが発行されます。同じアカウントで何度も認証した場合（テスト中など）、そのアカウントはrefresh_tokenを返さず、Alexaサービスが更新トークンをリクエストしてもトークンは返されません。また、Googleからクエリを実行する際にaccess_type=offlineを設定していない可能性もあります。その場合、更新トークンをリクエストしていないことになります。

特定のアカウントで更新トークンが機能するようにするには、Googleのセキュリティ設定でアプリからのアクセスを削除します。その後もう一度認証すると初回認証として処理され、スキルは正常に更新されるようになります。

問題： リダイレクト中にHTTP 400エラーが発生する

現象

アカウントリンクの設定にリダイレクトしたあと、ユーザーにHTTP 400エラーが表示される。

解決方法

この現象は通常、redirect_uriに問題があるか、リダイレクト先URLが無効であることを示しています。また、リクエストサイズが大きすぎる（リダイレクト先URIとドメインのCookieをすべて足した文字数）場合、ページが正しくリダイレクトされないことがあります。

シークレット（プライベート）ウィンドウでアカウントリンクに成功する場合、リクエストサイズが原因である可能性があります。シークレット（プライベート）ウィンドウでアカウントリンクを実行できる場合は、リダイレクト先URLまたは認可コードの文字数を減らしてみてください。リダイレクト先URLにはすべてのクエリパラメーターが含まれているため、パラメーターを短くすることで問題に対応できます。

それでもアカウントリンクが機能しない

現象

上記の解決策を試しても、アカウントリンクの問題が解決しない。

解決方法

次の重要なヒントと要件を確認してください。

  • ポップアップはサポートされません。ポップアップでリンクしようとすると失敗します。
  • Implicit grantでリンクするスキルの場合、機密性の高い情報のクエリパラメーター（アカウントリンクのトークンや状態など）は「#」で始まるURLフラグメントとして含める必要があります。機密性の高い情報をクエリ文字列に含めることはできません。以下は例です。 
    http://pitangui.haqm.com/spa/skill/account-linking-status.html?vendorId=AAAAAAAAAAAAAA#state=xyz∾cess_token=2YotnFZFEjr1zCsicxLpAA&token_type=Bearer
  • アカウントリンクのURLは、HAQMが承認した認証局の証明書で保護されたHTTPS URLである必要があります。
  • アクセストークンを含む応答を送信するときは、必ず200 OKステータスコードを送信してください。
  • HAQMがサポートしている認証方法は、HTTPのBasic認証とリクエスト本文内の認証情報です。別の認証方法を使用しているサービスは、アカウントリンクに失敗します。クライアント認証の詳細については、OAuth 2.0ドキュメントの「Client Password」セクションを参照してください。
  • 認可コードのGrant種別の場合、OAuth2の仕様に従ってアクセストークンをデフォルトでJSON形式で送信する必要があります。アクセストークンがデフォルトで文字列として返される場合、アカウントリンクは失敗します。たとえば、GitHubはこの理由で失敗します。残念ながら、現時点では、何らかの中間APIゲートウェイを介さずにGitHubとアカウントをリンクすることはできません。
HAQMへの問い合わせ

上記の解決策をすべて実行しても問題が解決しない場合は、しばらくしてからもう一度試すか、以下の情報をすべて記入してお問い合わせください。

  • スキルID。
  • アカウントリンクのテスト用認証情報（アカウントリンクページにログインするためのアカウントとパスワード）。
  • 失敗したアカウントのカスタマーID。カスタマーIDは、http://developer.haqm.com/mycid.htmlで確認できます。
  • スキルのリンクに失敗した正確な日時（UTC、またはタイムゾーンを指定）。記録にある最新の日時、できれば14日以内の日時を提供してください。
  • リンクしようとしている地域（EU、NA、アジアなど）。
  • デバイスの種類（AndroidまたはiOS）。
  • Alexaアプリのバージョン。バージョンは、Alexaアプリの設定>その他で確認できます。
  • 問題の説明またはスクリーンショットへのリンク。たとえば、空白ページが表示されたり、「リンクできません」と表示されたり、ページ上のボタンを使用できない、など。
  • Alexa開発者コンソールのアカウントリンクタブの、以下のアカウントリンク設定。
    • 認証画面のURL
    • ドメインリスト
    • アカウントリンクのタイプ（Implicit grantまたはAuthorization code grant）

アプリ間アカウントリンク（開発者のアプリから開始する場合）の問題

問題： 「400 Bad Request」エラー

現象

スキル有効化APIを呼び出すと400 Bad Requestエラーが表示される。

解決方法

このエラーは、スキル有効化APIへのリクエストの形式が正しくない場合に発生することがあります。このエラーが表示された場合は、次の設定を確認してください。

  • 認証パラメーターのBearerにはタイトルケース（1文字目が大文字）を使用する必要があります。各API操作の詳細とリクエスト例については、スキルの有効化REST APIのリファレンスを参照してください。
  • すべてのスキル管理APIと同様、スキル有効化APIを呼び出す前に必ずユーザーのアクセストークンを取得する必要があります。

問題： 「401 Unauthorized」エラー

現象

スキル有効化APIを呼び出すと401 Unauthorizedエラーが表示される。

解決方法

このエラーは、スキルとユーザーの有効化が削除された場合に発生することがあります。ユーザーがいつスキルを無効にしたかを把握していないと、トークンは無効になってしまいます。

この問題を回避するには、スキル無効化イベントを監視し、無効になったスキルのトークンを削除します。そうすることで、トークンが無効になった状況でスキル有効化APIを呼び出すことがなくなります。スキル無効化イベントの詳細については、スキル無効化イベントを参照してください。

問題： 「403 Forbidden」エラー

現象

スキル有効化APIを呼び出すと403 Forbiddenエラーが表示される。

解決方法

以下の原因が考えられます。

  • クライアントIDにアカウントリンクスコープをリクエストする権限がない。
  • スキル有効化APIを呼び出す権限のないアカウントから、開発段階のスキルに対する操作をリクエストした。操作をリクエストできるのは、スキルの作成に使用した開発者アカウントと、ベータテスト用アカウントとして手動で追加したアカウントのみです。

原因に応じて次の解決策を試してください。

解決策1

次の手順を実行して、ユーザーIDにアカウントリンクスコープをリクエストする権限を付与します。

  1. Alexa開発者コンソールにサインインし、スキルに移動します。
  2. ビルドタブをクリックします。
  3. 左側のツールをクリックし、アカウントリンクをクリックします。
  4. アプリのリダイレクト先URLを追加します。
    アプリのリダイレクト先URLを追加することで、クライアントIDにalexa::skills:account_linkingスコープへのアクセス権限が付与されます。

詳細については、URLとエンドポイント、よくある質問、スキルの有効化REST APIのリファレンスを参照してください。

Alexa Skills Kitコマンドラインインターフェース（ASK CLI）またはAlexaスキル管理API（SMAPI）でも同様の処理を実行できます。

解決策2

スキルのベータテストに該当するアカウントを追加します。詳細については、Alexaスキルのベータテストを行うを参照してください。

問題： 「Invalid account linking credentials」エラー

現象

スキル有効化APIを呼び出すと「Invalid account linking credentials」エラーが表示される。

解決方法

このエラーは、サポートされていないOAuth 2.0サーバーを使用した場合に発生することがあります。

アカウントリンクの設定を完了するには、完全に認可されたサーバーを実装する必要があります。そうしないと、Alexaは認可コードをユーザーのアクセストークンと交換できません。デフォルトのアカウントリンク（Alexaアプリから開始する場合）の実装は、アプリ間アカウントリンクフローの一部です。詳細については、スキルへのアカウントリンクの実装を参照してください。

問題： 「Could not contact provider of account linking credentials」エラー

現象

スキル有効化APIを呼び出すと「Could not contact provider of account linking credentials」エラーが表示される。

解決方法

このエラーは、Alexaがトークン交換サーバーに接続できない場合に発生することがあります。

トークン交換サーバーのログを確認し、リクエストが届いているか確認してください。エラーが発生した場合は、ログから根本原因を特定します。

問題： アカウントリンクが完了しない

現象

アプリ間アカウントリンクフローを実施してもスキルが有効にならず、ユーザーのアカウントもリンクされない。

解決方法

この問題は、スキル有効化APIを呼び出してアカウントリンクを有効化していない場合に発生することがあります。

ログをチェックし、アプリ間アカウントリンクフロー（開発者のアプリから開始）でスキル有効化APIが呼び出され、アカウントリンクが完了していることを確認します。詳細については、Enable skill and account link（英語のみ）を参照してください。

問題： Login with HAQM（LWA）フォールバックフローが機能しない

現象

LWAフォールバックフローを実行しようとするとエラーが表示される。

解決方法

以下の原因が考えられます。

  • LWAフォールバックURLを開いてユーザーのHAQM認可コードを取得するときに、スキルが誤った設定を使用している。
  • LWAフォールバックフローが正しく設定されていない。
  • リダイレクト先URLがユーザーのデフォルトブラウザで開かれている。

原因に応じて次の解決策を試してください。

解決策1

LWAフォールバックURLを開くときに使用するURLとクエリパラメーターをチェックします。ユーザーがアカウントリンクリクエストを承認したときにアプリにリダイレクトされるよう、redirectURLにはアプリのURLを指定する必要があります。詳細については、AlexaアプリのURLとLWAフォールバックURLのパラメーター、およびURLとエンドポイントを参照してください。

解決策2

LWAフォールバックフローの以下のパラメーターをチェックします。2組のクライアントIDとシークレットを使用できますが、同じものを使用することはできません。

  • Alexaが提供するクライアントID／シークレット – スキルがアプリ間アカウントリンク（開発者のアプリから開始する場合）を使用する場合、このクライアントID／シークレットは編集できません。これらの値はAlexa開発者コンソールのアカウントリンクセクションに表示されます。LWAからユーザーの同意とアクセストークンを取得するために使用するクライアントIDとシークレットで、このクライアントIDとシークレットを使用してスキル有効化APIを呼び出し、スキルを有効にしてリンクすることができます。
  • 開発者が提供するクライアントID／シークレット – 開発者コンソールのアカウントリンクページで、独自の認可サーバーとトークンサーバー用に指定します（LWAも指定できますが、その場合も上記のクライアントID／シークレットとは別のものです）。アプリ間アカウントリンク（開発者のアプリから開始する場合）では、独自の認可サーバーを使用してユーザーの認可コードを生成し、生成したコードをスキル有効化APIへのリクエストに指定して送信します。

解決策3

リダイレクト先URLがユーザーのデフォルトブラウザで開かれていないか（推奨されません）チェックします。原因として以下の状況が考えられます。

  • アプリでユニバーサルリンクまたはアプリリンクが有効になっていない。
  • ユーザーのデバイス上のアプリのバージョンが古く、ユニバーサルリンクまたはアプリリンクをサポートしていない。
  • 指定したリダイレクト先URLのユニバーサルリンクまたはアプリリンクがアプリで有効になっていない。

どの原因で問題が発生しているか確認してください。最初の2つの状況はユーザーしか解決できませんが、3つ目の状況は開発者側で対処可能です。詳細については、アプリのユニバーサルリンク（iOS）またはアプリリンク（Android）を有効にするを参照してください。

問題： Androidで、ユーザーがデフォルトのブラウザアプリでAlexaアプリを開くとアカウントリンクが失敗する

現象

Androidのアプリ間アカウントリンク（開発者のアプリから開始する場合）フローでAlexaアプリを開くと「別のアプリを使用」セレクタが表示され、ユーザーがデフォルトのブラウザを選択すると、アカウントリンクに失敗する。

解決方法

AndroidのAlexaアプリではAndroidアプリリンクが有効になっていて特定のアプリでリンクを開く必要があるため、ユーザーはデフォルトのブラウザを使用してAlexaアプリを開くことはできないはずです。

「別のアプリを使用」セレクタが表示される場合、そのユーザーのAlexaアプリには無効なアプリリンクがあります。この状況は、Androidマニフェストに指定されたすべてのドメインに対応するassetlinks.jsonファイルを、Alexaアプリがインストール時に取得できなかった場合に発生することがあります。これはAndroidアプリリンクの既知の問題で、ユーザーがAlexaアプリを削除して再インストールすることで解決できます。

問題： アカウントリンクされていないユーザーをアプリ内から「Alexaにリンク」の対象にできない

現象

まだアカウントリンクされていないユーザーをアプリ内から「Alexaにリンク」の対象することができない。

解決方法

この問題は、スキルの初回リリース後にアプリ間アカウントリンクを実装した場合に発生することがあります。その場合、Alexaアプリでの従来のアカウントリンクフローで設定を完了した、アカウントリンク済みの既存ユーザーがいる可能性があります。アプリ間アカウントリンク（開発者のアプリから開始する場合）では、まだアカウントがリンクされていないユーザーだけを対象にすることはできません。

スキルイベント（SKILL_ACCOUNT_LINKEDおよびSKILL_DISABLED）にサブスクライブすると、対象を限定することができます。これらのスキルイベントは、ユーザーの最新のアカウントリンクステータスを通知します。詳細については、Alexaスキルのスキルイベントを参照してください。

アプリ間アカウントリンク（Alexaアプリから開始する場合）の問題

問題： AndroidでアプリではなくウェブURLが開く

現象

AndroidでアプリではなくウェブURLが開く。

解決方法

この問題は、ユーザーのスマートフォンでアプリのアプリリンクが正しく設定されていない場合に発生することがあります。

Androidアプリリンクについて次の点を確認してください。

  • アプリマニフェストのautoVerifyフラグが有効で、アプリでアプリリンクが有効になっている。
  • アプリマニフェストに指定されているすべてのドメインがAndroidアプリリンクの検証をパスしている。
  • アプリマニフェストに指定されているすべてのドメインがassetlinks.jsonファイルをホストしている。

詳細については、Androidドキュメントの「Android アプリリンクを検証する」、「リンクポリシーをチェックする」、および「Digital Asset Links ファイルを確認する」を参照してください。

問題： Androidにアプリがインストールされていない場合、ウェブ認証画面のURIではなくAndroidアプリ認証画面のURIが開く

現象

Androidにアプリがインストールされていない場合、ウェブ認証画面のURIではなくAndroidアプリ認証画面のURIが開く。

解決方法

これは想定される動作で対処は必要はありません。この問題は、Androidにアプリがインストールされていない場合に発生します。その場合、アプリ内ブラウザで使用されるURIはAndroidアプリ認証画面のURIで、ウェブ認証画面のURIではありません。

Andoroidでは、アプリがインストールされていない場合、「Androidアプリの認証URI」フィールドの値がフォールバック認証画面のURIとして使用されます。iOSでは、アプリがインストールされていない場合、「Web認証画面のURI」フィールドの値がフォールバック認証画面のURIとして使用されます。AndoroidとiOSで動作が異なるのは、iOSの制約でAlexaアプリでは外部リンクを開くことができないためで、代わりにウェブ認証画面のURLが使用されます。Androidにはこの制限はありません。

問題： アプリ間アカウントリンクの完了率が正しくない

現象

アプリ間アカウントリンク（Alexaアプリから開始する場合）の完了率が正しくない。

解決方法

アプリ間アカウントリンク（Alexaアプリから開始する場合）フローが成功するかどうかは、アプリがAlexaアプリにリダイレクトするかどうかによって決まります。

ユーザーをAlexaアプリにリダイレクトする際、認証応答に必ずクエリパラメーターsource=appを追加してください。詳細については、ステップ4： ユーザーをAlexaアプリにリダイレクトするを参照してください。

子ども向けスキルの問題

問題： アカウントリンクを追加したら、子ども向けスキルがペアレントダッシュボードに表示されなくなった

現象

子ども向けスキルにアカウントリンクを追加したところ、そのスキルがペアレントダッシュボードに表示されなくなった。

解決方法

これは想定される動作です。子ども向けスキルではアカウントリンクを使用できません。アカウントリンクを追加した子ども向けではないスキルはペアレントダッシュボードに表示されず、子ども用デバイスからはアクセスできません。

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

最終更新日: 2025 年 06 月 10 日