App Flip para Android

Depois de ter uma implementação do OAuth 2.0, você pode configurar o App Flip baseado em OAuth, que permite que os usuários do Android vinculem as contas no seu sistema de autenticação às Contas do Google de forma mais rápida. As seções a seguir descrevem como projetar e implementar o App Flip para sua integração do Cloud-to-cloud no Android.

Diretrizes de design

Esta seção descreve os requisitos e as recomendações de design para a tela de consentimento da vinculação de contas do App Flip. Depois que o Google chamar seu app, ele vai mostrar a tela de consentimento ao usuário.

Requisitos

  1. Você precisa ter uma declaração de autorização do Google, como "Depois de vinculada, o Google terá permissão para controlar seus dispositivos".
  2. Você precisa informar que a conta do usuário está sendo vinculada ao Google, não a um produto específico, como o Google Home ou o Google Assistente.
  3. É necessário indicar uma call-to-action clara na tela de consentimento e usar a frase "Concordar e vincular" para a ação de vinculação. Isso acontece porque os usuários precisam entender quais dados são obrigatórios para compartilhar com o Google e vincular as contas.
  4. Você precisa oferecer uma maneira para os usuários voltarem, negarem ou cancelarem, caso eles escolham não vincular. Use a palavra "Cancelar" para a ação de cancelamento.
  5. Você precisa implementar este fluxo de trabalho: depois de clicar em "Concordar e vincular", mostre o sucesso da vinculação e redirecione o usuário de volta ao app Google Home automaticamente. O usuário vai ver o dispositivo vinculado no app Google Home com sua ação. Depois de clicar em "Cancelar", redirecione o usuário de volta para o app Google Home.

Recomendações

Portanto, recomendamos que você faça o seguinte:

  1. Mostrar a Política de Privacidade do Google. Inclua um link para a Política de Privacidade do Google na tela de consentimento.

  2. Dados que serão compartilhados. Use uma linguagem clara e concisa para informar ao usuário quais dados dele o Google exige e por quê.

  3. Capacidade de desvincular. Ofereça um mecanismo para os usuários desvincularem, como um URL para as configurações da conta na sua plataforma. Como alternativa, inclua um link para a Conta do Google, onde os usuários podem gerenciar a conta vinculada.

  4. Capacidade de mudar a conta de usuário. Sugira um método para os usuários trocarem de conta. Isso é especialmente útil se os usuários costumam ter várias contas.

    • Se um usuário precisar fechar a tela de permissão para trocar de conta, envie um erro recuperável ao Google para que ele possa fazer login na conta desejada com a vinculação do OAuth e o fluxo implícito.

  5. Inclua seu logotipo. Mostre o logotipo da sua empresa na tela de consentimento. Use as diretrizes de estilo para posicionar seu logotipo. Se você também quiser mostrar o logotipo do Google, consulte Logotipos e marcas registradas.

Esta figura mostra um exemplo de tela de consentimento com destaques para os requisitos e recomendações individuais a serem seguidos ao projetar uma tela de consentimento do usuário.
Figura 1: diretrizes de design da tela de consentimento para vinculação de contas.

Configurar para App Flip com base em OAuth

As seções a seguir descrevem os pré-requisitos para a vinculação no app baseada em OAuth e como configurar seu projeto de vinculação no app no Console para Desenvolvedores do Google Home.

Criar uma integração de nuvem para nuvem e configurar um servidor OAuth 2.0

Antes de configurar o App Flip, faça o seguinte:

Configurar a vinculação no app no Console para Desenvolvedores

A seção a seguir descreve como configurar a vinculação no app no Developer Console.

  1. Preencha todos os campos obrigatórios(*) em Vinculação de contas. Se a vinculação no app não for compatível, o OAuth normal será usado como substituto.
  2. Insira um URL para o URL de fulfillment do Cloud. O URL de fulfillment da nuvem é usado para processar as intents de casa inteligente. Marque Local fulfillment.
  3. Em Vinculação no app (opcional), marque App Android.
  4. Preencha os seguintes campos:
    • ID do aplicativo. O ID do aplicativo é um ID exclusivo que você define para seu app.
    • Assinatura de apps. Os apps Android precisam ser "assinados" com um certificado de chave pública antes de serem instalados. Para saber como conseguir a assinatura de apps, consulte Como autenticar seu cliente.
    • Intenção de autorização. Nesse campo, insira uma string que especifique sua ação de intent.
  5. Se quiser configurar o cliente, adicione escopos e clique em Adicionar escopo em Escopos (opcional).
  6. Se o cliente exigir, selecione Fazer com que o Google transmita o ID do cliente e a chave secreta pelo cabeçalho de autenticação básica HTTP.

Agora, prossiga para a próxima seção para implementar App Flip no seu app Android.

Implementar o App Flip nos seus apps nativos

Para implementar o App Flip, é necessário modificar o código de autorização do usuário no app para aceitar um link direto do Google.

OAuth-based App Flip linking (App Flip) inserts your Android app into the Google Account Linking flow. A traditional account linking flow requires the user to enter their credentials in the browser. The use of App Flip defers user sign-in to your Android app, which allows you to leverage existing authorizations. If the user is signed in to your app, they don't need to re-enter their credentials to link their account. A minimal amount of code changes are required to implement App Flip on your Android app.

In this document, you learn how to modify your Android app to support App Flip.

Try the sample

The App Flip linking sample app demonstrates an App Flip-compatible account linking integration on Android. You can use this app to verify how to respond to an incoming App Flip intent from Google mobile apps.

The sample app is preconfigured to integrate with the App Flip Test Tool for Android, which you can use to verify your Android app's integration with App Flip before you configure account linking with Google. This app simulates the intent triggered by Google mobile apps when App Flip is enabled.

How it works

The following steps are required to carry out an App Flip integration:

  1. The Google app checks if your app is installed on the device using its package name.
  2. The Google app uses a package signature check to validate that the installed app is the correct app.
  3. The Google app builds an intent to start a designated activity in your app. This intent includes additional data required for linking. It also checks to see if your app supports App Flip by resolving this intent through the Android framework.
  4. Your app validates that the request is coming from the Google app. To do so, your app checks the package signature and the provided client ID.
  5. Your app requests an authorization code from your OAuth 2.0 server. At the end of this flow, it returns either an authorization code or an error to the Google app.
  6. The Google app retrieves the result and continues with account linking. If an authorization code is provided, the token exchange happens server-to-server, the same way it does in the browser-based OAuth linking flow.

Modify your Android app to support App Flip

To support App Flip, make the following code changes to your Android app:

  1. Add an <intent-filter> to your AndroidManifest.xml file with an action string that matches the value you entered in the App Flip Intent field.

    <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. Validate the calling app's signature.

    You need to match the package name and signature for any Google apps that users may use to account link. For example, to link with Google Home and Search apps, add their package names and signatures:

    • Package name: com.google.android.apps.chromecast.app
    • Original SHA-256 lineage certificate: 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
    • Rotated Play App Signing SHA-256 certificate: 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

    and

    • Package name: com.google.android.googlequicksearchbox
    • Signature: 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

    Smart home linking requests are initiated directly by the Google Home app (GHA). If your application restricts callers and previously only allowed the Google Search app, you must add com.google.android.apps.chromecast.app and its SHA-256 certificates to your allowlist so that App Flip continues to succeed.

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

  3. Extract the client ID from the intent parameters and verify that the client ID matches the expected value.

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

  4. Upon successful authorization, return the resulting authorization code back to Google.

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

  5. If an error occurred, return an error result instead.

    // Error result
val error = Intent().apply {
    putExtra("ERROR_TYPE", 1)
    putExtra("ERROR_CODE", 1)
    putExtra("ERROR_DESCRIPTION", "Invalid Request")
}
setResult(-2, error)
finish()

Content of the launch intent

The Android intent that launches your app includes the following fields:

  • CLIENT_ID (String): Google client_id registered under your app.
  • SCOPE (String[]): A list of scopes requested.
  • REDIRECT_URI (String): The redirect URL.

Content of the response data

The data returned to the Google app is set in your app by calling setResult(). This data includes the following:

  • AUTHORIZATION_CODE (String): The authorization code value.
  • resultCode (int): Communicates the success or failure of the process and takes one of the following values:
    • Activity.RESULT_OK: Indicates success; an authorization code is returned.
    • Activity.RESULT_CANCELLED: A recoverable error. Signals that the user has cancelled the process. In this case, the Google app will attempt account linking again using your authorization URL.
    • -2: Indicates that an error has occurred. Different types of errors are described below.
  • ERROR_TYPE (int): The type of error, which takes one of the following values:
    • 1: Recoverable error: The Google app will attempt account linking using the authorization URL.
    • 2: Unrecoverable error: The Google app aborts account linking.
    • 3: Invalid or missing request parameters.
  • ERROR_CODE (int): An integer representing the nature of the error. To see what each error code means, refer to the table of error codes.

  • ERROR_DESCRIPTION (String, optional): Human-readable status message describing the error.

A value for the AUTHORIZATION_CODE is expected when resultCode == Activity.RESULT_OK. In all other cases, the value for AUTHORIZATION_CODE needs to be empty. If resultCode == -2, then the ERROR_TYPE value is expected to be populated.

Table of error codes

The table below shows the different error codes and whether each is a recoverable or unrecoverable error:

Error code Meaning Recoverable Unrecoverable
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 ✔

For all error codes, you must return the error result via setResult to ensure the appropriate fallback is triggered.

Teste o App Flip no seu dispositivo

Agora que você criou uma integração de nuvem para nuvem e configurou a vinculação no app no console e no app, é possível testar a vinculação no app no seu dispositivo móvel. Use o app Google Home para testar a vinculação no app.

Para testar o App Flip no app Google Home, siga estas etapas:

  1. Acesse o Developer Console e selecione seu projeto.
  2. Acesse Cloud-to-cloud > Test.
  3. Acione o fluxo de vinculação de contas no app Home:
    1. Abra o Google Home app (GHA).
    2. Clique no botão +.
    3. Clique em Configurar dispositivo.
    4. Clique em Já tem algo configurado?
    5. Selecione sua integração de nuvem para nuvem na lista de provedores. Ele vai ter o prefixo "[test]" na lista. Quando você selecionar sua integração [teste] na lista, o app será aberto.
    6. Verifique se o app foi iniciado e comece a testar o fluxo de autorização.
Anterior
Criar uma integração de nuvem para nuvem
Avançar
iOS