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.

A vinculação no app baseada em OAuth (App Flip) insere seu app Android no fluxo de vinculação da Conta do Google. Em um fluxo tradicional de vinculação de contas, o usuário precisa inserir as credenciais no navegador. O uso da vinculação no app adia o login do usuário no app Android, o que permite aproveitar as autorizações existentes. Se o usuário estiver conectado ao seu app, ele não precisará inserir as credenciais novamente para vincular a conta. É necessário fazer poucas mudanças no código para implementar a vinculação no app no seu app Android.

Neste documento, você vai aprender a modificar seu app Android para que ele seja compatível com a vinculação no app.

Testar o exemplo

O app de exemplo de vinculação no app demonstra uma integração de vinculação de conta compatível com a vinculação no app no Android. Você pode usar esse app para verificar como responder a uma intent de vinculação no app recebida de apps do Google para dispositivos móveis.

O app de exemplo é pré-configurado para se integrar à ferramenta de teste de vinculação no app para Android, que pode ser usada para verificar a integração do seu app Android com a vinculação no app antes de configurar a vinculação de contas com o Google. Esse app simula a intent acionada pelos apps para dispositivos móveis do Google quando a vinculação no app está ativada.

Como funciona

As etapas a seguir são necessárias para realizar uma integração de vinculação no app:

  1. O Google app verifica se o app está instalado no dispositivo usando o nome do pacote.
  2. O app do Google usa uma verificação de assinatura de pacote para validar se o app instalado é o correto.
  3. O app Google cria uma intent para iniciar uma atividade designada no seu app. Essa intent inclui dados adicionais necessários para a vinculação. Ele também verifica se o app é compatível com a vinculação no app resolvendo essa intent pelo framework do Android.
  4. Seu app valida que a solicitação vem do app do Google. Para isso, ele verifica a assinatura do pacote e o ID do cliente fornecido.
  5. O app solicita um código de autorização do servidor OAuth 2.0. No final desse fluxo, ele retorna um código de autorização ou um erro para o app do Google.
  6. O app do Google recupera o resultado e continua com a vinculação da conta. Se um código de autorização for fornecido, a troca de tokens vai acontecer de servidor para servidor, da mesma forma que no fluxo de vinculação do OAuth baseado em navegador.

Modificar o app Android para oferecer suporte à Vinculação no App

Para oferecer suporte à Vinculação no App, faça as seguintes mudanças no código do seu app Android:

  1. Adicione um <intent-filter> ao arquivo AndroidManifest.xml com uma string de ação que corresponda ao valor inserido no campo Intent de vinculação no 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. Valide a assinatura do app de chamada.

    É necessário corresponder o nome do pacote e a assinatura de todos os apps do Google que os usuários podem usar para vincular contas. Por exemplo, para vincular aos apps Google Home e Pesquisa, adicione os nomes de pacotes e as assinaturas deles:

    • Nome do pacote: com.google.android.apps.chromecast.app
    • Certificado de linhagem 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 da Assinatura de apps do Google Play alternado: 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

    e

    • Nome do pacote: com.google.android.googlequicksearchbox
    • Assinatura: 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

    As solicitações de vinculação de casa inteligente são iniciadas diretamente pelo Google Home app (GHA). Se o aplicativo restringe os autores de chamadas e anteriormente só permitia o app Pesquisa Google, adicione com.google.android.apps.chromecast.app e os certificados SHA-256 dele à lista de permissões para que a vinculação no app continue funcionando.

    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. Extraia o ID do cliente dos parâmetros da intent e verifique se ele corresponde ao 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...
    }
}

  4. Após a autorização, retorne o código de autorização resultante para o Google.

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

  5. Se ocorrer um erro, retorne um resultado de erro.

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

Conteúdo da intent de inicialização

A intent do Android que inicia o app inclui os seguintes campos:

  • CLIENT_ID (String): o client_id do Google registrado no seu app.
  • SCOPE (String[]): uma lista de escopos solicitados.
  • REDIRECT_URI (String): o URL de redirecionamento.

Conteúdo dos dados de resposta

Os dados retornados ao app do Google são definidos no seu app chamando setResult(). Esses dados incluem o seguinte:

  • AUTHORIZATION_CODE (String): o valor do código de autorização.
  • resultCode (int): comunica o sucesso ou a falha do processo e assume um dos seguintes valores:
    • Activity.RESULT_OK: indica sucesso. Um código de autorização é retornado.
    • Activity.RESULT_CANCELLED: um erro recuperável. Sinaliza que o usuário cancelou o processo. Nesse caso, o app do Google vai tentar vincular a conta novamente usando seu URL de autorização.
    • -2: indica que ocorreu um erro. Os diferentes tipos de erros são descritos abaixo.
  • ERROR_TYPE (int): o tipo de erro, que usa um dos seguintes valores:
    • 1: erro recuperável. O app do Google vai tentar vincular a conta usando o URL de autorização.
    • 2: erro irrecuperável: o app do Google cancela a vinculação da conta.
    • 3: parâmetros de solicitação inválidos ou ausentes.
  • ERROR_CODE (int): um número inteiro que representa a natureza do erro. Para saber o que cada código do erro significa, consulte a tabela de códigos do erro.

  • ERROR_DESCRIPTION (String, opcional): mensagem de status legível por humanos que descreve o erro.

Um valor para AUTHORIZATION_CODE é esperado quando resultCode == Activity.RESULT_OK. Em todos os outros casos, o valor de AUTHORIZATION_CODE precisa estar vazio. Se for resultCode == -2, o valor ERROR_TYPE precisa ser preenchido.

Tabela de códigos do erro

A tabela abaixo mostra os diferentes códigos do erro e se cada um é recuperável ou erro irrecuperável:

Código do erro Significado Recuperável Irrecuperável
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 os códigos de erro, é necessário retornar o resultado do erro usando setResult para garantir que o substituto adequado seja acionado.

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