O Google tem o compromisso de promover a igualdade racial para as comunidades negras. Saiba como.

Esta página foi traduzida pela API Cloud Translation.

Acesso rápido à carteira

O recurso de acesso rápido à carteira, disponível no Android 11, permite que o usuário acesse cartões de pagamento e cartões relevantes diretamente no menu liga/desliga. Os principais casos de uso incluem selecionar a forma de pagamento adequada antes de realizar uma transação em um terminal NFC e acessar rapidamente voos e outros cartões para eventos futuros.

No Android 12 e versões mais recentes, o recurso Acesso rápido à carteira está disponível na aba, como mostrado nas Figuras 1 e 2.

Recurso de Acesso rápido à Carteira na aba de notificações — **Figura 1.** Recurso de Acesso rápido à Carteira (dispositivo bloqueado).

Recurso de acesso rápido à carteira na sombra — **Figura 2.** Recurso de Acesso rápido à Carteira (dispositivo desbloqueado).

No Android 11, o recurso está disponível no menu de desligamento, conforme mostrado na Figura 3.

**Figura 3.** Recurso de acesso rápido à carteira no menu de desligamento.

Requisitos

O dispositivo precisa ter NFC para usar o recurso de acesso rápido à Carteira. O recurso é vinculado ao QuickAccessWalletService do app padrão de pagamento por aproximação, o que significa que o dispositivo também precisa ser compatível com a emulação de cartão com base em host (HCE, na sigla em inglês) da NFC.

Visão geral do recurso

A Carteira de acesso rápido tem duas partes: a interface e o provedor de cartão.

No Android 12 ou versões mais recentes, a interface da Carteira é executada na interface do sistema e está localizada em frameworks/base/packages/SystemUI/src/com/android/systemui/wallet. No Android 11, a interface da Carteira, localizada em platform/packages/apps/QuickAccessWallet, precisa ser instalada e incluída na lista de permissões.

O provedor de cartão do Acesso rápido à carteira é o app de pagamento por aproximação padrão. Os usuários podem ter vários apps de pagamento por aproximação instalados simultaneamente, mas apenas o app de pagamento por aproximação padrão pode mostrar cartões no menu Liga/Desliga. É possível especificar qual app de pagamento NFC é definido como padrão inicialmente, mas os usuários podem selecionar um app diferente nas configurações. Se apenas um app de pagamento por aproximação estiver instalado, ele vai se tornar o padrão automaticamente. Consulte CardEmulationManager.

Implementação

Para fornecer cartões à interface da Carteira de acesso rápido, os apps de pagamento NFC precisam implementar QuickAccessWalletService. Os apps de pagamento precisam incluir uma entrada de manifesto que anuncie o serviço.

Para garantir que apenas a IU do sistema possa se vincular a QuickAccessWalletService, o app de pagamento por NFC precisa exigir a permissão android.permission.BIND_QUICK_ACCESS_WALLET_SERVICE. Exigir essa permissão garante que somente a interface do sistema possa se vincular a QuickAccessWalletService.

<service
     android:name=".MyQuickAccessWalletService"
     android:label="@string/my_default_tile_label"
     android:icon="@drawable/my_default_icon_label"
     android:logo="@drawable/my_wallet_logo"
     android:permission="android.permission.BIND_QUICK_ACCESS_WALLET_SERVICE">
     <intent-filter>
         <action android:name="android.service.quickaccesswallet.QuickAccessWalletService" />
         <category android:name="android.intent.category.DEFAULT"/>
     </intent-filter>
     <meta-data android:name="android.quickaccesswallet"
          android:resource="@xml/quickaccesswallet_configuration" />
     <meta-data
          android:name="android.quickaccesswallet.tile"
          android:resource="@drawable/my_default_tile_icon"/>
</service>

Outras informações sobre a carteira são incluídas no arquivo XML vinculado:

<quickaccesswallet-service
   xmlns:android="http://schemas.android.com/apk/res/android"
   android:settingsActivity="com.example.android.SettingsActivity"
   android:shortcutLongLabel="@string/my_wallet_empty_state_text"
   android:shortcutShortLabel="@string/my_wallet_button_text"
   android:targetActivity="com.example.android.WalletActivity"/>

Em seguida, o app de pagamento precisa implementar QuickAccessWalletService:

public class MyQuickAccessWalletService extends QuickAccessWalletService {

    @Override
    public void onWalletCardsRequested(
            GetWalletCardsRequest request,
            GetWalletCardsCallback callback) {
        GetWalletCardsResponse response = // generate response
        callback.onSuccess(response);
    }

    @Override
    public void onWalletCardSelected(SelectWalletCardRequest request) {
        // selecting a card should ensure that it is used when making an NFC payment
    }

    @Override
    public void onWalletDismissed() {
        // May un-select card if the wallet app has the concept of a 'default'
        // payment method
    }
}

Se HostApduService começar a processar uma transação NFC e, como consequência, iniciar uma atividade para mostrar o progresso e o resultado do pagamento, ele também tentará buscar uma referência ao QuickAccessWalletService vinculado e chamar QuickAccessWalletService#sendEvent com um tipo de evento de TYPE_NFC_PAYMENT_STARTED. Isso faz com que a interface da Carteira de acesso rápido seja encerrada, permitindo que o usuário tenha uma visualização desobstruída da atividade de pagamento.

Para ver mais documentação sobre como implementar QuickAccessWalletService, consulte QuickAccessWalletService e o teste CTS TestQuickAccessWalletService.

Ativar a interface da Carteira de acesso rápido no Android 11

Para configurar a disponibilidade da Carteira de acesso rápido no menu liga/desliga no Android 11, inclua o destino QuickAccessWallet no build e ative o plug-in globalactions.wallet adicionando a linha em negrito no exemplo de código abaixo ao arquivo overlay/frameworks/base/packages/SystemUI/res/values/config.xml.

<resources>
    ...
    <!-- SystemUI Plugins that can be loaded on user builds. -->
    <string-array name="config_pluginWhitelist" translatable="false">
        <item>com.android.systemui</item>
        <item>com.android.systemui.plugin.globalactions.wallet</item>
    </string-array>
</resources>

Especifique o app de pagamento por NFC padrão no arquivo de configuração de configurações usando def_nfc_payment_component.

O app de pagamento por NFC padrão precisa expor QuickAccessWalletService para fornecer cartões à Carteira de acesso rápido. Se o app de pagamento por aproximação padrão não exportar esse serviço, a interface da carteira será oculta.

Detalhes de implementação do QuickAccessWalletService

QuickAccessWalletService tem três métodos abstratos que precisam ser implementados: onWalletCardsRequested, onWalletCardSelected e onWalletDismissed. O diagrama de sequência abaixo ilustra uma sequência de chamadas quando a carteira de acesso rápido é exibida imediatamente antes de um pagamento por NFC.

Diagrama de sequência da Carteira de acesso rápido

Exemplo de sequência de chamadas quando o Acesso rápido à carteira é aberto — **Figura 4**. Exemplo de sequência de chamadas quando a Carteira de Acesso rápido é aberta.

Nem todas as visualizações da Carteira de acesso rápido são seguidas por um pagamento por NFC, mas a Figura 4 acima ilustra todos os recursos da QuickAccessWalletService. Neste exemplo, o provedor do cartão de acesso rápido à carteira implementa os elementos descritos em azul. Supõe-se que os cartões de pagamento são armazenados no dispositivo em um banco de dados e acessados por uma interface chamada PaymentCardManager. Além disso, presume-se que uma atividade chamada PaymentActivity mostre o resultado de um pagamento por NFC. O fluxo ocorre da seguinte maneira:

O usuário realiza um gesto para abrir a Carteira de acesso rápido.
A interface do Quick Access Wallet (parte da interface do sistema) verifica o gerenciador de pacotes para saber se o app de pagamento por NFC padrão exporta QuickAccessWalletService.
- Se o serviço não for exportado, a Carteira de Acesso Rápido não será exibida.
A interface da Carteira de Acesso rápido é vinculada a QuickAccessWalletService e chama onWalletCardsRequested. Esse método usa um objeto de solicitação com dados sobre o número e o tamanho dos cartões que podem ser fornecidos e um callback. O callback pode ser chamado em uma linha de execução em segundo plano.
QuickAccessWalletService calcula os cards que quer mostrar e chama o método onSuccess no callback fornecido. É recomendado que o serviço realize essas ações em uma linha de execução em segundo plano.
Assim que os cartões são exibidos, a interface do sistema notifica QuickAccessWalletService de que o primeiro cartão foi selecionado chamando onWalletCardSelected.
- onWalletCardSelected é chamado sempre que o usuário seleciona um novo card.
- onWalletCardSelected pode ser chamado mesmo que o cartão selecionado não tenha mudado.
Quando o usuário dispensa a Carteira de acesso rápido, a IU do sistema notifica QuickAccessWalletService chamando onWalletDismissed.

No exemplo acima, o usuário aproxima o smartphone de um terminal de pagamento NFC enquanto a carteira está sendo mostrada. Um componente importante do processamento de pagamentos NFC é o HostApduService, que precisa ser implementado para processar APDUs fornecidas pelo leitor de NFC. Para mais informações, consulte Emulação de cartão com base no host. Supõe-se que o app de pagamento inicia uma atividade para mostrar o progresso e o resultado da interação com o terminal NFC. No entanto, a interface da Carteira de acesso rápido é mostrada na parte de cima da janela do app, o que significa que a atividade de pagamento é ocultada pela interface da Carteira de acesso rápido. Para corrigir isso, o app precisa notificar a IU do sistema que a IU da Carteira de acesso rápido precisa ser encerrada. Para isso, ele precisa ter uma referência ao QuickAccessWalletService vinculado e chamar sendWalletServiceEvent com o tipo de evento TYPE_NFC_PAYMENT_STARTED.

Exemplo de implementação do QuickAccessWalletService

/** Sample implementation of {@link QuickAccessWalletService} */
@RequiresApi(VERSION_CODES.R)
public class MyQuickAccessWalletService extends QuickAccessWalletService {

  private static final String TAG = "QAWalletSvc";
  private ExecutorService executor;
  private PaymentCardManager paymentCardManager;

  @Override
  public void onCreate() {
    super.onCreate();
    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.R) {
      Log.w(TAG, "Should not run on pre-R devices");
      stopSelf();
      return;
    }
    executor = Executors.newSingleThreadExecutor();
    paymentCardManager = new PaymentCardManager();
  }

  @Override
  public void onDestroy() {
    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.R) {
      return;
    }
    executor.shutdownNow();
  }

  @Override
  public void onWalletCardsRequested(
      @NonNull GetWalletCardsRequest request, @NonNull GetWalletCardsCallback callback) {
    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.R) {
      return;
    }
    executor.submit(
        () -> {
          List<PaymentCard> paymentCards = paymentCardManager.getCards();
          int maxCards = Math.min(paymentCards.size(), request.getMaxCards());
          List<WalletCard> walletCards = new ArrayList<>(maxCards);
          int selectedIndex = 0;
          int cardWidthPx = request.getCardWidthPx();
          int cardHeightPx = request.getCardHeightPx();
          for (int index = 0; index < maxCards; index++) {
            PaymentCard paymentCard = paymentCards.get(index);
            WalletCard walletCard =
                new WalletCard.Builder(
                        paymentCard.getCardId(),
                        paymentCard.getCardImage(cardWidthPx, cardHeightPx),
                        paymentCard.getContentDescription(),
                        paymentCard.getPendingIntent())
                    .build();
            walletCards.add(walletCard);
            if (paymentCard.isSelected()) {
              selectedIndex = index;
            }
          }
          GetWalletCardsResponse response =
              new GetWalletCardsResponse(walletCards, selectedIndex);
          callback.onSuccess(response);
        });
  }

  @Override
  public void onWalletCardSelected(@NonNull SelectWalletCardRequest request) {
    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.R) {
      return;
    }
    executor.submit(
        () -> paymentCardManager.selectCardById(request.getCardId()));
  }

  @Override
  public void onWalletDismissed() {
    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.R) {
      return;
    }
    executor.submit(() -> {
      paymentCardManager.removeCardOverrides();
    });
  }
}

Para mais detalhes sobre QuickAccessWalletService, consulte a referência da API QuickAccessWalletService.

Permissões

A entrada do manifesto para QuickAccessWalletService precisa exigir a permissão android.permission.BIND_QUICK_ACCESS_WALLET_SERVICE introduzida no Android 11. Essa é uma permissão no nível da assinatura mantida pela interface do sistema, o que significa que somente o processo da interface do sistema pode ser vinculado a implementações de QuickAccessWalletService. Os apps sideloaded podem reivindicar essa permissão e ter acesso total aos dados de QuickAccessWalletService em dispositivos com o Android 10 ou versões anteriores. Para evitar isso, é recomendável que o serviço verifique a versão do build em onCreate e ative o serviço apenas em dispositivos com o Android 11 ou mais recente. Nenhuma outra permissão do app é necessária além daquelas necessárias para fornecer serviços de pagamento de emulação de cartão host.

Se o app de pagamento NFC padrão não implementar ou exportar QuickAccessWalletService, a interface da Carteira de acesso rápido não será exibida.

Configurações no Android 12

Para ativar ou desativar a Carteira de acesso rápido na tela de bloqueio, os usuários podem usar o botão Mostrar carteira em Configurações > Tela > Tela de bloqueio. Para desativar a carteira na aba, os usuários precisam editá-la manualmente na aba de configurações rápidas.

Alternar para ativar ou desativar a carteira na tela de bloqueio

Figura 5. Mostrar a chave "Mostrar a Carteira" na página "Tela de bloqueio" em "Configurações".

Configurações no Android 11

Os usuários podem desativar o recurso da Carteira de acesso rápido no app Configurações. A página de configurações está em Configurações > Sistema > Gestos > Cartões e cartões de acesso.

Página de configurações para ativar ou desativar o recurso Acesso rápido à carteira — **Figura 6**. Página de configurações para ativar ou desativar o recurso da Carteira de acesso rápido.

Personalização

Adicionar a visualização do Acesso rápido à carteira a outro local na interface do sistema

A interface da Carteira de acesso rápido é criada como um plug-in do sistema. Embora a implementação do AOSP use o recurso em GlobalActionsDialog (exibido ao pressionar o botão de energia por muito tempo), é possível mover o recurso para trás de um gesto diferente desde que você mantenha o contrato especificado pela interface do plug-in.

public interface GlobalActionsPanelPlugin extends Plugin {

  /** Invoked when the view is shown */
  PanelViewController onPanelShown(Callbacks callbacks, boolean deviceLocked);

  /** Callbacks for interacting with the view container */
  interface Callbacks {
    /** Dismisses the view */
    void dismissGlobalActionsMenu();

    /** Starts a PendingIntent, dismissing the keyguard if necessary. */
    void startPendingIntentDismissingKeyguard(PendingIntent pendingIntent);
  }

  /** Provides the Quick Access Wallet view */
  interface PanelViewController {

    /** Returns the QuickAccessWallet view, which may take any size */
    View getPanelContent();

    /** Invoked when the view is dismissed */
    void onDismissed();

    /** Invoked when the device is either locked or unlocked. */
    void onDeviceLockStateChanged(boolean locked);
  }
}

A interface da Carteira de acesso rápido implementa GlobalActionsPanelPlugin e PanelViewController. GlobalActionsDialog recebe uma instância do plug-in da carteira usando com.android.systemui.Dependency:

GlobalActionsPanelPlugin mPanelPlugin =
    Dependency.get(ExtensionController.class)
        .newExtension(GlobalActionsPanelPlugin.class)
        .withPlugin(GlobalActionsPanelPlugin.class)
        .build()
        .get();

Depois de verificar se o plug-in não é nulo e se o PanelViewController retornado por onPanelShown não é nulo, a caixa de diálogo anexa o View fornecido por getPanelContent ao próprio View e fornece callbacks adequados para eventos do sistema.

// Construct a Wallet PanelViewController.
// `this` implements GlobalActionsPanelPlugin.Callbacks
GlobalActionsPanelPlugin.PanelViewController mPanelController =
    mPanelPlugin.onPanelShown(this, !mKeyguardStateController.isUnlocked());

// Attach the view
FrameLayout panelContainer = findViewById(R.id.my_panel_container);
FrameLayout.LayoutParams panelParams =
    new FrameLayout.LayoutParams(
        FrameLayout.LayoutParams.MATCH_PARENT,
        FrameLayout.LayoutParams.MATCH_PARENT);
panelContainer.addView(mPanelController.getPanelContent(), panelParams);

// Respond to unlock events (if the view can be accessed while the phone is locked)
keyguardStateController.addCallback(new KeyguardStateController.Callback() {
  @Override
  public void onUnlockedChanged() {
    boolean unlocked = keyguardStateController.isUnlocked()
        || keyguardStateController.canDismissLockScreen();
    mPanelController.onDeviceLockStateChanged(unlocked);
  }
});

// Implement GlobalActionsPanelPlugin.Callbacks
@Override
public void dismissGlobalActionsMenu() {
  dismissDialog();
}
@Override
public void startPendingIntentDismissingKeyguard(PendingIntent pendingIntent) {
  mActivityStarter.startPendingIntentDismissingKeyguard(pendingIntent);
}

// Notify the wallet when the container view is dismissed
mPanelController.onDismissed();

Para remover o Acesso rápido à carteira do menu Liga/Desliga, omita o destino QuickAccessWallet do build do sistema. Para remover a carteira de acesso rápido do menu de desligamento, mas adicioná-la a uma visualização diferente fornecida pela interface do sistema, inclua o destino de build e remova as referências ao GlobalActionsPanelPlugin do GlobalActionsImpl.

Definir configurações padrão

Android 12

No Android 12 e versões mais recentes, o Acesso rápido à carteira está sempre visível na aba de configurações rápidas. A visibilidade da Carteira de Acesso rápido na tela de bloqueio é bloqueada pela seguinte configuração segura: LOCKSCREEN_SHOW_WALLET. Essa configuração controla se o ícone de acesso rápido à carteira é mostrado no canto inferior direito da tela de bloqueio. Essa configuração é definida como true por padrão, mas pode ser desativada pelo usuário em Configurações > Tela > Tela de bloqueio > Mostrar carteira.

Android 11

No Android 11, a visibilidade da Carteira no Acesso rápido é controlada por duas configurações seguras: GLOBAL_ACTIONS_PANEL_ENABLED e GLOBAL_ACTIONS_PANEL_AVAILABLE. A configuração AVAILABLE controla se o recurso pode ser ativado e desativado nas Configurações. Essa configuração é definida como true por WalletPluginService. Se QuickAccessWallet não estiver incluído no build, a configuração permanecerá false. A configuração ENABLED é definida como true por padrão no mesmo lugar, mas pode ser desativada pelo usuário nas configurações. Para mudar o comportamento padrão, modifique WalletPluginService#enableFeatureInSettings.

Validação

Para validar sua implementação da Carteira de acesso rápido, execute testes CTS e manuais. As mudanças no plug-in também precisam executar os testes roboelétricos incluídos.

Testes CTS

Execute os testes CTS localizados em cts/tests/quickaccesswallet.

Testes manuais do Android 12

Para testar os principais recursos da Carteira de acesso rápido, é necessário ter um terminal de pagamento NFC (real ou falso) e um app de pagamento NFC que implemente QuickAccessWalletService (app de carteira). Os recursos principais que precisam ser testados incluem: disponibilidade, estado zero, seleção de cartão e comportamento da tela de bloqueio.

Disponibilidade

Se o app de pagamento NFC padrão não for compatível com o recurso, a Carteira de Acesso Rápido não poderá ser acessada nas Configurações rápidas nem na tela de bloqueio.
Se o app de pagamento por NFC padrão oferecer suporte ao recurso, a Carteira de acesso rápido poderá ser acessada na sombra de configurações rápidas.
Se o app de pagamento por NFC padrão oferecer suporte ao recurso e a configuração LOCKSCREEN_SHOW_WALLET for true, a Carteira de acesso rápido vai estar disponível na tela de bloqueio.
Se o app de pagamento por aproximação padrão oferecer suporte ao recurso e a configuração LOCKSCREEN_SHOW_WALLET for false, a carteira de acesso rápido não poderá ser acessada na tela de bloqueio.

Estado zero

Se QuickAccessWalletService estiver ativado e exportado, mas não fornecer nenhum cartão, o bloco na sombra aparecerá como mostrado no exemplo na Figura 7. Clicar no bloco abre o app padrão de pagamento por aproximação.

Figura 7. Exemplo de bloco na sombra mostrando o app de pagamento por aproximação padrão.
Clicar na visualização de estado vazio, conforme mostrado na Figura 8, abre o app de pagamento NFC padrão. Essa visualização de estado vazio aparece apenas quando o usuário tem um cartão na carteira, remove o cartão da página de detalhes e volta à visualização da carteira.
A tela de bloqueio mostra o ícone de carteira.

Visualização do estado vazio na Carteira de acesso rápido

Figura 8. Visualização do estado vazio na interface da Carteira de acesso rápido.

Estado diferente de zero

Se o app de carteira fornecer um ou mais cartões, o bloco na aba vai aparecer como mostrado na Figura 9.

Figura 9. Exemplo de bloco na sombra quando o app da Carteira tem um ou mais cards.
Ao clicar no bloco, um carrossel de cards é mostrado.
A tela de bloqueio mostra um botão que abre a Carteira de acesso rápido.

Figura 10. Interface da Carteira de acesso rápido com um cartão exibido.
Se o cartão exibido representar uma forma de pagamento NFC, segurar o smartphone em um terminal de pagamento NFC vai fazer com que essa forma de pagamento seja usada e a visualização da carteira seja dispensada.
Clicar em um card abre a atividade detalhada dele.
Se vários cards forem fornecidos por QuickAccessWalletService, o usuário poderá deslizar entre eles.
O menu flutuante contém uma entrada: abra as configurações da tela de bloqueio para que o usuário possa alterar a opção Mostrar carteira.

Testes de estado de bloqueio

Se o smartphone estiver bloqueado, a carteira vai aparecer na sombra de configurações rápidas com a descrição Adicionar um cartão se não houver nenhum cartão no app de pagamento padrão ou Desbloquear para usar se houver cartões no app de pagamento padrão.
Se o smartphone estiver bloqueado, a visibilidade da Carteira na tela de bloqueio será controlada pela configuração Secure.LOCKSCREEN_SHOW_WALLET, que é controlada em "Configurações".
Se o smartphone estiver bloqueado, LOCKSCREEN_SHOW_WALLET for false e nenhum cartão existir no app de pagamento NFC padrão, a carteira não será exibida na tela de bloqueio.
Se o smartphone estiver bloqueado, LOCKSCREEN_SHOW_WALLET for true e nenhum cartão existir no app de pagamento NFC padrão, a carteira não será exibida na tela de bloqueio.
Se o smartphone estiver bloqueado, LOCKSCREEN_SHOW_WALLET for true e os cartões estiverem no app de pagamento por aproximação padrão, a carteira será exibida na tela de bloqueio.
Desbloquear o smartphone enquanto a Carteira estiver sendo exibida na tela de bloqueio faz com que os cards sejam solicitados, o que pode resultar em um conteúdo diferente.

Testes de acessibilidade

Os usuários do Talkback podem navegar pela visualização da Carteira deslizando para a esquerda e para a direita e ouvindo as descrições de conteúdo dos cards.
Deslizar para a esquerda e direita com o TalkBack ativado seleciona cada card. Os usuários do Talkback podem selecionar e usar uma forma de pagamento NFC em um terminal de pagamento NFC.

Testes manuais para o Android 11

Para testar os principais recursos da Carteira de acesso rápido, é necessário ter um terminal de pagamento NFC (real ou falso) e um app de pagamento NFC que implemente QuickAccessWalletService (app de carteira). Os recursos principais que precisam ser testados incluem disponibilidade, estado zero, seleção de cartão e comportamento da tela de bloqueio.