Google está realizando la transición de la vinculación de cuentas de casa inteligente de terceros para que se controle de forma completa e independiente en la app de Google Home. Es posible que debas actualizar tu integración antes del 30 de octubre de 2026. Para obtener más información, consulta la guía de migración de la vinculación de cuentas.

Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Cambios de app para iOS

Una vez que tengas una implementación de OAuth 2.0, puedes configurar de forma opcional la App Flip basada en OAuth, que permite que tus usuarios de iOS vinculen más rápido sus cuentas en tu sistema de autenticación con sus Cuentas de Google. En las siguientes secciones, se describe cómo diseñar e implementar App Flip para tu integración de Cloud-to-cloud en iOS.

Lineamientos de diseño

En esta sección, se describen los requisitos y las recomendaciones de diseño para la pantalla de consentimiento de vinculación de cuentas de Cambio de app. Después de que Google llame a tu app, esta mostrará la pantalla de consentimiento al usuario.

Requisitos

Debes tener una declaración de autorización de Google, como "Una vez que se vinculen, Google tendrá permiso para controlar tus dispositivos".
Debes comunicar que la cuenta del usuario se está vinculando a Google, no a un producto específico de Google, como Google Home o Asistente de Google.
Debes incluir un llamado a la acción claro en la pantalla de consentimiento y usar la frase "Aceptar y vincular" para la acción de vinculación. Esto se debe a que los usuarios deben comprender qué datos deben compartir con Google para vincular sus cuentas.
Debes proporcionar una forma para que los usuarios vuelvan atrás, rechacen o cancelen la vinculación si deciden no vincular sus cuentas. Usa la redacción "Cancelar" para la acción de cancelación.
Debes implementar este flujo de trabajo: Después de hacer clic en "Aceptar y vincular", debes mostrar el éxito de la vinculación y redireccionar automáticamente al usuario a la app de Google Home. El usuario ahora debería ver el dispositivo vinculado en la app de Google Home con tu acción. Después de hacer clic en "Cancelar", debes redireccionar al usuario a la app de Google Home.

Recomendaciones

Configura App Flip basado en OAuth

En las siguientes secciones, se describen los requisitos previos para el cambio de app basado en OAuth y cómo configurar tu proyecto de cambio de app en la consola para desarrolladores de Google Home.

Crear una integración de Cloud-to-cloud y configurar un servidor de OAuth 2.0

Antes de configurar App Flip, debes hacer lo siguiente:

Configura un servidor de OAuth 2.0. Para obtener más información sobre cómo configurar un servidor OAuth, consulta Implementa un servidor OAuth 2.0.
Crea una integración de nube a nube. Para crear una integración, sigue las instrucciones que se indican en Crea una integración de Cloud a Cloud.

Configura el cambio de app en la Consola para desarrolladores

En la siguiente sección, se describe cómo configurar el cambio de app en la Consola para desarrolladores.

Completa todos los campos en Información del cliente de OAuth. (Si no se admite App Flip, se usa OAuth normal como resguardo).
En Usa tu app para la vinculación de cuentas(opcional), marca Habilitar para iOS.
Completa el campo Vínculo universal. Para obtener más información sobre los vínculos universales, consulta Cómo permitir que las apps y los sitios web se vinculen a tu contenido.
Si quieres configurar tu cliente de forma opcional, agrega permisos y haz clic en Agregar permiso en Configura tu cliente (opcional).
Haz clic en Guardar.

Ahora puedes continuar con la siguiente sección para implementar App Flip en tu app para iOS.

Implementa App Flip en tus aplicaciones nativas

Para implementar App Flip, debes modificar el código de autorización del usuario en tu app para que acepte un vínculo directo de Google.

La vinculación de Cambio de app basada en OAuth (Cambio de app) abre tu app para iOS desde una app de Google para ayudar al usuario de la app de Google a vincular su cuenta con mayor facilidad. Debes realizar cambios menores en el código de tu app para iOS para implementar esta función.

En este documento, aprenderás a modificar tu app para iOS para que admita el cambio de app.

Prueba la muestra

La app de ejemplo de Cambio de app demuestra una integración de vinculación de cuentas en iOS que es compatible con Cambio de app. Puedes usar esta app para verificar cómo responder a un vínculo universal entrante de cambio de app desde las apps para dispositivos móviles de Google.

La app de ejemplo está preconfigurada para integrarse con la herramienta de prueba de cambio de app para iOS, que puedes usar para verificar la integración de tu app para iOS con cambio de app antes de configurar la vinculación de cuentas con Google. Esta app simula el vínculo universal que activan las apps de Google para dispositivos móviles cuando se habilita el cambio de app.

Cómo funciona

A continuación, se indican los pasos del flujo que realizan la app de Google y tu app cuando se produce el cambio de app:

La app de Google intenta abrir el vínculo universal de tu app. Puede abrir tu app si está instalada en el dispositivo del usuario y asociada con el vínculo universal. Consulta Cómo admitir vínculos universales para obtener más detalles.
Tu app verifica que los parámetros client_id y redirect_uri codificados en la URL entrante coincidan con el vínculo universal de Google esperado.
Tu app solicita un código de autorización a tu servidor de OAuth2. Al final de este flujo, tu app devuelve un código de autorización o un error a la app de Google. Para ello, abre el vínculo universal de Google con parámetros adjuntos para el código de autorización o el error.
La app de Google controla el vínculo universal de Google entrante y continúa con el resto del flujo. Si se proporciona un código de autorización, la vinculación se completa de inmediato. El intercambio de tokens se produce de servidor a servidor, de la misma manera que en el flujo de vinculación de OAuth basado en el navegador. Si se devuelve un código de error, el flujo de vinculación continúa con las opciones alternativas.

Modifica tu app para iOS para que admita el cambio de app

Para admitir el cambio de app, realiza los siguientes cambios de código en tu app para iOS:

Controla NSUserActivityTypeBrowsingWeb en el delegado de tu app.
Captura los parámetros redirect_uri y state de la URL para usarlos más adelante.

Verifica que redirect_uri coincida con este formato:

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

Verifica que el ID de cliente coincida con el valor esperado. Usa la siguiente muestra de código:

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
    }
}

Después de la autorización correcta, llama al URI de redireccionamiento con el código de autorización. Usa la siguiente muestra de código:

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)
    }
}

Si se produjo un error, adjunta un resultado de error al URI de redireccionamiento. Usa la siguiente muestra de código:

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)
    }
}

Parámetros de consulta para el vínculo universal de tu app

Cuando la app de Google abre el vínculo universal de tu app, este incluye los siguientes parámetros de consulta:

client_id (String): Es el client_id de Google que está registrado en tu app.
scope (List of String): Es una lista de permisos solicitados separados por espacios.
state (String): Es un nonce que usa Google para verificar que el resultado de la autorización sea en respuesta a la solicitud saliente de Google.
redirect_uri (String): Es el vínculo universal de Google. Es el URI de "cambio" para abrir la app de Google y pasar los resultados.

Parámetros de consulta para el vínculo universal de Google

Parámetros que se usan cuando el resultado de la autorización se devuelve correctamente:

code (String): Es el valor del código de autorización, si está disponible.
state (String): Es el valor exacto que se recibe del vínculo universal entrante.

Parámetros que se usan cuando el resultado de la autorización se devuelve sin éxito:

error (String), con los siguientes valores:
- cancelled: Es un error recuperable. La app de Google intentará vincular la cuenta con la URL de autorización. Algunos ejemplos son que el usuario no pueda acceder, que un dispositivo esté sin conexión o que se agote el tiempo de espera de una conexión.
- unrecoverable: Es un error irrecuperable. Por ejemplo, el usuario intenta vincular una cuenta inhabilitada.La app de Google anulará la vinculación de la cuenta.
- invalid_request: Los parámetros de la solicitud no son válidos o faltan. Este es un error recuperable. La app de Google intentará vincular la cuenta con la URL de autorización.
- access_denied: El usuario rechaza la solicitud de consentimiento. Este es un error no recuperable; la app de Google anula la vinculación.
error_description (String, opcional): Es un mensaje de error fácil de entender.

Nota: Para obtener más información sobre los posibles errores y el contenido opcional del campo error_description, consulta el estándar de OAuth 2.0.

Para todos los tipos de errores, debes devolver los datos de respuesta al REDIRECT_URI especificado para garantizar que se active el resguardo adecuado.

Modifica tu extremo de autorización para que admita el cambio de app

Configura tu plataforma para que acepte solicitudes con las URLs de redireccionamiento de cambio de app de Google:

App de 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

App del Asistente de 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

Para el Google Home app (GHA), la vinculación de cuentas de casa inteligente usa las URLs de redireccionamiento de com.google.Chromecast. Asegúrate de que tu servidor de autorización permita estas URLs de redireccionamiento.

Verifica que client_id y la URL que especifica el parámetro redirect_uri coincidan con los valores esperados cuando se recibe una solicitud. Si la verificación del cliente falla, devuelve el error invalid_request al redirect_uri.

Prueba App Flip en tu dispositivo

Ahora que creaste una integración de nube a nube y configuraste el cambio de app en la consola y en tu app, puedes probar el cambio de app en tu dispositivo móvil. Puedes usar la app de Google Home para probar el cambio de app.

Para probar App Flip desde la app de Google Home, sigue estos pasos:

Ve a Developer Console y selecciona tu proyecto.
Ve a Cloud-to-cloud > Test.
Activa el flujo de vinculación de cuentas desde la app de Home:

Abre el Google Home app (GHA).
Haz clic en el botón +.
Haz clic en Configurar dispositivo.
Haz clic en ¿Ya tienes otros configurados?
Selecciona tu integración de la nube a la nube en la lista de proveedores. Se antepondrá “[test]” en la lista. Cuando selecciones tu integración de [prueba] en la lista, se debería abrir tu app.
Verifica que se haya iniciado la app y comienza a probar el flujo de autorización.

Android

Identifica y sincroniza