欢迎使用 Google Home 开发者中心，这是一个学习如何开发智能家居 Action 的新平台。注意：构建 Action 的工作仍需在 Actions 控制台中完成。

Android 应用快速关联

拥有 OAuth 2.0 实现后，你可以选择配置基于 OAuth 的 App Flip，这可让你的 Android 用户更快地将其在你的身份验证系统中的帐号关联到他们的 Google 帐号。以下部分介绍了如何为 smart home Action 设计和实现 App Flip。

设计准则

本部分介绍了 App Flip 帐号关联同意屏幕的设计要求和建议。Google 调用您的应用后，应用会向用户显示同意屏幕。

要求

  1. 您必须告知用户该用户的帐号正在与 Google 关联，而不是与特定的 Google 产品（例如 Google Home 或 Google 助理）关联。

建议

建议您执行以下操作：

  1. 显示 Google 的隐私权政策。在同意屏幕上添加指向 Google 隐私权政策的链接。

  2. 要共享的数据。使用简明扼要的语言向用户说明他们所需的 Google 数据及其原因。

  3. 明确的号召性用语。在意见征求屏幕上添加明确的号召性用语，例如“同意并关联”。这是因为用户需要了解他们需要与 Google 共享哪些数据才能关联帐号。

  4. 能够取消。如果用户不进行关联，则可以提供返回或取消的方式。

  5. 能够解除关联。提供一种可让用户取消关联的机制，例如指向其平台上帐号设置的网址。或者，您可以添加一个指向 Google 帐号的链接，以便用户管理其关联帐号。

  6. 能够更改用户帐号。推荐一种切换用户帐号的方法。如果用户往往拥有多个帐号，这种做法尤其有用。

    • 如果用户必须关闭同意屏幕才能切换帐号，请向 Google 发送可恢复的错误，以便用户通过 OAuth 关联和隐式流程登录所需的帐号。

  7. 添加徽标。在同意屏幕上显示您的公司徽标。 根据样式准则放置徽标。如果您还想显示 Google 的徽标，请参阅徽标和商标。

此图显示了一个同意屏幕示例，其中强调了在设计用户意见征求屏幕时需要遵循的各项要求和建议。
图 1：帐号关联同意屏幕设计指南。

基于 OAuth 的应用快速关联的设置

以下部分描述了基于 OAuth 的应用快速关联的前提条件，以及如何在 Actions 控制台中配置应用快速关联项目。

创建智能家居 Action 并设置 OAuth 2.0 服务器

如需配置应用快速关联，你需要先执行以下操作：

在 Actions 控制台中配置应用快速关联

以下部分介绍了如何在 Actions 控制台中配置应用快速关联。

  1. 填写 OAuth Client information 下的所有字段。（如果不支持 App Flip，则会使用常规 OAuth 作为后备选项。）
  2. 在 Use your app for account linking (optional) 下方，选中 Enable for Android。
  3. 填写以下字段：
    • Application ID。这是你为应用设置的唯一 ID。
    • App signature。Android 应用必须先使用公钥证书进行“签名”，然后才能安装。如需了解如何获取应用签名，请参阅对客户端进行身份验证。
    • Authorization intent。在此字段中，输入一个用于指定你的 intent 操作的字符串。
  4. 如果你想选择配置客户端，请添加范围，然后点击 Configure your client (optional) 下的 Add scope。
  5. 点击保存。

在 Android 应用中实现 App Flip

如需实现应用快速关联功能，你需要修改应用中的用户授权代码，以接受来自 Google 的深层链接。

基于 OAuth 的应用快速关联（应用快速关联）会将您的 Android 应用插入 Google 帐号关联流程。传统的帐号关联流程需要用户在浏览器中输入凭据。使用应用快速关联会延迟用户登录 Android 应用，以便您利用现有授权。如果用户已登录您的应用，则无需重新输入凭据即可关联帐号。在 Android 应用中实现应用快速关联所需的代码更改极少。

在本文档中，您将学习如何修改 Android 应用以支持应用快速关联。

试用示例

App Flip 关联示例应用展示了 Android 上与应用快速关联兼容的帐号关联集成。您可以使用此应用验证如何响应从 Google 移动应用传入的应用快速关联 intent。

示例应用已预先配置为与 Android 应用快速关联测试工具集成。在配置 Google 帐号关联之前，您可以使用该应用验证 Android 应用与应用快速关联功能的集成。此应用会模拟启用应用快速关联时由 Google 移动应用触发的 intent。

运作方式

如需执行应用快速关联，必须执行以下步骤：

  1. Google 应用使用应用的软件包名称检查应用是否已安装到设备上。
  2. Google 应用使用软件包签名检查来验证已安装的应用是否为正确的应用。
  3. Google 应用会构建一个 intent，用于启动应用中的指定 activity。此 intent 包含关联所需的其他数据。它还会通过 Android 框架解析此 intent，检查您的应用是否支持应用快速关联。
  4. 您的应用验证请求是否来自 Google 应用。为此，您的应用会检查软件包签名和提供的客户端 ID。
  5. 您的应用向 OAuth 2.0 服务器请求授权代码。在此流程结束时，它会向 Google 应用返回授权代码或错误。
  6. Google 应用会检索结果，并继续关联帐号。如果提供授权代码，则令牌交换会在服务器之间进行，就像在基于浏览器的 OAuth 关联流程中一样。

修改 Android 应用以支持应用快速关联

如需支持应用快速关联，请对您的 Android 应用进行以下代码更改：

  1. 使用您在应用快速关联 intent 字段中输入的值与操作字符串匹配的 AndroidManifest.xml 文件添加一个 <intent-filter>。

    <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. 从 intent 参数中提取客户端 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()

启动 intent 的内容

启动应用的 Android intent 包含以下字段：

  • CLIENT_ID (String)：在您的应用中注册了 Google client_id。
  • SCOPE (String[])：请求的范围列表。
  • REDIRECT_URI (String)：重定向网址。

响应数据的内容

返回到 Google 应用的数据通过调用 setResult() 在您的应用中设置。这些数据包括：

  • AUTHORIZATION_CODE (String)：授权代码值。
  • resultCode (int)：传达相应进程的成功或失败，并采用以下任一值：
    • Activity.RESULT_OK：表示成功；返回授权代码。
    • Activity.RESULT_CANCELLED：表明用户已取消该进程。在这种情况下，Google 应用会尝试使用您的授权网址进行帐号关联。
    • -2：表示出现错误。下面将介绍不同类型的错误。
  • ERROR_TYPE (int)：错误类型，采用以下值之一：
    • 1：可恢复的错误：Google 应用将尝试使用授权网址进行帐号关联。
    • 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 返回错误结果，以确保触发相应的后备。

在设备上测试应用快速关联

现在，你已在控制台和应用中创建了一个 Action 并配置了 App Flip，接下来可以在移动设备上测试 App Flip。你可以使用 Google 助理应用或 Google Home 应用测试 App Flip。

如需从 Google 助理应用测试应用快速关联，请按以下步骤操作：

  1. 转到 Actions 控制台并选择你的项目。
  2. 点击顶部导航栏中的 Test。
  3. 在 Google 助理应用中触发帐号关联流程：
    1. 打开 Google 助理应用。
    2. 点击设置。
    3. 在“Google 助理”标签页上，点击家居控制。
    4. 点击“添加”(+)。
    5. 从提供商列表中选择你的 Action。它在列表中以“[test]”为前缀。从列表中选择 [test] Action 后，就应该会打开你的应用。
    6. 验证你的应用是否已启动并开始测试授权流程。

如需从 Google Home 应用测试应用快速关联，请按以下步骤操作：

  1. 转到 Actions 控制台并选择你的项目。
  2. 点击顶部导航栏中的 Test。
  3. 在 Google Home 应用中触发帐号关联流程：
    1. 打开 Google Home 应用。
    2. 点击 + 按钮。
    3. 点击设置设备。
    4. 点击有已设置好的设备？
    5. 从提供商列表中选择你的智能家居 Action。它在列表中以“[test]”为前缀。从列表中选择 [test] Action 后，就应该会打开你的应用。
    6. 验证你的应用是否已启动并开始测试授权流程。
上一页
Create an Actions project
下一页
Identify and sync