App Flip para Android

Una vez que tengas una implementación de OAuth 2.0, puedes configurar App Flip basado en OAuth, que permite a tus usuarios de Android vincular 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 acción smart home.

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

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

Te recomendamos que hagas lo siguiente:

  1. Muestra la Política de Privacidad de Google. Incluye un vínculo a la Política de Privacidad de Google en la pantalla de consentimiento.

  2. Datos que se compartirán. Usa un lenguaje claro y conciso para indicarle al usuario qué datos de Google requiere y por qué.

  3. Llamado a la acción claro. En tu pantalla de consentimiento, indica un llamado a la acción claro, como "Aceptar y vincular". Esto se debe a que los usuarios deben comprender qué datos deben compartir con Google para vincular sus cuentas.

  4. Posibilidad de cancelar. Proporciona una forma para que los usuarios retrocedan o cancelen si eligen no vincularse.

  5. Capacidad de desvincularse. Ofrece un mecanismo para desvincular a los usuarios, como una URL para la configuración de la cuenta en tu plataforma. De manera alternativa, puedes incluir un vínculo a una Cuenta de Google en la que los usuarios puedan administrar sus cuentas vinculadas.

  6. Capacidad para cambiar la cuenta de usuario Sugerir un método para que los usuarios cambien sus cuentas Esto es especialmente beneficioso si los usuarios tienden a tener varias cuentas.

    • Si un usuario debe cerrar la pantalla de consentimiento para cambiar de cuenta, envía un error recuperable a Google a fin de que el usuario pueda acceder a la cuenta deseada con la vinculación de OAuth y el flujo implícito.
  7. Incluya su logotipo. Muestre el logotipo de su empresa en la pantalla de consentimiento. Usa tus lineamientos de estilo para colocar tu logotipo. Si también deseas mostrar el logotipo de Google, consulta Logotipos y marcas comerciales.

En esta figura, se muestra un ejemplo de pantalla de consentimiento con menciones de los requisitos individuales y las recomendaciones que se deben seguir cuando se diseña una pantalla de consentimiento del usuario.
Figura 1: Lineamientos de diseño de la pantalla de consentimiento de vinculación de cuentas.

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

En las siguientes secciones, se describen los requisitos para App Flip basada en OAuth y la configuración de tu proyecto de App Flip en la Consola de Actions.

Cómo crear una Acción de casa inteligente y configurar un servidor de OAuth 2.0

Antes de configurar App Flip, debes hacer lo siguiente:

Cómo configurar App Flip en la Consola de Actions

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

  1. Completa todos los campos de la sección Información del cliente de OAuth. (si no se admite App Flip, se usa OAuth normal como resguardo).
  2. En la sección Usa la app para la vinculación de cuentas (opcional), marca la opción Habilitar para Android.
  3. Completa los siguientes campos:
    • ID de aplicación. El ID de aplicación es un ID único que estableces para tu aplicación.
    • 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 tu acción de intent.
  4. Si deseas configurar tu cliente de forma opcional, agrega permisos y haz clic en Agregar permiso en Configurar tu cliente (opcional).
  5. Haz clic en Guardar.

Cómo implementar App Flip en tus apps para Android

Para implementar App Flip, debes modificar el código de autorización del usuario en tu app a fin de 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:

  1. Google app verifica si tu app está instalada en el dispositivo con su nombre de paquete.
  2. Google app usa una verificación de firma de paquetes para validar que la app instalada sea la correcta.
  3. 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.
  4. Tu app valida que la solicitud provenga de Google app. Para ello, verifica la firma del paquete y el ID de cliente proporcionado.
  5. 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.
  6. 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:

  1. 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>
    
  2. 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
    }
    
  3. 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...
        }
    }
    
  4. 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()
    
  5. Si se produjo un error, muestra un resultado de error.

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

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 App Flip en tu dispositivo

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

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

  1. Ve a la Consola de Actions y selecciona tu proyecto.
  2. Haga clic en Probar en la barra de navegación superior.
  3. Activa el flujo de vinculación de cuentas desde la app de Asistente:
    1. Abre la app del Asistente de Google.
    2. Haz clic en Configuración.
    3. En la pestaña Asistente, haz clic en Control de la casa.
    4. Haga clic en Agregar(+).
    5. Selecciona tu acción en la lista de proveedores. Tendrá el prefijo “[test]” en la lista. Cuando seleccionas la acción [test] de la lista, se debe abrir la app.
    6. Verifica que se haya iniciado tu app y comienza a probar el flujo de autorización.

Para probar la función Flip desde la app de Home, sigue estos pasos:

  1. Ve a la Consola de Actions y selecciona tu proyecto.
  2. Haga clic en Probar en la barra de navegación superior.
  3. Activa el flujo de vinculación de cuentas desde la app de Home:
    1. Abre la app de Google Home.
    2. Haz clic en el botón +.
    3. Haz clic en Configurar dispositivo.
    4. Haga clic en ¿Ya tiene otros configurados?
    5. Selecciona tu acción de casa inteligente de la lista de proveedores. Tendrá el prefijo “[test]” en la lista. Cuando seleccionas la acción [test] de la lista, se debe abrir la app.
    6. Verifica que se haya iniciado tu app y comienza a probar el flujo de autorización.