Verificação entre apps

Os emissores podem oferecer a verificação entre apps como uma opção para concluir um desafio de ID&V de caminho amarelo ao provisionar um token. A verificação entre apps é configurada por seu provedor de serviços de token (TSP) e não requer nenhuma configuração por parte da equipe do Google Pay. Nesta página, explicamos como seu app interage com o app Carteira do Google, com base nas instruções de provisionamento que recebemos de seu TSP.

Quando os usuários optarem por ativar a verificação entre apps, a Carteira do Google vai invocar o app do emissor chamando a Activity do Android especificada pelo emissor na configuração do TSP. Depois que o usuário tiver verificado sua identidade, o app do emissor retorna o controle para a Carteira do Google para concluir o fluxo de provisionamento.

Se o app não estiver instalado no dispositivo do usuário, a Carteira do Google vai abrir a página da Google Play Store do app. Depois de instalar o app do emissor, o usuário precisa reiniciar o fluxo.

Para oferecer suporte à verificação entre apps, você vai precisar:

• definir configurações do TSP para ativar o fluxo de app para app;
• atualizar seu app para oferecer suporte ao fluxo de app para app.

O fluxo mostra uma experiência do usuário abstrata para o processo de verificação entre apps:

Configurações do TSP

Os emissores precisam fornecer os parâmetros abaixo ao TSP deles. O Google Pay recebe esses parâmetros do TSP durante o processo de tokenização e os utiliza para chamar seu app.

Saiba mais sobre como enviar e permitir intents no Android.

Desenvolvimento de apps

Quando um usuário seleciona o método entre apps para verificar sua identidade, o emissor do app precisa:

1. receber a intent da Carteira do Google;
2. autenticar o titular do cartão;
3. ativar o token;
4. retornar o usuário à Carteira do Google chamando activity.setResult(RESULT_OK, ...).

Receber a intent

Quando um usuário opta por verificar sua identidade usando o app do emissor, a Carteira do Google chama seu app usando o nome do pacote, a ação e o EXTRA_TEXT fornecido à Carteira do Google pelo TSP. Para receber o Intent da Carteira do Google, você precisa atualizar o manifesto do app e criar uma atividade para ativar o token.

Manifesto do app

Os emissores precisam atualizar o manifesto do Android no app para dispositivos móveis para tratar o Action de modo que a Carteira do Google possa chamá-lo durante o fluxo de app para app.

Depois que o manifesto do seu app tiver sido atualizado, a Carteira do Google poderá chamar seu app para iniciar a atividade de ativação do token no seu app.

<activity android:name="AppToAppActivity">
  <!-- This activity handles App To App ACTIVATE_TOKEN action -->
  <intent-filter>
    <action android:name="com.example.bank.action.ACTIVATE_TOKEN"/>
    <category android:name="android.intent.category.DEFAULT"/>
  </intent-filter>
</activity>

Saiba mais sobre intents do Android na documentação para desenvolvedores do Android e na referência para desenvolvedores do Android.

Atividade de ativação do token

Para concluir a ativação, seu app precisa iniciar uma atividade para concluir a ativação do token usando os parâmetros de ativação passados no Intent. O exemplo de código a seguir demonstra como acessar os dados do EXTRA_TEXT no Intent.

/*
 * Within issuer's mobile app AppToAppActivity
 */

// Validate caller is Google Wallet
// see Security Considerations section below

String data = getIntent().getStringExtra(Intent.EXTRA_TEXT);

// Parse base64 to retrieve the activation parameters as a JSON object in a String
String decodedData = new String(base64.decodeBase64(data));

// Read the JSON string
ObjectMapper mapper = new ObjectMapper();
JsonNode node = mapper.readTree(decodedData);

// Extract the activation parameters
String tokenRef = node.get("param0").asText());
String tokenParam = node.get("param1").asText());
// etc.

// Authenticate the user
...

Testar com o Android Debug Bridge (adb)

É possível simular a intent enviada pela Carteira do Google usando a ferramenta Android Debug Bridge (adb) na linha de comando. Isso testa o processamento de intents do seu app de maneira isolada. Use o comando a seguir, substituindo os valores do marcador pela sua configuração específica:

  adb shell am start \
    -a com.your.app.package.a2a \
    -p com.your.app.package \
    --es android.intent.extra.TEXT 'yourBase64EncodedExtraTextFromTSP'

Nesse comando:

• -a: corresponde à ação configurada com seu TSP.
• -p: é o nome do pacote do seu aplicativo.
• --es: especifica um valor de string extra. Use android.intent.extra.TEXT como a chave e forneça o payload JSON codificado em Base64 como o valor.

Os valores de "Ação" e "Pacote" dependem da sua configuração com o TSP, conforme observado no item "Configuração do TSP".

Se o comando for bem-sucedido, a atividade designada do app será iniciada. Se isso falhar, a mensagem de erro geralmente indica que a atividade não foi encontrada, apontando para uma incompatibilidade no nome do pacote ou na ação. Isso ajuda a confirmar se o app está configurado corretamente para receber a intent de app para app antes de testar o fluxo completo de ponta a ponta.

Solução de problemas: a intent abre a Play Store

Quando um usuário seleciona a verificação entre apps, se a Carteira do Google abrir a Play Store em vez do seu app, isso indica que a Carteira não conseguiu resolver a intent do Android necessária para iniciar o app.

Para abrir o app, verifique o seguinte:

• Incompatibilidade de nome do pacote: o nome do pacote do app instalado no dispositivo precisa corresponder exatamente ao nome do pacote configurado com seu TSP. Um erro comum é testar com um build de depuração, que pode ter um nome de pacote diferente (por exemplo, com.example.app.debug) do que o nome do pacote de produção (com.example.app) configurado com o TSP. O nome do pacote diferencia maiúsculas de minúsculas.
• Configuração do manifesto: verifique se o AndroidManifest.xml do app está configurado corretamente para processar a ação de intent. A tag <action> no <intent-filter> do manifesto precisa ser uma correspondência exata, caractere por caractere com a string de ação configurada com seu TSP.
• Configuração do TSP: o nome do pacote e a ação são enviados ao Google Pay pelo seu TSP. As correções nesses valores precisam ser feitas nos dados enviados ao TSP ou no portal de configuração dele. A Carteira do Google não ajusta esses valores, eles são transmitidos. Para mais informações, consulte a documentação do TSP.

Ativar o token

Há duas maneiras de ativar tokens:

• chamando as APIs do servidor TSP para ativar o token diretamente;
• conseguindo um código de ativação do TSP e passando-o no resultado do Activity.

Ativar usando APIs do servidor TSP

Quando o app para dispositivos móveis do banco emissor do cartão usa a API do TSP para ativar o token, o app do banco emissor do cartão recebe o Intent, autentica o titular do cartão e ativa o token ao chamar a API do TSP. No final desse fluxo, você indica à Carteira do Google se a ativação foi bem-sucedida ou não ao retornar o usuário ao Google Wallet. Consulte a documentação técnica do seu TSP para detalhes sobre como ativar tokens usando as APIs de servidor.

Na ativação pela API do TSP, seu app não retorna um código para a Carteira do Google e a ela acontece "fora da banda", da perspectiva do Google Pay.

Exemplo de código para retornar o usuário à Carteira do Google depois que o processo de ativação for concluído usando a técnica da API do TSP.

Intent resultIntent = new Intent();

resultIntent.putExtra("BANKING_APP_ACTIVATION_RESPONSE", "approved");
// or "declined", or "failure"

activity.setResult(RESULT_OK, resultIntent);

Ativar usando o resultado de intent do Android e o código de ativação do TSP

Quando o app para dispositivos móveis do banco emissor do cartão recebe um código de ativação do TSP e o retorna à Carteira do Google, o app do emissor retorna um código de ativação à Carteira do Google usando um resultado de intent.

Esse método exige um código de ativação gerado pelo TSP. Consulte seu TSP para saber se esse método é compatível e como gerar um código de ativação, também chamado de código de autenticação ou valor de autenticação de tokenização (TAV, na sigla em inglês).

A seguir, há um exemplo de código para retornar o usuário à Carteira do Google com um código de ativação.

Intent resultIntent = new Intent();

resultIntent.putExtra("BANKING_APP_ACTIVATION_RESPONSE", "approved");
// or "declined", or "failure"

// if "approved", also pass the code
resultIntent.putExtra("BANKING_APP_ACTIVATION_CODE", activationCode);

activity.setResult(RESULT_OK, resultIntent);

Segurança do app para dispositivos móveis

O app para dispositivos móveis do banco emissor precisa aderir ao modelo de segurança do Android, principalmente no que se refere ao uso de intents. Após receber a intent, use Activity.getCallingPackage para validar se a atividade de chamada é mesmo da Carteira do Google, como indicado abaixo.

// Validate caller is Google Wallet (Google Play Services)
if ("com.google.android.gms".equals(getCallingPackage())) {
    // Proceed with token activation
    ...
} else {
    // Abort token activation: handle error
    ...
}

Certifique-se de que seu app para dispositivos móveis faça o seguinte:

• autentica a identidade do titular do cartão;
• recebe o consentimento do titular do cartão para todas as solicitações de digitalização;
• verifica se a digitalização se refere à conta do titular do cartão correto.

Consulte a documentação técnica do seu TSP sobre ativação do token e o site para desenvolvedores Android sobre envio, permissão e recebimento de Intents.