Esta página foi traduzida pela API Cloud Translation.

Carteira de acesso rápido

O recurso Carteira de acesso rápido, disponível no Android 11, permite ao usuário acessar cartões de pagamento e passes relevantes diretamente do menu de energia. Os principais casos de uso incluem a seleção do método de pagamento apropriado antes de realizar uma transação em um terminal NFC e o acesso rápido a voos e outros passes para eventos futuros.

No Android 12 ou superior, o recurso Carteira de acesso rápido está disponível na sombra, conforme mostrado na Figura 1 e na Figura 2.

Recurso de carteira de acesso rápido na sombra — **Figura 1.** Recurso Carteira de Acesso Rápido (dispositivo bloqueado).

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

Recurso de carteira de acesso rápido no menu de energia — **Figura 3.** Recurso Carteira de acesso rápido no menu de energia.

Requisitos

Seu dispositivo deve ter NFC para usar o recurso Carteira de acesso rápido. O recurso está vinculado ao QuickAccessWalletService do aplicativo de pagamento NFC padrão, o que significa que o dispositivo também deve suportar emulação de cartão baseado em host NFC (HCE) .

Visão geral dos recursos

Existem duas partes na Carteira de Acesso Rápido: a UI da Carteira de Acesso Rápido e o fornecedor do cartão da Carteira de Acesso Rápido.

No Android 12 ou superior, a UI da Wallet é executada na UI do sistema e está localizada em frameworks/base/packages/SystemUI/src/com/android/systemui/wallet . No Android 11, a IU da Wallet, localizada em platform/packages/apps/QuickAccessWallet , deve ser instalada e colocada na lista de permissões.

O fornecedor do cartão Quick Access Wallet é o aplicativo de pagamento NFC padrão. Os usuários podem ter vários aplicativos de pagamento NFC instalados simultaneamente, mas apenas o aplicativo de pagamento NFC padrão pode mostrar cartões no menu de energia. Você pode especificar qual aplicativo de pagamento NFC é definido inicialmente como padrão , mas os usuários podem selecionar um aplicativo diferente em Configurações. Se apenas um aplicativo de pagamento NFC estiver instalado, ele se tornará o padrão automaticamente (consulte CardEmulationManager ).

Implementação

Para fornecer cartões à IU da Carteira de acesso rápido, os aplicativos de pagamento NFC devem implementar QuickAccessWalletService . Os aplicativos de pagamento devem incluir uma entrada de manifesto anunciando o serviço.

Para garantir que apenas a IU do sistema possa se vincular ao QuickAccessWalletService , o aplicativo de pagamento NFC deve exigir a permissão android.permission.BIND_QUICK_ACCESS_WALLET_SERVICE . A exigência dessa permissão garante que apenas a IU do sistema possa vincular-se ao 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>

Informações adicionais sobre a carteira estã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 aplicativo de pagamento deve 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 lidar com uma transação NFC e, como consequência, iniciar uma atividade para exibir o progresso e o resultado do pagamento, ele também deverá tentar obter uma referência ao QuickAccessWalletService vinculado e chamar QuickAccessWalletService#sendEvent com um tipo de evento TYPE_NFC_PAYMENT_STARTED . Isso faz com que a UI da Carteira de Acesso Rápido seja dispensada, permitindo ao usuário uma visão desobstruída da atividade de pagamento.

Para obter documentação adicional sobre a implementação QuickAccessWalletService , consulte QuickAccessWalletService e o teste TestQuickAccessWalletService CTS.

Ativando a IU da carteira de acesso rápido no Android 11

Para configurar a carteira de acesso rápido para estar disponível no menu de energia no Android 11, inclua o destino QuickAccessWallet na compilação 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 arquivos 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 aplicativo de pagamento NFC padrão no arquivo de configuração usando def_nfc_payment_component .

O aplicativo de pagamento NFC padrão deve expor QuickAccessWalletService para fornecer cartões à carteira de acesso rápido. Se o aplicativo de pagamento NFC padrão não exportar esse serviço, a UI da carteira ficará oculta.

Detalhes de implementação do QuickAccessWalletService

QuickAccessWalletService possui três métodos abstratos que devem ser implementados: onWalletCardsRequested , onWalletCardSelected e onWalletDismissed . O diagrama de sequência abaixo ilustra uma sequência de chamada quando a Carteira de Acesso Rápido é visualizada imediatamente antes de um pagamento NFC.

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

**Figura 4.** Exemplo de sequência de chamada quando a Carteira de Acesso Rápido é visualizada.

Nem todas as visualizações da Carteira de Acesso Rápido são seguidas por um pagamento NFC, mas a Figura 4 acima ilustra todos os recursos do QuickAccessWalletService . Neste exemplo, o fornecedor do cartão Quick Access Wallet implementa os elementos destacados em azul. Supõe-se que os cartões de pagamento sejam armazenados no dispositivo em um banco de dados e acessados por meio de uma interface chamada PaymentCardManager . Supõe-se ainda que uma atividade chamada PaymentActivity exibe o resultado de um pagamento NFC. O fluxo ocorre da seguinte forma:

O usuário realiza um gesto para abrir a Carteira de Acesso Rápido.
A IU da Carteira de Acesso Rápido (parte da IU do Sistema) verifica o gerenciador de pacotes para ver se o aplicativo de pagamento NFC padrão exporta QuickAccessWalletService .
- Se o serviço não for exportado, a Carteira de Acesso Rápido não será exibida.
A IU da Carteira de Acesso Rápido se vincula ao QuickAccessWalletService e chama onWalletCardsRequested . Este método recebe um objeto de solicitação contendo dados sobre o número e tamanho dos cartões que podem ser fornecidos e um retorno de chamada. O retorno de chamada pode ser chamado de um thread em segundo plano.
QuickAccessWalletService calcula os cartões que deseja mostrar e, em seguida, chama o método onSuccess no retorno de chamada fornecido. É recomendável que o serviço execute essas ações em um thread em segundo plano.
Assim que os cartões são exibidos, a IU do sistema notifica QuickAccessWalletService de que o primeiro cartão foi selecionado chamando onWalletCardSelected .
- onWalletCardSelected é chamado sempre que o usuário seleciona um novo cartão.
- onWalletCardSelected pode ser chamado mesmo que o cartão atualmente selecionado não tenha mudado.
Quando o usuário descarta a Carteira de Acesso Rápido, a UI do Sistema notifica QuickAccessWalletService chamando onWalletDismissed .

No exemplo acima, o usuário coloca o telefone ao alcance de um terminal de pagamento NFC enquanto a carteira está sendo exibida. Um componente chave para lidar com pagamentos NFC é HostApduService , que deve ser implementado para processar APDUs fornecidos pelo leitor NFC (para obter mais informações, consulte Emulação de cartão baseada em host ). Supõe-se que o aplicativo de pagamento inicie uma atividade para exibir o progresso e o resultado da interação com o terminal NFC. No entanto, a UI da Carteira de Acesso Rápido é exibida na parte superior da janela do aplicativo, o que significa que a atividade de pagamento é obscurecida pela UI da Carteira de Acesso Rápido. Para corrigir isso, o aplicativo deve notificar a IU do sistema de que a IU da carteira de acesso rápido deve ser dispensada. Isso pode ser feito obtendo uma referência ao QuickAccessWalletService vinculado e chamando sendWalletServiceEvent com o tipo de evento TYPE_NFC_PAYMENT_STARTED .

Implementação de amostra 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 obter mais detalhes sobre QuickAccessWalletService , consulte Referência da API QuickAccessWalletService .

Permissões

A entrada do manifesto para QuickAccessWalletService deve exigir a permissão android.permission.BIND_QUICK_ACCESS_WALLET_SERVICE introduzida no Android 11. Esta é uma permissão em nível de assinatura mantida pela IU do sistema, o que significa que apenas o processo da IU do sistema pode se vincular a implementações de QuickAccessWalletService . Esteja ciente de que os aplicativos carregados lateralmente podem reivindicar essa permissão e obter acesso total aos dados QuickAccessWalletService em dispositivos com Android 10 ou inferior. Para evitar isso, é recomendado que o serviço verifique a versão do build no onCreate e habilite o serviço apenas em dispositivos com Android 11 e superior. Nenhuma outra permissão de aplicativo é necessária além daquelas necessárias para fornecer serviços de pagamento de emulação de cartão host.

Se o aplicativo de pagamento NFC padrão não implementar ou exportar QuickAccessWalletService , a UI 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 desabilitar a carteira na sombra, os usuários devem editá-la manualmente na aba de configurações rápidas.

Alterne para ativar ou desativar a carteira na tela de bloqueio

Figura 5. Mostrar alternância de carteira na página da tela de bloqueio em Configurações.

Configurações no Android 11

Os usuários podem desativar o recurso Carteira de acesso rápido no aplicativo Configurações. A página de configurações é encontrada em Configurações > Sistema > Gestos > Cartões e passes .

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

Costumização

Adicionando a visualização da Carteira de Acesso Rápido a outro local na IU do Sistema

A UI da Carteira de Acesso Rápido é construída como um plugin do sistema . Embora a implementação do AOSP faça uso dele no GlobalActionsDialog (mostrado ao pressionar longamente), você pode mover o recurso para trás de um gesto diferente, desde que mantenha o contrato especificado pela interface do plugin.

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 IU da carteira de acesso rápido implementa GlobalActionsPanelPlugin e PanelViewController . GlobalActionsDialog obtém uma instância do plugin de 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 a View fornecida por getPanelContent à sua própria View e fornece retornos de chamada apropriados 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 a Carteira de Acesso Rápido do menu de energia, omita o destino QuickAccessWallet da compilação do sistema. Para remover a Carteira de acesso rápido do menu avançado, mas adicioná-la a uma visualização diferente fornecida pela IU do sistema, inclua o destino de compilação e remova as referências ao GlobalActionsPanelPlugin de GlobalActionsImpl .

Definindo configurações padrão

Andróide 12

No Android 12 ou superior, a Carteira de Acesso Rápido está sempre visível na aba de configurações rápidas. A visibilidade da Carteira de Acesso Rápido na tela de bloqueio é controlada pela seguinte configuração segura: LOCKSCREEN_SHOW_WALLET . Esta configuração controla se o ícone da Carteira de Acesso Rápido é 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 de 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 em Configurações. Esta configuração é definida como true por WalletPluginService . Se QuickAccessWallet não estiver incluído na compilação, a configuração permanecerá false . A configuração ENABLED é definida como true por padrão no mesmo local, mas pode ser desativada pelo usuário em Configurações. Para alterar 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 alterações no plugin também devem exercitar os testes robolétricos incluídos.

Testes CTS

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

Testes manuais para Android 12

Testar os principais recursos da Carteira de Acesso Rápido requer um terminal de pagamento NFC (real ou falso) e um aplicativo de pagamento NFC que implemente QuickAccessWalletService (aplicativo de carteira). Os principais recursos que devem ser testados incluem: disponibilidade, estado zero, seleção de cartão e comportamento da tela de bloqueio.

Disponibilidade

Se o aplicativo de pagamento NFC padrão não suportar o recurso, a Carteira de Acesso Rápido não estará acessível nem nas configurações rápidas nem na tela de bloqueio.
Se o aplicativo de pagamento NFC padrão suportar o recurso, a Carteira de Acesso Rápido estará acessível na aba de configurações rápidas.
Se o aplicativo de pagamento NFC padrão suportar o recurso e se a configuração LOCKSCREEN_SHOW_WALLET for true , a Carteira de Acesso Rápido estará acessível na tela de bloqueio.
Se o aplicativo de pagamento NFC padrão suportar o recurso e se a configuração LOCKSCREEN_SHOW_WALLET for false , a Carteira de Acesso Rápido não estará acessível na tela de bloqueio.

Estado zero

Se QuickAccessWalletService estiver ativado e exportado, mas não fornecer nenhum cartão, o bloco na Sombra aparecerá conforme mostrado no exemplo da Figura 7. Clicar no bloco abre o aplicativo de pagamento NFC padrão.
Figura 7. Exemplo de bloco na sombra mostrando o aplicativo de pagamento NFC padrão.
Clicar na visualização de estado vazia, conforme mostrado na Figura 8, abre o aplicativo de pagamento NFC padrão. Essa visualização de estado vazio é exibida somente quando o usuário ainda tem um cartão na carteira, remove o cartão da página de detalhes do cartão e depois volta para a visualização da carteira.
A tela de bloqueio mostra o ícone da carteira.

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

Figura 8. Visualização do estado vazio na UI da Carteira de Acesso Rápido.

Estado diferente de zero

Se o aplicativo de carteira fornecer um ou mais cartões, o bloco na sombra aparecerá conforme mostrado na Figura 9.
Figura 9. Exemplo de bloco na sombra quando o aplicativo de carteira possui um ou mais cartões.
Clicar no bloco mostra um carrossel de cartas.
A tela de bloqueio mostra um botão que abre a Carteira de Acesso Rápido.
Figura 10. UI da carteira de acesso rápido com um cartão exibido.
Se o cartão exibido representar um método de pagamento NFC, segurar o telefone em um terminal de pagamento NFC resultará no uso desse método de pagamento e a visualização da carteira será descartada.
Clicar em um cartão exibido abre a atividade detalhada desse cartão.
Se vários cartões forem fornecidos pelo QuickAccessWalletService , o usuário poderá deslizar entre os cartões.
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 telefone estiver bloqueado, a carteira ficará visível na aba de configurações rápidas, com uma descrição de Adicionar um cartão se não existir cartão no aplicativo de pagamento padrão ou desbloquear para usar se existirem cartões no aplicativo de pagamento padrão.
Se o telefone 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 telefone estiver bloqueado, LOCKSCREEN_SHOW_WALLET for false e não existir nenhum cartão no aplicativo de pagamento NFC padrão, a carteira não será exibida na tela de bloqueio.
Se o telefone estiver bloqueado, LOCKSCREEN_SHOW_WALLET for true e não existir nenhum cartão no aplicativo de pagamento NFC padrão, a carteira não será exibida na tela de bloqueio.
Se o telefone estiver bloqueado, LOCKSCREEN_SHOW_WALLET for true e existirem cartões no aplicativo de pagamento NFC padrão, a carteira será exibida na tela de bloqueio.
Desbloquear o telefone enquanto a carteira está sendo exibida na tela de bloqueio faz com que os cartões sejam solicitados novamente, o que pode resultar em conteúdo diferente do cartão.

Testes de acessibilidade

Os usuários do Talkback podem navegar na visualização da carteira deslizando para a esquerda e para a direita e ouvindo as descrições do conteúdo dos cartões.
Deslizar para a esquerda e para a direita com o Talkback ativado seleciona cada cartão por vez. Os usuários do Talkback podem selecionar e usar um método de pagamento NFC em um terminal de pagamento NFC.

Testes manuais para Android 11

Testar os principais recursos da Carteira de Acesso Rápido requer um terminal de pagamento NFC (real ou falso) e um aplicativo de pagamento NFC que implemente QuickAccessWalletService (aplicativo de carteira). Os principais recursos que devem ser testados incluem disponibilidade, estado zero, seleção de cartão e comportamento da tela de bloqueio.