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 Android

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 Android 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 Android.

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 obligatorios(*) en Vinculación de la cuenta. (Si no se admite el cambio de app, se usa OAuth normal como resguardo).
Proporciona una URL para la URL de entrega en la nube. La URL de entrega de Cloud se usa para procesar tus intents de casa inteligente. Marca Local fulfillment.
En Cambio de app (opcional), marca App para Android.
Completa los siguientes campos:

ID de aplicación. El ID de aplicación es un ID único que estableces para tu app.
Firma de la app. Las apps para Android deben estar “firmadas” con un certificado de clave pública para poder instalarse. Para obtener información sobre cómo obtener la firma de tu app, consulta Cómo autenticar a tu cliente.
Es el intent de autorización. En este campo, ingresa una cadena que especifique tu acción de intent.

Si deseas configurar tu cliente de forma opcional, agrega permisos y haz clic en Agregar permiso en Permisos (opcional).
Si tu cliente lo requiere, selecciona Hacer que Google transmita el secreto y el ID de cliente a través del encabezado de autenticación básica HTTP.

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

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) inserta tu app para Android en el flujo de Vinculación de la Cuenta de Google. Un flujo de vinculación de cuentas tradicional requiere que el usuario ingrese sus credenciales en el navegador. El uso del cambio de app difiere el acceso del usuario a tu app para Android, lo que te permite aprovechar las autorizaciones existentes. Si el usuario accedió a tu app, no es necesario que vuelva a ingresar sus credenciales para vincular su cuenta. Se requiere una cantidad mínima de cambios de código para implementar el cambio de app en tu app para Android.

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

Prueba la muestra

La app de ejemplo de vinculación de Cambio de app demuestra una integración de vinculación de cuentas compatible con Cambio de app en Android. Puedes usar esta app para verificar cómo responder a un intent de cambio de app entrante desde las apps de Google para dispositivos móviles.

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

Cómo funciona

Para llevar a cabo una integración de cambio de app, se deben seguir estos pasos:

La app de Google verifica si tu app está instalada en el dispositivo con su nombre de paquete.
La app de Google usa una verificación de firma de paquete para validar que la app instalada sea la correcta.
La app de Google compila un intent para iniciar una actividad designada en tu app. Este intent incluye datos adicionales necesarios para la vinculación. También verifica si tu app admite el cambio de app resolviendo este intent a través del framework de Android.
Tu app valida que la solicitud provenga de la app de Google. Para ello, verifica la firma del paquete y el ID de cliente proporcionado.
Tu app solicita un código de autorización a tu servidor de OAuth 2.0. Al final de este flujo, se devuelve un código de autorización o un error a la app de Google.
La app de Google recupera el resultado y continúa con la vinculación de la cuenta. Si se proporciona un código de autorización, 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.

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

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

Agrega un <intent-filter> a tu archivo AndroidManifest.xml con una cadena de acción que coincida con el valor que ingresaste en el campo Intent de cambio de app.

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

Valida la firma de la app de llamadas.

Debes hacer coincidir el nombre del paquete y la firma de cualquier app de Google que los usuarios puedan usar para vincular la cuenta. Por ejemplo, para vincular con las apps de Google Home y la Búsqueda, agrega sus nombres de paquete y firmas:
- Package name: com.google.android.apps.chromecast.app
- Certificado de linaje SHA-256 original: 3D:7A:12:23:01:9A:A3:9D:9E:A0:E3:43:6A:B7:C0:89:6B:FB:4F:B6:79:F4:DE:5F:E7:C2:3F:32:6C:8F:99:4A
- Certificado SHA-256 rotado de la firma de apps de Play: 5A:AD:2B:EE:6D:B9:5D:17:E0:5A:08:D7:D1:E6:4C:10:A1:51:18:79:15:44:83:91:6B:6A:E6:C7:FD:9C:B0:C6
y
- Package name: com.google.android.googlequicksearchbox
- Firma: F0:FD:6C:5B:41:0F:25:CB:25:C3:B5:33:46:C8:97:2F:AE:30:F8:EE:74:11:DF:91:04:80:AD:6B:2D:60:DB:83
Las solicitudes de vinculación de casa inteligente se inician directamente desde Google Home app (GHA). Si tu aplicación restringe los llamadores y, anteriormente, solo permitía la app de la Búsqueda de Google, debes agregar com.google.android.apps.chromecast.app y sus certificados SHA-256 a tu lista de entidades permitidas para que el cambio de app siga funcionando correctamente.
```
private fun verifyFingerprint(
    expectedPackage: String,
    expectedFingerprints: List<String>
): Boolean {
    val callingPackage = callingActivity?.packageName ?: return false
    if (callingPackage != expectedPackage) return false
    return expectedFingerprints.any { hex ->
        val sha256Bytes =
            hex.split(":").map { it.toInt(16).toByte() }.toByteArray()
        packageManager.hasSigningCertificate(
            callingPackage,
            sha256Bytes,
            PackageManager.CERT_INPUT_SHA256
        )
    }
}
```

Extrae el ID de cliente de los parámetros del intent y verifica que coincida con el valor esperado.

private const val EXPECTED_CLIENT = "<client-id-from-actions-console>"
private const val EXPECTED_PACKAGE = "com.google.android.apps.chromecast.app"
// Original lineage certificate (3D:7A...) and active rotated
// Play App Signing certificate (5A:AD...)
private val EXPECTED_FINGERPRINTS = listOf(
    "3D:7A:12:23:01:9A:A3:9D:9E:A0:E3:43:6A:B7:C0:89:6B:FB:4F:B6:79:F4:DE:5F:E7:C2:3F:32:6C:8F:99:4A",
    "5A:AD:2B:EE:6D:B9:5D:17:E0:5A:08:D7:D1:E6:4C:10:A1:51:18:79:15:44:83:91:6B:6A:E6:C7:FD:9C:B0:C6"
)
...

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

    val clientId = intent.getStringExtra("CLIENT_ID")

    if (clientId == EXPECTED_CLIENT &&
        verifyFingerprint(EXPECTED_PACKAGE, EXPECTED_FINGERPRINTS)) {

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

Una vez que se complete la autorización, devuelve el código de autorización resultante a Google.

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

Si se produjo un error, devuelve un resultado de error.

Nota: No controles el error directamente en tu app; en su lugar, devuelve el resultado del error a través de setResult. Esto garantiza que se active el método de resguardo adecuado si falla el flujo de vinculación de la app.
```
// Error result
val error = Intent().apply {
    putExtra("ERROR_TYPE", 1)
    putExtra("ERROR_CODE", 1)
    putExtra("ERROR_DESCRIPTION", "Invalid Request")
}
setResult(-2, error)
finish()
```

Contenido del intent de inicio

El intent de Android que inicia tu app incluye los siguientes campos:

CLIENT_ID (String): Es el client_id de Google registrado en tu app.
SCOPE (String[]): Es una lista de los permisos solicitados.
REDIRECT_URI (String): Es la URL de redireccionamiento.

Contenido de los datos de la respuesta

Los datos que se devuelven a la app de Google se configuran en tu app llamando a setResult(). Estos datos incluyen lo siguiente:

AUTHORIZATION_CODE (String): Es el valor del código de autorización.
resultCode (int): Comunica el éxito o el fracaso del proceso y adopta uno de los siguientes valores:
- Activity.RESULT_OK: Indica que la operación se realizó correctamente y se devuelve un código de autorización.
- Activity.RESULT_CANCELLED: Es un error recuperable. Indica que el usuario canceló el proceso. En este caso, la app de Google intentará vincular la cuenta nuevamente con tu URL de autorización.
- -2: Indica que se produjo un error. A continuación, se describen los diferentes tipos de errores.
ERROR_TYPE (int): Es el tipo de error, que toma uno de los siguientes valores:
- 1: Error recuperable: La app de Google intentará vincular la cuenta con la URL de autorización.
- 2: Error irrecuperable: La app de Google anula la vinculación de la cuenta.
- 3: Los parámetros de la solicitud no son válidos o faltan.
ERROR_CODE (int): Es un número entero que representa la naturaleza del error. Para ver el significado de cada código de error, consulta la tabla de códigos de error.
ERROR_DESCRIPTION (String, opcional): Es el mensaje de estado legible por humanos que describe el error.

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

Se espera un valor para AUTHORIZATION_CODE cuando resultCode == Activity.RESULT_OK. En todos los demás casos, el valor de AUTHORIZATION_CODE debe estar vacío. Si es resultCode == -2, se espera que se complete el valor de ERROR_TYPE.

Tabla de códigos de error

En la siguiente tabla, se muestran los diferentes códigos de error y si cada uno es un error recuperable o irrecuperable:

Código de error	Significado	Recuperable	Irrecuperable
`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`	✔

Para todos los códigos de error, debes devolver el resultado del error a través de setResult para asegurarte de que se active el resguardo adecuado.

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.

Crea una integración de nube a nube

iOS