Virar app para Android

Depois de implementar o OAuth 2.0, você tem a opção de configurar o App Flip com base em OAuth. Isso permite que os usuários do Android vinculem as contas do sistema de autenticação mais rapidamente às Contas do Google deles. As seções a seguir descrevem como projetar e implementar App Flip para sua ação smart home.

Diretrizes de design

Nesta seção, descrevemos os requisitos de design e as recomendações para a tela de consentimento de vinculação de contas do Flip App. Depois que o Google chamar o app, ele exibirá a tela de consentimento para o usuário.

Requisitos

  1. Você precisa informar que a conta do usuário está sendo vinculada ao Google, e não a um produto específico, como o Google Home ou o Google Assistente.

Recomendações

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

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

  2. Dados a serem compartilhados. Usar uma linguagem clara e concisa para dizer ao usuário quais dados são exigidos pelo Google e por quê.

  3. Call-to-action clara. Defina uma call-to-action clara na tela de consentimento, como "Concordar e vincular". Isso ocorre porque os usuários precisam entender quais dados precisam ser compartilhados com o Google para vincular as contas deles.

  4. Opção de cancelar. Forneça uma maneira de o usuário voltar ou cancelar, se eles optarem por não vincular.

  5. Capacidade de desvincular. Ofereça um mecanismo para os usuários desvincularem, como um URL das configurações da conta na sua plataforma. Também é possível incluir um link para a Conta do Google, em que os usuários podem gerenciar a conta vinculada.

  6. Capacidade de alterar a conta de usuário. Sugira um método para os usuários trocarem de conta. Isso é útil principalmente se os usuários tendem a ter várias contas.

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

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

A figura mostra um exemplo de tela de consentimento com chamadas para os requisitos e recomendações individuais que serão seguidas 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 o App Flip com base em OAuth

As seções a seguir descrevem os pré-requisitos do App Flip com base em OAuth e como configurá-lo no console do Actions.

Criar uma ação de casa inteligente e configurar um servidor OAuth 2.0

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

Configurar o App Flip no Console do Actions

A seção a seguir descreve como configurar o App Flip no Console do Actions.

  1. Preencha todos os campos em Informações do cliente OAuth. Se o App Flip não for compatível, o OAuth normal será usado como substituto.
  2. Em Usar seu aplicativo para vinculação de conta (opcional), marque Ativar para Android.
  3. Preencha os seguintes campos:
    • ID do aplicativo. O ID do aplicativo é um ID exclusivo que você define para seu app.
    • Assinatura do app. Aplicativos Android precisam ser "assinados" com um certificado de chave pública antes de serem instalados. Para mais informações sobre como conseguir a assinatura do app, consulte Como autenticar seu cliente.
    • Intent de autorização. Nesse campo, insira uma string que especifique sua ação de intent.
  4. Se você quiser configurar o cliente, adicione escopos e clique em Adicionar escopo em Configurar seu cliente (opcional).
  5. Clique em Salvar.

Implementar o App Flip nos seus apps Android

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

A vinculação de versões de apps baseadas em OAuth (Flip de apps) insere seu app Android no fluxo de vinculação de Contas do Google. Um fluxo tradicional de vinculação de contas exige que o usuário insira as credenciais no navegador. O uso do App Flip adia o login do usuário para o app Android, o que permite aproveitar as autorizações existentes. Se o usuário estiver conectado ao seu app, ele não precisará digitar as credenciais novamente para vincular a conta. Uma quantidade mínima de mudanças de código é necessária para implementar o App Flip no seu app Android.

Neste documento, você vai aprender a modificar o app Android para oferecer suporte ao App Flip.

Testar a amostra

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

O app de exemplo está pré-configurado para integração com a App Flip Test Tool para Android, que pode ser usada para verificar a integração do seu app Android com o App Flip antes de configurar a vinculação de contas com o Google. Este app simula a intent acionada por apps para dispositivos móveis do Google quando o App Flip está ativado.

Como funciona

As etapas a seguir são necessárias para realizar uma integração do App Flip:

  1. O Google app verifica se o app está instalado no dispositivo usando o nome do pacote.
  2. O Google app usa uma verificação de assinatura de pacote para validar se o app instalado é o correto.
  3. O Google app cria uma intent para iniciar uma atividade designada no app. Essa intent inclui outros dados necessários para a vinculação. Ele também verifica se o app é compatível com o App Flip ao resolver essa intent pelo framework do Android.
  4. O app valida se a solicitação vem do Google app. Para fazer isso, o app 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 Google app.
  6. O Google app recupera o resultado e continua com a vinculação da conta. Se um código de autorização for fornecido, a troca de tokens acontecerá de servidor para servidor, da mesma forma que no fluxo de vinculação de OAuth baseado no navegador.

Modificar seu app Android para oferecer suporte ao Flip para apps

Para oferecer compatibilidade com o App Flip, faça as seguintes mudanças no código do seu app Android:

  1. Adicione uma <intent-filter> ao arquivo AndroidManifest.xml com uma string de ação que corresponda ao valor inserido no campo Intenção do Flip do 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.

    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. Extrair o ID do cliente dos parâmetros da intent e verificar se o ID do cliente corresponde ao 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. Após a autorização, retorne o código de autorização resultante de volta ao 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 lançamento

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

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

Conteúdo dos dados da resposta

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

  • AUTHORIZATION_CODE (String): o valor do código de autorização.
  • resultCode (int): comunica o sucesso ou falha do processo e usa um dos seguintes valores:
    • Activity.RESULT_OK: indica sucesso. Um código de autorização é retornado.
    • Activity.RESULT_CANCELLED: indica que o usuário cancelou o processo. Nesse caso, o Google app tentará vincular a conta usando o URL de autorização.
    • -2: indica que ocorreu um erro. Diferentes tipos de erros são descritos abaixo.
  • ERROR_TYPE (int): o tipo de erro, que recebe um dos seguintes valores:
    • 1: erro recuperável: o Google app tentará vincular a conta usando o URL de autorização.
    • 2: erro irrecuperável: o Google app 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 ver o que cada código de erro significa, consulte a tabela de códigos de erro.

  • ERROR_DESCRIPTION (String, opcional): mensagem de status legível descrevendo o erro.

Espera-se um valor de AUTHORIZATION_CODE quando resultCode == Activity.RESULT_OK. Em todos os outros casos, o valor de AUTHORIZATION_CODE precisa estar vazio. Se resultCode == -2, o valor ERROR_TYPE deverá ser preenchido.

Tabela de códigos de erro

A tabela abaixo mostra os diferentes códigos de erro e se cada um é um erro recuperável ou 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 correto seja acionado.

Testar o App Flip no dispositivo

Agora que você criou uma ação e configurou o App Flip no console e no app, pode testá-lo no dispositivo móvel. Você pode usar o app Google Assistente ou o app Google Home para testar o App Flip.

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

  1. Acesse o console do Actions e selecione seu projeto.
  2. Clique em Testar na navegação superior.
  3. Acione o fluxo de vinculação da conta no app Google Assistente:
    1. Abra o app Google Assistente.
    2. Clique em Configurações.
    3. Na guia do Assistente, clique em Automação residencial.
    4. Clique em Add(+).
    5. Selecione sua ação na lista de provedores. Ele será prefixado com “[test]” na lista. Quando você selecionar a ação [test] na lista, seu app será aberto.
    6. Verifique se o aplicativo foi lançado e comece a testar o fluxo de autorização.

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

  1. Acesse o console do Actions e selecione seu projeto.
  2. Clique em Testar na navegação superior.
  3. Acione o fluxo de vinculação da conta no app Google Home:
    1. Abra o app Google Home.
    2. Clique no botão +.
    3. Clique em Configurar dispositivo.
    4. Clique em Já tem algo configurado?
    5. Selecione sua ação de casa inteligente na lista de provedores. Ele será prefixado com “[test]” na lista. Quando você selecionar a ação [test] na lista, seu app será aberto.
    6. Verifique se o aplicativo foi lançado e comece a testar o fluxo de autorização.
Anterior
Criar um projeto do Actions
Próxima
Identificar e sincronizar