Android 向けアプリ切り替え

OAuth 2.0 を実装すると、OAuth ベースの App Flip を設定できるようになります。これにより、Android ユーザーは認証システムのアカウントを Google アカウントに簡単にリンクできます。以降のセクションでは、smart home アクション用に App Flip を設計および実装する方法について説明します。

Design guidelines

This section describes the design requirements and recommendations for the App Flip account linking consent screen. After Google calls your app, your app displays the consent screen to the user.

Requirements

  1. You must communicate that the user's account is being linked to Google, not to a specific Google product, such as Google Home or Google Assistant.

Recommendations

We recommend that you do the following:

  1. Display Google's Privacy Policy. Include a link to Google's Privacy Policy on the consent screen.

  2. Data to be shared. Use clear and concise language to tell the user what data of theirs Google requires and why.

  3. Clear call-to-action. State a clear call-to-action on your consent screen, such as "Agree and link." This is because users need to understand what data they're required to share with Google to link their accounts.

  4. Ability to cancel. Provide a way for users to go back or cancel, if they choose not to link.

  5. Ability to unlink. Offer a mechanism for users to unlink, such as a URL to their account settings on your platform. Alternatively, you can include a link to Google Account where users can manage their linked account.

  6. Ability to change user account. Suggest a method for users to switch their account(s). This is especially beneficial if users tend to have multiple accounts.

    • If a user must close the consent screen to switch accounts, send a recoverable error to Google so the user can sign in to the desired account with OAuth linking and the implicit flow.

  7. Include your logo. Display your company logo on the consent screen. Use your style guidelines to place your logo. If you wish to also display Google's logo, see Logos and trademarks.

This figure shows an example consent screen with call-outs to the individual requirements and recommendations to be followed when you design a user consent screen.
Figure 1: Account linking consent screen design guidelines.

OAuth ベースのアプリ切り替えを設定する

以下のセクションでは、OAuth ベースのアプリ切り替えの前提条件と、アプリ切り替えプロジェクトを Actions Console で設定する方法について説明します。

スマートホーム アクションを作成して OAuth 2.0 サーバーを設定する

アプリ切り替えを設定する前に、以下を行う必要があります。

Actions Console でアプリ切り替えを設定する

次のセクションでは、Actions Console でアプリ切り替えを構成する方法を説明します。

  1. [OAuth Client information]（OAuth クライアント情報）のすべてのフィールドを入力します（アプリ切り替えがサポートされていない場合は、通常の OAuth がフォールバックとして使用されます）。
  2. [Use your app for account linking (optional)]（アプリをアカウントのリンクに使用する（省略可））で、[Enable for Android]（Android で有効にする）をオンにします。
  3. 次の各項目を入力します。
    • [Application ID]（アプリ ID）。Application ID は、アプリに設定する固有の ID です。
    • [App signature]（アプリ署名）。Android アプリは、インストールする前に公開鍵証明書で署名しておく必要があります。アプリ署名の取得について詳しくは、クライアントの認証をご覧ください。
    • [Authorization intent]（認証インテント）。ここには、インテントのアクションを指定する文字列を入力します。
  4. クライアントを設定したい場合は、スコープを追加し、[Configure your client (optional)]（クライアントを構成する（省略可））で [Add scope]（スコープを追加）をクリックします。
  5. [保存] をクリックします。

Android アプリにアプリ切り替えを実装する

アプリ切り替えを実装するには、Google からのディープリンクを許可するようにアプリのユーザー認可コードを変更する必要があります。

OAuth ベースのアプリ切り替え（アプリ切り替え）を使用すると、Android アプリを Google アカウントのリンク フローに挿入できます。従来のアカウントのリンクフローでは、ユーザーがブラウザに認証情報を入力する必要があります。アプリ切り替えを使用すると、Android アプリへのログインを遅らせることができ、既存の承認を活用できます。ユーザーがアプリにログインしている場合は、アカウントをリンクするために認証情報を再入力する必要はありません。Android アプリにアプリ切り替えを実装するには、最小限のコード変更が必要です。

このドキュメントでは、アプリ切り替えをサポートするように Android アプリを変更する方法について説明します。

サンプルを試す

アプリ切り替えリンクのサンプルアプリは、Android でのアプリ切り替え対応アカウント リンクの統合を示しています。このアプリを使用すると、Google モバイルアプリから受信したアプリ切り替えインテントに応答する方法を確認できます。

サンプルアプリは、Android 用のアプリ切り替えテストツールと統合するように構成されています。このツールを使用して、Google とアカウントのリンクを設定する前に Android アプリと App Flip の統合を確認できます。このアプリは、アプリ切り替えが有効になっている場合に、Google モバイルアプリでトリガーされるインテントをシミュレートします。

仕組み

アプリ切り替えを統合するには、次の手順が必要です。

  1. Google アプリは、パッケージ名を使用して、アプリがデバイスにインストールされているかどうかを確認します。
  2. Google アプリは、パッケージ署名チェックを使用して、インストールされているアプリが正しいアプリであることを確認します。
  3. Google アプリがアプリ内の指定されたアクティビティを開始するためのインテントを作成します。このインテントには、リンクに必要な追加データが含まれます。また、Android フレームワークを通じてこのインテントを解決することで、アプリがアプリ切り替えをサポートしているかどうかを確認します。
  4. アプリは、そのリクエストが Google アプリから送信されていることを検証します。そのため、アプリはパッケージ署名と提供されたクライアント ID を確認します。
  5. アプリが OAuth 2.0 サーバーに認証コードをリクエストします。このフローが終了すると、認証コードまたはエラーが Google アプリに返されます。
  6. Google アプリが結果を取得し、アカウントのリンクを続けます。認証コードを指定すると、サーバー間のトークン交換は、ブラウザベースの OAuth リンクフローの場合と同じように行われます。

アプリ切り替えをサポートするように Android アプリを変更する

アプリ切り替えをサポートするには、Android アプリのコードを次のように変更します。

  1. [App Flip Intent] フィールドに入力した値と一致するアクション文字列を使用して、<intent-filter> を AndroidManifest.xml ファイルに追加します。

    <activity android:name="AuthActivity">
  <!-- Handle the app flip intent -->
  <intent-filter>
    <action android:name="INTENT_ACTION_FROM_CONSOLE"/>
    <category android:name="android.intent.category.DEFAULT"/>
  </intent-filter>
</activity>

  2. 呼び出し元アプリの署名を検証します。

    private fun verifyFingerprint(
        expectedPackage: String,
        expectedFingerprint: String,
        algorithm: String
): Boolean {

    callingActivity?.packageName?.let {
        if (expectedPackage == it) {
            val packageInfo =
                packageManager.getPackageInfo(it, PackageManager.GET_SIGNATURES)
            val signatures = packageInfo.signatures
            val input = ByteArrayInputStream(signatures[0].toByteArray())

            val certificateFactory = CertificateFactory.getInstance("X509")
            val certificate =
                certificateFactory.generateCertificate(input) as X509Certificate
            val md = MessageDigest.getInstance(algorithm)
            val publicKey = md.digest(certificate.encoded)
            val fingerprint = publicKey.joinToString(":") { "%02X".format(it) }

            return (expectedFingerprint == fingerprint)
        }
    }
    return false
}

  3. インテント パラメータからクライアント ID を抽出し、クライアント ID が期待値と一致することを確認します。

    private const val EXPECTED_CLIENT = "<client-id-from-actions-console>"
private const val EXPECTED_PACKAGE = "<google-app-package-name>"
private const val EXPECTED_FINGERPRINT = "<google-app-signature>"
private const val ALGORITHM = "SHA-256"
...

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    val clientId = intent.getStringExtra("CLIENT_ID")

    if (clientId == EXPECTED_CLIENT &&
        verifyFingerprint(EXPECTED_PACKAGE, EXPECTED_FINGERPRINT, ALGORITHM)) {

        // ...authorize the user...
    }
}

  4. 認証が成功したら、結果の認証コードを Google に返します。

    // Successful result
val data = Intent().apply {
    putExtra("AUTHORIZATION_CODE", authCode)
}
setResult(Activity.RESULT_OK, data)
finish()

  5. エラーが発生した場合は、代わりにエラー結果を返します。

    // Error result
val error = Intent().apply {
    putExtra("ERROR_TYPE", 1)
    putExtra("ERROR_CODE", 1)
    putExtra("ERROR_DESCRIPTION", "Invalid Request")
}
setResult(-2, error)
finish()

起動インテントの内容

アプリを起動する Android のインテントには次のフィールドがあります。

  • CLIENT_ID（String）: Google の client_id がアプリに登録されました。
  • SCOPE（String[]）: リクエストされたスコープのリスト。
  • REDIRECT_URI（String）: リダイレクト URL。

レスポンス データの内容

Google アプリに返されるデータは、setResult() を呼び出すことによってアプリ内で設定されます。このデータには次のものが含まれます。

  • AUTHORIZATION_CODE（String）: 認証コードの値。
  • resultCode（int）: プロセスの成功または失敗について通知し、次のいずれかの値を取ります。
    • Activity.RESULT_OK: 成功を示します。認証コードが返されます。
    • Activity.RESULT_CANCELLED: ユーザーがプロセスをキャンセルしたことを示します。この場合、Google アプリは認証 URL を使用してアカウントのリンクを試みます。
    • -2: エラーが発生したことを示します。さまざまなエラーの種類を以下に示します。
  • ERROR_TYPE（int）: エラーのタイプ。次のいずれかの値になります。
    • 1: 回復可能なエラー: Google アプリは、認証 URL を使用してアカウントのリンクを試みます。
    • 2: 回復不能なエラー: Google アプリがアカウントのリンクを中止します。
    • 3: リクエスト パラメータが無効であるか、不明です。
  • ERROR_CODE（int）: エラーの性質を表す整数。各エラーコードの意味については、エラーコードの表をご覧ください。

  • ERROR_DESCRIPTION（String、省略可）: 人が読めるエラーで、エラーを説明するメッセージ。

resultCode == Activity.RESULT_OK の場合、AUTHORIZATION_CODE の値は想定されています。それ以外の場合は、AUTHORIZATION_CODE の値を空にする必要があります。resultCode == -2 の場合、ERROR_TYPE 値が設定されます。

エラーコードの表

次の表は、各エラーコードと、それぞれが回復できるエラーであるか、回復できないエラーであるかを示しています。

エラーコード 意味 回復できる 回収不可
1 INVALID_REQUEST ✔
2 NO_INTERNET_CONNECTION ✔
3 OFFLINE_MODE_ACTIVE ✔
4 CONNECTION_TIMEOUT ✔
5 INTERNAL_ERROR ✔
6 AUTHENTICATION_SERVICE_UNAVAILABLE ✔
8 CLIENT_VERIFICATION_FAILED ✔
9 INVALID_CLIENT ✔
10 INVALID_APP_ID ✔
11 INVALID_REQUEST ✔
12 AUTHENTICATION_SERVICE_UNKNOWN_ERROR ✔
13 AUTHENTICATION_DENIED_BY_USER ✔
14 CANCELLED_BY_USER ✔
15 FAILURE_OTHER ✔
16 USER_AUTHENTICATION_FAILED ✔

すべてのエラーコードについて、適切なフォールバックがトリガーされるように、setResult を介してエラー結果を返す必要があります。

デバイスでアプリ切り替えをテストする

アクションを作成し、コンソールとアプリでアプリ切り替えを設定したら、モバイル デバイスでアプリ切り替えをテストできます。アプリ切り替えをテストするには、Google アシスタント アプリまたは Google Home アプリを使用します。

アシスタント アプリからアプリ切り替えをテストする手順は次のとおりです。

  1. Actions Console に移動して、プロジェクトを選択します。
  2. 上部のナビゲーションで [Test]（テスト）をクリックします。
  3. アシスタント アプリからアカウントのリンクフローをトリガーします。
    1. Google アシスタント アプリを開きます。
    2. [設定] をクリックします。
    3. [アシスタント] タブで、[スマートホーム] をクリックします。
    4. [追加（+）] をクリックします。
    5. プロバイダのリストからアクションを選択します。リストの先頭に「[test]」が付きます。リストから [test] アクションを選択する場合、アプリを開く必要があります。
    6. アプリが起動したことを確認し、承認フローのテストを開始します。

Home アプリからアプリ切り替えをテストする手順は次のとおりです。

  1. Actions Console に移動して、プロジェクトを選択します。
  2. 上部のナビゲーションで [Test]（テスト）をクリックします。
  3. Home アプリからアカウントのリンクフローをトリガーします。
    1. Google Home アプリを開きます。
    2. [+] ボタンをクリックします。
    3. [デバイスのセットアップ] をクリックします。
    4. [セットアップ済みデバイスのリンク] をクリックします。
    5. プロバイダのリストからスマートホーム アクションを選択します。リストの先頭に「[test]」が付きます。リストから [test] アクションを選択する場合、アプリを開く必要があります。
    6. アプリが起動したことを確認し、承認フローのテストを開始します。
前へ
Create an Actions project
次へ
Identify and sync