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



このアカウントリンクフローを使用すると、ユーザーはAlexaアプリから、AlexaユーザーIDと別のサービスでのIDをリンクできるようになります。ユーザーがモバイルデバイスでアプリとAlexaアプリの両方にログインしている場合、どちらのアプリにもアカウント認証情報を入力せずにアカウントをリンクできます。

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

• アプリからアプリ間アカウントリンクを開始 - ユーザーは、Alexaアプリではなく、アプリまたはウェブサイトからアカウントをリンクします。詳細については、アプリ間アカウントリンク（アプリから開始する場合）を参照してください。
• Alexaアプリのみ（ブラウザのフロー） - Alexaアプリの中だけでアカウントリンクのユーザー操作が完結します。これは最も一般的なフローです。詳細については、アカウントリンクフローを選択するを参照してください。

アプリやウェブサイトをお持ちで、ユーザーに再度ログインを求めることなく、ユーザーのAuthorizaion Grantを取得できる場合は、Alexaアプリのみのフローに加えて、いずれかのアプリ間アカウントリンクフローの実装をお勧めします。

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

• 用語
• ユーザーの操作
• 実装するフローの選択
• しくみ
• アプリへの認可リクエストのパラメーター
• 主な手順
• ベストプラクティス
• テストのガイドライン
• よくある質問
• 関連トピック

用語

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

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

ユーザーの操作

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

• ユーザーは、スキルを有効にするか、スキルの詳細ページでアカウントをリンクオプションをクリックして、Alexaアプリ内からプロセスを開始します。ユーザーがアカウントリンクプロセスを開始すると、モバイルデバイスにアプリがインストールされているかどうかによって、以下のいずれかのフローが適用されます。
• （アプリのフロー）モバイルデバイスにアプリがインストールされている場合は、デバイスがアプリを起動し、ユーザーに対してアカウントリンクリクエストへの同意を求めます。ユーザーがリクエストに同意すると、デバイスはユーザーをAlexaアプリにリダイレクトします。
• （ブラウザのフロー）デバイスにアプリをインストールしていない場合のフローは、Alexaアプリのみのアカウントリンクフローと同じです。つまり、ユーザーのブラウザが認証ページを開き、ユーザーにアカウントリンクリクエストへの同意を求めます。ユーザーがリクエストに同意すると、認証ウェブサイトはユーザーをAlexaアプリにリダイレクトします。

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

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

以下の例は、アプリがインストールされている場合のフローです。

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

以下の例は、アプリがインストールされていない場合のフローです。このフローは、Alexaアプリのみのフロー（ブラウザのフロー）と同じです。

実装するフローの選択

実装するアプリ間アカウントリンクフローは、ユーザーがモバイルデバイスにアプリをインストールしているかどうかによって異なります。ユーザーがデバイスにアプリをインストールしている場合は、アプリのフローをメインのフローとして実装し、ブラウザのフローをアプリがインストールされていない場合の対応として実装します。ユーザーがモバイルデバイスにアプリをインストールしないと想定する場合は、ブラウザのフローを実装します。

しくみ

アプリ間アカウントリンクはOAuth 2.0に基づいて機能します。処理の流れは以下のとおりです。

1. ユーザーはAlexaアプリをインストールしてログインします。
2. ユーザーは、以下のいずれかを実行して、Alexaアプリでアカウントリンクプロセスを開始します。
   1. スキルの詳細ページで有効にするをタップします。
   2. ユーザーが以前にスキルを有効にしていた場合は、スキルの設定ページでアカウントをリンクをタップします。
   3. Alexaアプリでユーザーがスキルを操作したときに表示されるアカウントリンクカードでアカウントをリンクをタップします。
3. 次のステップは、ユーザーのデバイスにアプリがインストールされているかどうかによって、以下の2つに分かれます。
   
   • アプリがインストールされている場合：
     1. Alexaアプリは、認可リクエストに必要なパラメーターとともに、アプリのユニバーサルリンク（iOS）またはアプリリンク（Android）を使用して、ユーザーをアプリにリダイレクトします。
     2. アプリは同意画面を表示し、アカウントリンクのリクエストに同意するか拒否するかをユーザーに確認します。
     3. ユーザーがリクエストに同意します。
     4. （オプション）アプリはユーザーから、優先するストアの場所などの追加情報を取得します。
     5. アプリは認可応答を使用して、ユーザーをAlexaアプリにリダイレクトします。
        
   • アプリがインストールされていない場合： これは、アカウントリンクフローを選択するで説明されている、Alexaアプリのみのアカウントリンクフローです。
4. Alexaアプリは、前のステップの認可応答をAlexaサービスに送信し、アカウントのリンクを終了します。Alexaサービスでは、スキルがImplicit grantとAuthorization code grantのどちらを使用するかに応じて、以下のプロセスを使用します。
   
   • Implicit grant（カスタムスキルのみ）： Alexaサービスは、前のステップで提供されたアクセストークンを保存します。
   • Authorization code grant： Alexaサービスはトークンサーバーを呼び出して、前のステップの認可コードをアクセストークンと更新トークンのペアと交換し、このトークンのペアを保存します。
5. アカウントリンクプロセスが完了します。

アプリへの認可リクエストのパラメーター

このセクションでは、指定したユニバーサルリンク（iOS）またはアプリリンク（Android）を使用してAlexaサービスがアプリに対して実行する認可リクエストのパラメーターについて説明します。

主な手順

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

• iOSアプリ - Swift 4
• Androidアプリ - Kotlin

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

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

ステップ1： アプリのユニバーサルリンク（iOS）またはアプリリンク（Android）を有効にする

Alexaアプリでアプリに認可をリクエストできるようにするには、ユニバーサルリンク（iOS）またはアプリリンク（Android）を有効にする必要があります。

実装方法

例： ユニバーサルリンクを有効にする（iOS）

例： アプリリンクを有効にする（Android）

ステップ2： スキルでアカウントリンク用のコンフィギュレーションを行う

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

アカウントリンクのコンフィギュレーションの詳細については、Authorization code grantを設定するおよびImplicit grantを設定するを参照してください。

実装方法

例： 開発者コンソールを使ってスキルのコンフィギュレーションを行う

例： CLIを使ってスキルのコンフィギュレーションを行う

例： SMAPIを使ってスキルのコンフィギュレーションを行う

{
  "accountLinkingRequest": {
     "accessTokenScheme": "HTTP_BASIC",
     "accessTokenUrl": "https://api.amazon.com/auth/o2/token/",
     "authorizationUrl": "https://www.amazon.com/ap/oa/",
     "clientId": "yourSMAPIClientId",
     "clientSecret": "yourSMAPIClientSecret",
     "domains": [],
     "authorizationUrlsByPlatform": [
      {
        "platformType": "iOS",
        "platformAuthorizationUrl": "https://youriOSURL"
      },
      {
        "platformType": "Android",
        "platformAuthorizationUrl": "https://yourAndroidURL"
      }
     ],
     "scopes": ["profile"],
     "skipOnEnablement": true,
     "type": "AUTH_CODE"
  }
}

ステップ3： アプリで認可リクエストを処理する

AlexaサービスがauthorizationUrlsByPlatformを使用してアプリのユニバーサルリンクまたはアプリリンクを呼び出す場合、アプリはユーザーに同意画面を表示し、アカウントへのリンクの認可を取得する必要があります。

実装方法

https://yourAppAuthUrl?
response_type={Response Type}&
client_id={Client ID}&
scope={Scope}&
state={State}&
redirect_uri={Redirect URI}

例： 認可リクエストを処理する（iOS）

// AppDelegateのユニバーサルリンクハンドラー
// ユニバーサルリンクを処理するメソッドを追加します。
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
        let incomingURL = userActivity.webpageURL else {
            return false
    }

    guard let components = NSURLComponents(url: incomingURL, resolvingAgainstBaseURL: true),
        let queryParameters = components.queryItems else {
            return false
    }
    
    let AUTH_REQUEST_PARAMETERS: Set = ["redirect_uri", "state", "scope", "client_id", "response_type"]
    var validatedParameters : [String: String] = [:]
    for queryParameter in queryParameters {
        if AUTH_RESPONSE_PARAMETERS.contains(queryParameter.name) {
            validatedParameters[queryParameter.name] = queryParameter.value
        }
    }

    let initialViewController = UIStoryboard(name: "Main", bundle: nil).instantiateViewController(withIdentifier: "appToAppConsentScreen") as! AppToAppScreenViewController
            initialViewController.authorizationRequest = validatedParameters
            self.window?.rootViewController = initialViewController
            self.window?.makeKeyAndVisible()
            return true

}

// 同意画面のコントローラーを作成します。
class AppToAppScreenViewController: UIViewController {
    
    var authorizationRequest : [String: String]?
    
    override func viewDidLoad() {
        super.viewDidLoad()
    }
    
    
    @IBAction func acceptButtonClicked(_ sender: UIButton) {
        guard let responseUri = 
            callBackendForAuthorization(authorizationRequest: authorizationRequest, "ACCEPT") else {
                return
        }
        
        // このメソッドの実装については次のステップを参照してください。
        openUrl(alexaUrl: responseUri)
    }
    
    @IBAction func denyButtonClicked(_ sender: UIButton) {
        
        guard let responseUri = 
            callBackendForAuthorization(authorizationRequest: authorizationRequest, "DENY") else {
                return
        }
        
        // このメソッドの実装については次のステップを参照してください。
        openUrl(alexaUrl: responseUri)
    }
}

例： 認可リクエストを処理する（Android）

class AppToAppConsent : AppCompatActivity() {
 
     // 定数
     private val QUERY_PARAMETER_KEY_CLIENT_ID = "client_id"
     private val QUERY_PARAMETER_KEY_RESPONSE_TYPE = "response_type"
     private val QUERY_PARAMETER_KEY_STATE = "state"
     private val QUERY_PARAMETER_KEY_SCOPE = "scope"
     private val QUERY_PARAMETER_KEY_REDIRECT_URI = "redirect_uri"

     private val USER_ACCEPT = "ACCEPT";
     private val USER_DENY = "DENY";

     // 受け取るクエリパラメーター
     private var clientId: String? = null
     private var responseType: String? = null
     private var state: String? = null
     private var scope: String? = null
     private var redirectUri: String? = null
     private var url: String? = null
 
     private lateinit var acceptButton: Button
     private lateinit var denyButton: Button
 
 
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
         val appLinkData = intent.data
 
         // アプリリンクから値を取得します。
         clientId = appLinkData.getQueryParameter(QUERY_PARAMETER_KEY_CLIENT_ID)
         responseType = appLinkData.getQueryParameter(QUERY_PARAMETER_KEY_RESPONSE_TYPE)
         state = appLinkData.getQueryParameter(QUERY_PARAMETER_KEY_STATE)
         scope = appLinkData.getQueryParameter(QUERY_PARAMETER_KEY_SCOPE)
         redirectUri = appLinkData.getQueryParameter(QUERY_PARAMETER_KEY_REDIRECT_URI)
 
         setContentView(R.layout.activity_consent_screen)
         initializeComponents()
     }
 
     private fun initializeComponents() {
  
         acceptButton = findViewById(R.id.btn_accept_linking)
         acceptButton.setOnClickListener {
             val responseUri = callBackendForAuthorization(clientId, responseType, state, scope, redirectUri, USER_ACCEPT)

             // このメソッドの実装については次のステップを参照してください。
             openUrl(responseUri)
         }
 
         denyButton = findViewById(R.id.btn_decline_linking)
         denyButton.setOnClickListener {
             val responseUri = callBackendForAuthorization(clientId, responseType, state, scope, redirectUri, USER_DENY)

             // このメソッドの実装については次のステップを参照してください。
             openUrl(responseUri)   
         }
     }
}

ステップ4： ユーザーをAlexaアプリにリダイレクトする

ユーザーがアプリでアカウントリンクリクエストに同意したら、ユーザーをAlexaアプリにリダイレクトしてアカウントリンクプロセスを終了します。

実装方法

https://alexaAppRedirectUri?
code=yourServiceCode&
state=authorizationRequestState&
source=app

https://alexaAppRedirectUri#
token=yourServiceToken&
token_type=Bearer&
expiration_time=3600&
state=authorizationRequestState&
source=app

https://alexaAppRedirectUri?
error=access_denied&
state=authorizationRequestState&
error_description=The%20user%20denied%20the%20request.%20

https://alexaAppRedirectUri#
error=access_denied&
state=authorizationRequestState&
error_description=The%20user%20denied%20the%20request.%20

例： ユーザーをAlexaアプリにリダイレクトする（iOS）

private func openUrl(alexaAppUrl: URL) {
    UIApplication.shared.open(alexaAppUrl)
}

例： ユーザーをAlexaアプリにリダイレクトする（Android）

private fun openUrl(alexaAppUrl: String) {
    startActivity(Intent.ACTION_VIEW, Uri.parse(alexaAppUrl))
}

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

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

実装方法

ベストプラクティス

アプリ間アカウントリンクの実装時には、次の点に留意してください。

• ユーザーインターフェース - アプリのユーザーインターフェースは、Amazon EchoおよびAlexaブランド使用ガイドラインに従ってデザインします。
• セキュリティ - ユーザーのリクエストが金融取引や個人情報が関係する処理の場合、リクエストを実行する前に、事前に設定されたセキュリティの質問に答えるようにユーザーに求めます。
• 応答URIの生成 - 認可応答またはアクセストークン応答を使用してユーザーをAlexaアプリにリダイレクトするコードでは、応答URIをバックエンドで作成することを強くお勧めします。これにより、アプリを再ビルドせずにパラメーターや検証ロジックをすぐに変更できます。
• アプリでアプリ間アカウントリンクを有効にする - スキルの新しいバージョンを公開する前に、アプリがユニバーサルリンク（iOS）またはアプリリンク（Android）を処理して認証ページを開けることを確認してください。

テストのガイドライン

すべてのスキルに適用される認定の要件にスキルが適合していることを確認することに加え、アプリ間アカウントリンクの実装をテストします。最初に、モバイルデバイスにアプリとAlexaアプリの両方をインストールし、両方のアプリにサインインしていることを確認します。次に、Alexaアプリでスキルを有効にし、以下を確認します。

• スキルを有効にしたときに、ユーザーにアカウントリンクの続行を確認するランディングページをアプリが表示します。
• アプリ内のリンクを選択した後、ユーザーはAlexaアプリにリダイレクトされ、リンクが完了したことを確認する必要があります。
• スキルと対話して、スキルが正しくリンクされていることを確認します。

iOSとAndroidの両方にアプリ間アカウントリンクを実装した場合は、それぞれのエクスペリエンス全体を個別にテストしてください。

よくある質問

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

質問： アカウントリンクリクエストを処理できるアプリが複数あります。アプリ間アカウントリンクフローを設定するにはどうすればよいですか？

この場合は、認証URIで複数のアプリを開くことができる必要があります。ユニバーサルリンクとアプリリンクは、この機能を次のようにサポートしています。

• iOS - アカウントリンクリクエストを処理するすべてのアプリのentitlementsファイルに、認証URIのドメインを追加できます。ドメインのapple-app-site-associationファイルで、アプリごとに異なるエントリを追加できます。ユーザーが複数のアプリをインストールしている場合、apple-app-site-associationファイルでの表示順序で優先度の順位が決まります。

• Android - アカウントリンクリクエストを処理するすべてのアプリのアプリマニフェストに、認証URIのドメインを追加できます。ドメインのAsset Links JSONで、アプリごとに異なるエントリを追加できます。ユーザーが複数のアプリをインストールしている場合、アプリマニフェストのインテントフィルタのpriority属性で優先度の順位が決まります。

質問： 複数のスキルを持っている場合、同じアプリを使用することはできますか？

はい。次のいずれかの方法で対応できます。

• 所有するすべてのスキルに同じ認証URIを使用します。
• スキルごとに個別の認証URIを設定し、アプリを開くスキルごとにユニバーサルリンクまたはアプリリンクを有効にします。

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

ユーザーがログインしているアカウントとは異なるアカウントをAlexaにリンクすることが予想される場合は、ユーザーがアプリでアカウントリンクのリクエストを受け取ったときに、ログアウトして別のアカウントを選択できるようにすることで対応できます。

質問： サードパーティの認可サーバーを使用しています。アプリ間アカウントリンクを実装できますか？

はい。ただし、ユーザーが再度ログインしなくても済むのは、認可サーバーがセッション識別子を使用して認可コードまたはアクセストークンを生成するAPIを公開している場合のみです。

質問： ユーザーはアカウントをリンクした後にデバイスの検出を実行できますか？

はい。アカウントをリンクした後のユーザーエクスペリエンスは、Alexaアプリのみのフローと同じです。

質問： ユーザーは権限の付与に同意できますか？

はい。ユーザーは、アカウントをリンクする前に、引き続きスキル権限を付与できます。

質問： スキルのパーソナライズで動作するようにスキルを設定しています。ユーザーは個人アカウントをリンクできますか？

はい。アプリ間アカウントリンクフローは、個人アカウントのリンクをサポートしています。

質問： ユーザーのAlexaアプリがアプリ間アカウントリンクフローをサポートしているかどうかを確認するにはどうすればよいですか？

Alexaアプリは、アプリ間アカウントリンクフローを完了できるAlexaアプリを持っている場合にのみ、アプリへのリクエストを開始します。

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

スキルを無効にすると、ユーザーのアカウントのリンクが解除されます。スキルを無効にするには、「アレクサ、＜スキル名＞を無効にして」と話しかけるか、スキルの詳細ページからスキルを削除します。

質問： Alexaイベントを送信するようにスキルを設定しました。Alexaイベントはアプリ間フローでどのように機能しますか？

スキルのAlexaイベントを送る権限を有効にしている場合、Lambda関数はAcceptGrantディレクティブを処理する必要があります。スキルがこのディレクティブを処理しない場合、ユーザーがスキルを有効にしようとするとアカウントリンクは失敗します。詳細については、アクセス権限を設定してAlexaへのユーザー認証を実現するを参照してください。

関連トピック

• アプリ間アカウントリンク（アプリから開始する場合）
• アカウントリンクとは