Google 正在将第三方智能家居账号关联功能完全独立地迁移到 Google Home 应用中。您可能需要在 2026 年 10 月 30 日之前更新集成。如需了解详情，请参阅账号关联迁移指南。

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

iOS 版 App Flip

拥有 OAuth 2.0 实现后，您可以选择配置基于 OAuth 的 App Flip，这可让您的 iOS 用户更快地将其在您的身份验证系统中的账号关联到他们的 Google 账号。以下部分介绍了如何在 iOS 上为 Cloud-to-cloud 集成设计和实现 App Flip。

设计准则

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

要求

您必须提供 Google 授权声明，例如“关联后，Google 将有权控制您的设备。”
您必须告知用户，其账号将与 Google 关联，而非与 Google Home 或 Google 助理等特定 Google 产品关联。
您必须在意见征求界面上明确说明号召性用语，并使用“同意并关联”字样来表示关联操作。这是因为用户需要了解他们必须与 Google 共享哪些数据才能关联账号。
如果用户选择不关联，您必须提供一种让用户返回、拒绝或取消的方式。使用“取消”一词表示取消操作。
您必须实现以下工作流：用户点击“同意并关联”后，您必须显示关联成功消息，并自动将用户重定向回 Google Home 应用。用户现在应该会在 Google Home 应用中看到与您的操作相关联的设备。点击“取消”后，您应将用户重定向回 Google Home 应用。

建议

建议您执行以下操作：

显示 Google 的隐私权政策。在意见征求屏幕上添加指向 Google 隐私权政策的链接。
要分享的数据。使用简洁明了的语言告知用户 Google 需要哪些用户数据以及原因。
能够解除关联。提供一种可供用户取消关联的机制，例如指向您平台上的账号设置的网址。或者，您也可以添加指向 Google 账号的链接，以便用户管理其关联的账号。
能够更改用户账号。建议用户切换账号的方法。如果用户倾向于使用多个账号，此功能尤其有用。
- 如果用户必须关闭同意屏幕才能切换账号，请向 Google 发送可恢复的错误，以便用户可以通过 OAuth 关联和隐式流程登录所需账号。
添加您的徽标。在权限请求页面上显示公司徽标。根据样式指南放置徽标。如果您还想显示 Google 的徽标，请参阅徽标和商标。

此图显示了一个同意屏幕示例，其中包含在设计用户同意屏幕时应遵循的各项要求和建议。 — 图 1：账号关联意见征求界面设计准则。

基于 OAuth 的 App Flip 的设置

以下部分描述了基于 OAuth 的 App Flip 的前提条件，以及如何在 Google Home Developer Console 中配置 App Flip 项目。

创建云到云集成并设置 OAuth 2.0 服务器

如需配置 App Flip，你需要先执行以下操作：

设置 OAuth 2.0 服务器。如需详细了解如何设置 OAuth 服务器，请参阅实现 OAuth 2.0 服务器。
创建云到云集成。如需创建集成，请按照创建云到云集成中的说明操作。

在开发者控制台中配置 App Flip

以下部分介绍了如何在开发者控制台中配置 App Flip。

填写 OAuth Client information 下的所有字段。（如果不支持 App Flip，则会使用常规 OAuth 作为后备选项。）
在 Use your app for account linking(optional) 下方，选中 Enable for iOS。
填写 Universal Link 字段。如需详细了解通用链接，请参阅允许应用和网站链接到您的内容。
如果您想选择配置客户端，请添加范围，然后点击 Configure your client (optional) 下的 Add scope。
点击保存。

现在，您可以继续阅读下一部分，在 iOS 应用中实现 App Flip。

在原生应用中实现 App Flip

如需实现App Flip，您需要修改应用中的用户授权代码，以接受来自 Google 的深层链接。

基于 OAuth 的 App Flip 关联 (App Flip) 会从 Google 应用打开您的 iOS 应用，以帮助 Google 应用用户更轻松地关联其账号。您需要对 iOS 应用进行细微的代码更改才能实现此功能。

在本文档中，您将了解如何修改 iOS 应用以支持 App Flip。

试用示例

App Flip 示例应用演示了 iOS 上与 App Flip 兼容的账号关联集成。您可以使用此应用来验证如何响应来自 Google 移动应用的传入 App Flip 通用链接。

示例应用已预先配置为与 App Flip Test Tool for iOS 集成，您可以使用该工具验证 iOS 应用与 App Flip 的集成，然后再配置与 Google 的账号关联。此应用会模拟启用 App Flip 时由 Google 移动应用触发的通用链接。

运作方式

以下是发生 App Flip 时 Google 应用和您的应用执行的流程步骤：

Google 应用会尝试打开应用的通用链接。如果您的应用已安装在用户的设备上，并且与通用链接相关联，则该链接可以打开您的应用。如需了解详情，请参阅支持通用链接。
您的应用会检查传入网址中编码的 client_id 和 redirect_uri 参数是否与预期的 Google 通用链接匹配。
您的应用向 OAuth2 服务器请求授权代码。在此流程结束时，您的应用会向 Google 应用返回授权代码或错误。为此，它会打开 Google 的通用链接，并附加授权代码或错误的参数。
Google 应用会处理传入的 Google 通用链接，并继续执行其余流程。如果提供了授权代码，则关联会立即完成。令牌交换在服务器之间进行，就像在基于浏览器的 OAuth 关联流程中一样。如果返回错误代码，关联流程会继续执行备选选项。

修改 iOS 应用以支持 App Flip

如需支持 App Flip，请对您的 iOS 应用进行以下代码更改：

在应用委托中处理 NSUserActivityTypeBrowsingWeb。
从网址中捕获 redirect_uri 和 state 参数，以供日后使用。

检查 redirect_uri 是否符合以下格式：

https://oauth-redirect.googleusercontent.com/a/GOOGLE_APP_BUNDLE_ID
https://oauth-redirect-sandbox.googleusercontent.com/a/GOOGLE_APP_BUNDLE_ID

验证客户端 ID 是否与预期值一致。请使用以下代码示例：

func application(_ application: UIApplication,
                 continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([Any]?) -> Void) -> Bool
{
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
        let incomingURL = userActivity.webpageURL,
        let components = URLComponents(url: incomingURL, resolvingAgainstBaseURL: false),
        let params = components.queryItems else {
            return false
    }

    if let clientId = params.filter({$0.name == "client_id"}).first?.value,
        let state = params.filter({$0.name == "state"}).first?.value,
        let redirectUri = params.filter({$0.name == "redirect_uri"}).first?.value {

        // Save the redirect_uri and state for later...

        // Verify the client id
        return (clientId == GOOGLE_CLIENT_ID)
    } else {
        // Missing required parameters
        return false
    }
}

授权成功后，使用授权代码调用重定向 URI。使用以下代码示例：

func returnAuthCode(code: String, state: String, redirectUri: String) {
    var redirectURL = URL(string: redirectUri)
    var components = URLComponents(url: redirectURL, resolvingAgainstBaseURL: false)

    // Return the authorization code and original state
    let paramAuthCode = URLQueryItem(name: "code", value: code)
    let paramState = URLQueryItem(name: "state", value: state)
    components?.queryItems = [paramAuthCode, paramState]
    if let resultURL = components?.url {
        UIApplication.shared.open(
            resultURL,
            options: [UIApplicationOpenURLOptionUniversalLinksOnly : true],
            completionHandler: nil)
    }
}

如果发生错误，请改为将错误结果附加到重定向 URI。使用以下代码示例：

func returnError(redirectUri: String) {
    var redirectURL = URL(string: redirectUri)
    var components = URLComponents(url: redirectURL, resolvingAgainstBaseURL: false)

    // Return the authorization code and original state
    let paramError = URLQueryItem(name: "error", value: "invalid_request")
    let paramDescription = URLQueryItem(name: "error_description", value: "Invalid Request")
    components?.queryItems = [paramError, paramDescription]
    if let resultURL = components?.url {
        UIApplication.shared.open(
            resultURL,
            options: [UIApplicationOpenURLOptionUniversalLinksOnly : true],
            completionHandler: nil)
    }
}

应用的通用链接的查询参数

当 Google 应用打开应用的通用链接时，该链接会包含以下查询参数：

client_id (String)：在您的应用下注册的 Google client_id。
scope (List of String)：所请求的以空格分隔的范围列表。
state (String)：Google 用于验证授权结果是否是对 Google 发出的请求的响应的 Nonce。
redirect_uri (String)：Google 的通用链接。用于打开 Google 应用并传递结果的“翻转”URI。

Google 通用链接的查询参数

成功返回授权结果时使用的参数：

code (String)：授权代码的值（如果有）。
state (String)：从传入的通用链接收到的确切值。

授权结果返回失败时使用的参数：

error (String)，具有以下值：
- cancelled：可恢复的错误。Google 应用将尝试使用授权网址进行账号关联。例如，用户登录失败、设备离线或连接超时。
- unrecoverable：不可恢复的错误。例如，用户尝试关联已停用的账号。Google 应用将中止账号关联。
- invalid_request：请求参数无效或缺失。此错误可恢复。Google 应用将尝试使用授权网址进行账号关联。
- access_denied：用户拒绝了同意请求。这是一个不可恢复的错误；Google 应用会中止关联。
error_description（String，可选）：人性化的出错提示。

注意：如需详细了解可能的错误以及 error_description 字段的可选内容，请参阅 OAuth 2.0 标准。

对于所有错误类型，您都必须将响应数据返回到指定的 REDIRECT_URI，以确保触发适当的后备。

修改授权端点以支持 App Flip

将您的平台配置为接受使用 Google 的 App Flip 重定向网址的请求：

Google Home 应用

https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast.dev
https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast.enterprise
https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast.dev
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast.enterprise
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast

Google 助理应用

https://oauth-redirect.googleusercontent.com/a/com.google.OPA.dev
https://oauth-redirect.googleusercontent.com/a/com.google.OPA.enterprise
https://oauth-redirect.googleusercontent.com/a/com.google.OPA
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA.dev
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA.enterprise
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA

对于 Google Home app (GHA)，智能家居账号关联使用 com.google.Chromecast 重定向网址。请确保您的授权服务器允许这些重定向网址。

收到请求后，请检查 client_id 和 redirect_uri 参数指定的网址是否与预期值一致。如果客户端验证失败，则向 redirect_uri 返回错误 invalid_request。

在设备上测试App Flip

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

如需从 Google Home 应用测试 App Flip，请按以下步骤操作：

前往开发者控制台，然后选择您的项目。
前往云到云 > 测试。
在 Google Home 应用中触发账号关联流程：

打开 Google Home app (GHA)。
点击 + 按钮。
点击设置设备。
点击有已设置好的设备？
从提供商列表中选择您的云端到云端集成。它在列表中将带有“[test]”前缀。从列表中选择 [test] 集成后，就应该会打开您的应用。
验证您的应用是否已启动并开始测试授权流程。

Android

识别并同步