App Flip para iOS

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

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 em Informações do cliente OAuth. Se o App Flip não for compatível, o OAuth normal será usado como alternativa.
  2. Em Usar seu app para vinculação de contas(opcional), marque Ativar para iOS.
  3. Preencha o campo Link universal. Para mais informações sobre links universais, consulte Como permitir que apps e sites vinculem ao seu conteúdo.
  4. Se quiser configurar o cliente, adicione escopos e clique em Adicionar escopo em Configurar o cliente (opcional).
  5. Clique em Salvar.

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

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) abre seu app iOS em um app do Google para ajudar o usuário do app do Google a vincular a conta com mais facilidade. Você precisa fazer pequenas mudanças no código do seu app iOS para implementar esse recurso.

Neste documento, você vai aprender a modificar seu app iOS 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 contas no iOS que é compatível com a vinculação no app. Use este app para verificar como responder a um link universal de vinculação no app recebido de apps para dispositivos móveis do Google.

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

Como funciona

Confira as etapas do fluxo que o app do Google e seu app seguem quando a vinculação no app ocorre:

  1. O app do Google tenta abrir o link universal do seu app. Ele pode abrir seu app se estiver instalado no dispositivo do usuário e associado ao link universal. Consulte Suporte a links universais para mais detalhes.

  2. O app verifica se os parâmetros client_id e redirect_uri codificados no URL recebido correspondem ao link universal esperado do Google.

  3. O app solicita um código de autorização do servidor OAuth2. No final desse fluxo, seu app retorna um código de autorização ou um erro para o app do Google. Para fazer isso, ele abre o link universal do Google com parâmetros anexados para o código de autorização ou erro.

  4. O app do Google processa o link universal do Google recebido e continua com o restante do fluxo. Se um código de autorização for fornecido, a vinculação será concluída imediatamente. A troca de tokens acontece de servidor para servidor, da mesma forma que no fluxo de vinculação do OAuth baseado no navegador. Se um código do erro for retornado, o fluxo de vinculação vai continuar com as opções alternativas.

Modificar o app iOS 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 iOS:

  1. Processe NSUserActivityTypeBrowsingWeb no delegado do app.
  2. Capture os parâmetros redirect_uri e state do URL para usar mais tarde.
  3. Verifique se redirect_uri corresponde a este formato: 
    https://oauth-redirect.googleusercontent.com/a/GOOGLE_APP_BUNDLE_ID
https://oauth-redirect-sandbox.googleusercontent.com/a/GOOGLE_APP_BUNDLE_ID

  4. Verifique se o ID do cliente corresponde ao valor esperado. Use o seguinte exemplo de código:

    func application(_ application: UIApplication,
                 continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([Any]?) -> Void) -> Bool
{
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
        let incomingURL = userActivity.webpageURL,
        let components = URLComponents(url: incomingURL, resolvingAgainstBaseURL: false),
        let params = components.queryItems else {
            return false
    }

    if let clientId = params.filter({$0.name == "client_id"}).first?.value,
        let state = params.filter({$0.name == "state"}).first?.value,
        let redirectUri = params.filter({$0.name == "redirect_uri"}).first?.value {

        // Save the redirect_uri and state for later...

        // Verify the client id
        return (clientId == GOOGLE_CLIENT_ID)
    } else {
        // Missing required parameters
        return false
    }
}

  5. Após a autorização, chame o URI de redirecionamento com o código de autorização. Use o seguinte exemplo de código:

    func returnAuthCode(code: String, state: String, redirectUri: String) {
    var redirectURL = URL(string: redirectUri)
    var components = URLComponents(url: redirectURL, resolvingAgainstBaseURL: false)

    // Return the authorization code and original state
    let paramAuthCode = URLQueryItem(name: "code", value: code)
    let paramState = URLQueryItem(name: "state", value: state)
    components?.queryItems = [paramAuthCode, paramState]
    if let resultURL = components?.url {
        UIApplication.shared.open(
            resultURL,
            options: [UIApplicationOpenURLOptionUniversalLinksOnly : true],
            completionHandler: nil)
    }
}

  6. Se ocorrer um erro, anexe um resultado de erro ao URI de redirecionamento. Use o seguinte exemplo de código:

    func returnError(redirectUri: String) {
    var redirectURL = URL(string: redirectUri)
    var components = URLComponents(url: redirectURL, resolvingAgainstBaseURL: false)

    // Return the authorization code and original state
    let paramError = URLQueryItem(name: "error", value: "invalid_request")
    let paramDescription = URLQueryItem(name: "error_description", value: "Invalid Request")
    components?.queryItems = [paramError, paramDescription]
    if let resultURL = components?.url {
        UIApplication.shared.open(
            resultURL,
            options: [UIApplicationOpenURLOptionUniversalLinksOnly : true],
            completionHandler: nil)
    }
}

Quando aberto pelo app do Google, o link universal do seu app inclui os seguintes parâmetros de consulta:

  • client_id (String): o client_id do Google registrado no seu app.
  • scope (List of String): uma lista de escopos solicitados separados por espaços.
  • state (String): um valor de uso único usado pelo Google para verificar se o resultado da autorização é uma resposta à solicitação de saída do Google.
  • redirect_uri (String): o link universal do Google. O URI "flip" para abrir o app do Google e transmitir resultados.

Parâmetros usados quando o resultado da autorização é retornado com sucesso:

  • code (String): o valor do código de autorização, se disponível.
  • state (String): o valor exato recebido do link universal de entrada.

Parâmetros usados quando o resultado da autorização não é retornado:

  • error (String), com os seguintes valores:

    • cancelled: um erro recuperável. O app do Google vai tentar vincular a conta usando o URL de autorização. Alguns exemplos são: falha no login do usuário, dispositivo off-line ou tempo limite de conexão excedido.
    • unrecoverable: um erro irrecuperável. Por exemplo, o usuário tenta vincular uma conta desativada.O app do Google vai cancelar a vinculação.
    • invalid_request: os parâmetros da solicitação são inválidos ou estão ausentes. Este é um erro recuperável. O app do Google vai tentar vincular a conta usando o URL de autorização.
    • access_denied: o usuário rejeita o pedido de consentimento. Esse é um erro não recuperável. O app do Google cancela a vinculação.

  • error_description (String, opcional): uma mensagem de erro fácil de usar.

Para todos os tipos de erro, é necessário retornar os dados de resposta ao REDIRECT_URI especificado para garantir que o substituto adequado seja acionado.

Modificar o endpoint de autorização para oferecer suporte à vinculação no app

Configure sua plataforma para aceitar solicitações usando os URLs de redirecionamento de vinculação no app do Google:

  • App Google Home 
    https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast.dev
https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast.enterprise
https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast.dev
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast.enterprise
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast
  • App Google Assistente 
    https://oauth-redirect.googleusercontent.com/a/com.google.OPA.dev
https://oauth-redirect.googleusercontent.com/a/com.google.OPA.enterprise
https://oauth-redirect.googleusercontent.com/a/com.google.OPA
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA.dev
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA.enterprise
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA

Para o Google Home app (GHA), a vinculação de conta de casa inteligente usa os URLs de redirecionamento com.google.Chromecast. Verifique se o servidor de autorização permite esses URLs de redirecionamento.

Verifique se client_id e o URL especificado pelo parâmetro redirect_uri correspondem aos valores esperados quando uma solicitação é recebida. Se a verificação do cliente falhar, retorne o erro invalid_request para o redirect_uri.

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
Android
Avançar
Identificar e sincronizar