Se usó la API de Cloud Translation para traducir esta página.

App Flip para Android

Una vez que tengas una implementación de OAuth 2.0, tienes la opción de configurar un App Flip , which allows your Android users to more quickly link their accounts in your authentication system to their Google accounts. The following sections describe how to design and implement App Flip for your smart home Action. basado en OAuth.

Lineamientos de diseño

En esta sección, se describen los requisitos de diseño y las recomendaciones para la pantalla de consentimiento de vinculación de cuentas de Apps Flip. Una vez que Google llama a tu app, esta muestra la pantalla de consentimiento al usuario.

Requisitos

Debes comunicar que la cuenta del usuario se vincula a Google, no a un producto específico de Google, como Google Home o el Asistente de Google.

Recomendaciones

Configuración de la versión de la app basada en OAuth

En las siguientes secciones, se describen los requisitos para usar Flip en la app basado en OAuth y cómo configurar tu proyecto de Flip en la Consola de Actions.

Crea una Acción de casa inteligente y configura un servidor de OAuth 2.0

Antes de que puedas 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 Cómo implementar un servidor OAuth 2.0.
Crea una acción. Para crear una acción, sigue las instrucciones en Crea un proyecto de acciones.

Configura Flip de apps en la Consola de Actions

En la siguiente sección, se describe cómo configurar App Flip en la Consola de Actions.

Llena todos los campos en Información del cliente de OAuth. (Si no se admite App Flip, se usa OAuth normal como resguardo).
En Utilizar la aplicación para la vinculación de cuentas (opcional), marca Habilitar 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 antes de que se puedan instalar. Para obtener más información sobre cómo obtener la firma de tu app, consulta Cómo autenticar tu cliente.
Intent de autorización. En este campo, ingresa una string que especifique la acción de tu intent.

Si deseas configurar el cliente de manera opcional, agrega alcances y haz clic en Agregar alcance en Configurar tu cliente (opcional).
Haz clic en Guardar.

Cómo implementar App Flip en tus apps de Android

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

La vinculación de apps mediante Flip basada en OAuth inserta la app para Android en el flujo de vinculación de Cuentas de Google. Un flujo de vinculación de cuentas tradicional requiere que el usuario ingrese sus credenciales en el navegador. El uso de App Flip aplaza 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 necesitará volver a ingresar sus credenciales para vincular su cuenta. Se requiere una cantidad mínima de cambios de código a fin de implementar App Flip en tu app para Android.

En este documento, aprenderás a modificar tu app para Android a fin de que sea compatible con App Flip.

Prueba la muestra

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

La app de muestra está preconfigurada a fin de integrarse a la Herramienta de pruebas de Flip para Android, que puedes usar a fin de verificar la integración de tu app para Android con App Flip antes de configurar la vinculación de cuentas con Google. Esta app simula el intent que activan las apps para dispositivos móviles de Google cuando se habilita App Flip.

Cómo funciona

Para llevar a cabo una integración de App Flip, debes seguir estos pasos:

Google app verifica si tu app está instalada en el dispositivo con su nombre de paquete.
Google app usa una verificación de firma de paquetes para validar que la app instalada sea la correcta.
Google app 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 App Flip mediante la resolución de este intent a través del marco de trabajo de Android.
Tu app valida que la solicitud provenga de Google app. Para ello, verifica la firma del paquete y el ID de cliente proporcionado.
Tu aplicación solicita un código de autorización de tu servidor de OAuth 2.0. Al final de este flujo, se muestra un código de autorización o un error en Google app.
Google app recupera el resultado y continúa con la vinculación de cuentas. 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 a fin de que sea compatible con App Flip

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

Agrega un <intent-filter> al archivo AndroidManifest.xml con una string de acción que coincida con el valor que ingresaste en el campo Intent de Flip de la 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 que realiza la llamada.

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
}

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 = "<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...
    }
}

Si la autorización es exitosa, 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, muestra un resultado de error.

Nota: No manejes el error directamente dentro de tu app. En su lugar, muestra el resultado del error mediante setResult. Esto garantiza que el método de resguardo apropiado se active si el flujo de vinculación de apps falla.
```
// 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 lanzamiento

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

CLIENT_ID (String): Google client_id está registrado en la aplicación.
SCOPE (String[]): Es una lista de alcances solicitados.
REDIRECT_URI (String): La URL de redireccionamiento.

Contenido de los datos de respuesta

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

AUTHORIZATION_CODE (String): El valor del código de autorización.
resultCode (int): comunica el éxito o fracaso del proceso y toma uno de los siguientes valores:
- Activity.RESULT_OK: indica que la operación se realizó correctamente; se muestra un código de autorización.
- Activity.RESULT_CANCELLED: Indica que el usuario canceló el proceso. En este caso, Google app intentará vincular la cuenta 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: Google app intentará vincular la cuenta mediante la URL de autorización.
- 2: Error irrecuperable: Google app anula la vinculación de cuentas.
- 3: Parámetros de solicitud no válidos o faltantes.
ERROR_CODE (int): 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): mensaje de estado legible que describe el error.

Nota: Consulta el estándar OAuth 2.0 para obtener más información sobre los errores posibles 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 propague el valor 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 no recuperable:

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 mostrar el resultado del error mediante setResult a fin de asegurarte de que se active el resguardo apropiado.

Cómo probar el modo Flip de apps en tu dispositivo

Ahora que creaste una Acción y configuraste App Flip en la consola y en tu app, puedes probar App Flip en tu dispositivo móvil. Puedes usar la app de Asistente de Google o la app de Google Home para probar App Flip.

Para probar App Flip desde la app del Asistente, sigue estos pasos:

Ve a la Consola de Actions y selecciona tu proyecto.
Haga clic en Test en la barra de navegación superior.
Activa el flujo de vinculación de cuentas desde la app del Asistente:

Abre la app del Asistente de Google.
Haz clic en Configuración.
En la pestaña del Asistente, haz clic en Control del hogar.
Haga clic en Agregar(+).
Selecciona tu acción en la lista de proveedores. Tendrá el prefijo “[test]” en la lista. Cuando selecciones la acción [test] de la lista, debería abrirse la app.
Verifica que se haya iniciado tu app y comienza a probar tu flujo de autorización.

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

Ve a la Consola de Actions y selecciona tu proyecto.
Haga clic en Test en la barra de navegación superior.
Activa el flujo de vinculación de cuentas desde la app de Home:

Abre la app de Google Home.
Haz clic en el botón +.
Haz clic en Configurar dispositivo.
Haga clic en ¿Ya configuró algo?
Selecciona tu Acción de casa inteligente de la lista de proveedores. Tendrá el prefijo “[test]” en la lista. Cuando selecciones la acción [test] de la lista, debería abrirse la app.
Verifica que se haya iniciado tu app y comienza a probar tu flujo de autorización.

Cree un proyecto de Actions

Identifica y sincroniza