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 em O Android 11 permite que o usuário acesse cartões de pagamento e passes relevantes diretamente do menu liga/desliga. Uso principal casos incluem a seleção da forma de pagamento apropriada antes de realizar uma transação em um terminal NFC e acesso rápido a voos e outros cartões para os próximos eventos.

No Android 12 ou versões mais recentes, a Carteira de acesso rápido está disponível na aba, conforme mostrado nas figuras 1 e 2.

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

No Android 11, o recurso está disponível no menu liga/desliga, conforme mostrado em Figura 3.

Recurso de acesso rápido à carteira no menu liga/desliga — **Figura 3.** Recurso de acesso rápido à carteira no poder .

Requisitos

Seu 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 que o dispositivo também deve ser compatível com NFC emulação de cartão com base em host (HCE, na sigla em inglês).

Visão geral do recurso

Ela tem duas partes: a interface do Acesso rápido à carteira e ao provedor do cartão Acesso rápido à Carteira.

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

O provedor do cartão de acesso rápido à Carteira é o app padrão de pagamento por aproximação. Os usuários podem ter vários apps de pagamento por aproximação instalados simultaneamente, mas apenas o app padrão O app de pagamento por aproximação pode mostrar cartões no menu liga/desliga. É possível especificar qual NFC é definido inicialmente como default, mas os usuários podem selecionar uma app nas Configurações. Se apenas um app de pagamento por aproximação estiver instalado, ele se tornará o padrão automaticamente (consulte CardEmulationManager).

Implementação

Para fornecer cartões à interface do Acesso rápido à carteira, o pagamento por aproximação os apps precisam implementar QuickAccessWalletService Os apps de pagamento precisam incluir uma entrada de manifesto anunciando o serviço.

Para garantir que apenas a interface do sistema possa se vincular a QuickAccessWalletService, o O app de pagamento por aproximação precisa exigir android.permission.BIND_QUICK_ACCESS_WALLET_SERVICE. Exigindo isso garante que somente a interface do sistema pode 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>

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 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, inicia uma atividade para exibir o progresso e o resultado do pagamento, ela deve tente conseguir uma referência ao QuickAccessWalletService vinculado e chame QuickAccessWalletService#sendEvent com um tipo de evento de TYPE_NFC_PAYMENT_STARTED. Isso faz com que a interface do Acesso rápido à carteira seja dispensado, permitindo que o usuário tenha uma visão desobstruída da atividade de pagamento.

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

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

Configurar o acesso rápido à carteira para que fique disponível no menu liga/desliga no Android 11, inclua QuickAccessWallet no build e ative o plug-in globalactions.wallet adicionando a linha em negrito no exemplo de código abaixo ao 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 padrão de pagamento por aproximação no arquivo de configuração de configurações usando def_nfc_payment_component.

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

Detalhes de implementação do QuickAccessWalletService

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

Diagrama de sequência do Acesso rápido à carteira

Exemplo de sequência de chamadas quando a Carteira de acesso rápido é visualizada — **Figura 4**. Exemplo de sequência de chamadas quando o Acesso rápido à Carteira está visto.

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

O usuário faz um gesto para abrir a carteira de acesso rápido.
A interface da Carteira de Acesso rápido (parte da interface do sistema) verifica o pacote para verificar se o app padrão de pagamento por aproximação exporta QuickAccessWalletService:
- Se o serviço não for exportado, a Carteira de acesso rápido não será exibidos.
A interface da Carteira do Acesso rápido é vinculada ao QuickAccessWalletService e chama onWalletCardsRequested. Esse método usa um objeto de solicitação que contenham 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, em seguida, chama o método onSuccess no callback fornecido. Está recomendado que o serviço execute 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 cartão.
- onWalletCardSelected pode ser chamado mesmo se o evento o cartão selecionado não foi alterado.
Quando o usuário dispensa a Carteira de acesso rápido, a interface do sistema notifica QuickAccessWalletService chamando onWalletDismissed.

No exemplo acima, o usuário aproxima o smartphone de um pagamento NFC terminal enquanto a carteira é exibida. Um componente essencial para lidar com NFC pagamentos é 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 em host). Presume-se que o app de pagamento inicie uma atividade para exibir o progresso e resultado da interação com o terminal NFC. No entanto, o Acesso rápido A interface da Carteira é mostrada na parte de cima da janela do app, o que significa que a atividade de pagamento é ocultada pela interface do Acesso rápido à Carteira. Para retificar isso, o app precisa notificar a interface do sistema de que a interface da Carteira de acesso rápido precisa ser dispensada. Isso pode ser feito obtendo uma referência ao elemento QuickAccessWalletService e chamar sendWalletServiceEvent com o evento digite TYPE_NFC_PAYMENT_STARTED.

Implementação de exemplo 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 Referência da API QuickAccessWalletService.

Permissões

A entrada de manifesto de QuickAccessWalletService precisa exigir o Permissão android.permission.BIND_QUICK_ACCESS_WALLET_SERVICE introduzida em Android 11 Essa é uma permissão no nível da assinatura pela interface do sistema, somente o processo da interface do sistema pode se vincular a implementações de QuickAccessWalletService: Os apps transferidos por sideload podem reivindicar esse permissão e acesso total aos dados do QuickAccessWalletService nos dispositivos com o Android 10 ou uma versão anterior. Para evitar isso, é recomendado que o serviço Verificar a versão do build em onCreate e ativar o serviço apenas em dispositivos com o Android 11 e versões mais recentes. Nenhuma outra permissão do app são necessárias além das necessárias para fornecer pagamentos de emulação de cartão do host serviços.

Se o app padrão de pagamento por aproximação não implementar ou exportar QuickAccessWalletService, a interface do Acesso rápido à carteira não está sendo mostrada.

Configurações no Android 12

Para ativar ou desativar o Acesso rápido à carteira na tela de bloqueio, os usuários podem Use o botão de alternância Mostrar carteira em Configurações > Tela > Tela de bloqueio. Para desativar a carteira na aba, os usuários precisam editar manualmente na aba de configurações rápidas.

Alterne para ativar ou desativar a carteira na tela de bloqueio

Figura 5. Mostrar o botão de ativação/desativação da carteira na página de bloqueio de tela, em "Configurações".

Configurações no Android 11

Os usuários podem desativar o recurso de acesso rápido à carteira no app Configurações. A de configuração está na Configurações > Sistema > Gestos > Cards e 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 de Acesso rápido à carteira.

Personalização

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

A Acesso rápido à interface da Carteira é criado como um system plugin. Embora a implementação do AOSP o use nos GlobalActionsDialog (mostrado ao tocar e manter pressionado o botão liga/desliga), você pode mover o recurso para trás de um gesto diferente contanto 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 Acesso rápido à interface da Carteira 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 for nulo, a caixa de diálogo anexará o View fornecido por getPanelContent ao próprio View e fornece callbacks 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 liga/desliga, omita a QuickAccessWallet destino do build do sistema. Para remover o Acesso rápido Carteira no menu liga/desliga, mas adicione a uma visualização diferente fornecida pela interface do sistema, incluir o destino do build e remover referências ao GlobalActionsPanelPlugin; de GlobalActionsImpl.

Definir configurações padrão

Android 12

No Android 12 ou versões mais recentes, a Carteira de acesso rápido é sempre visível na aba de configurações rápidas. Visibilidade do Acesso rápido A Carteira na tela de bloqueio é controlada pela seguinte configuração de segurança: LOCKSCREEN_SHOW_WALLET: Essa configuração controla se o Acesso rápido à Carteira ícone é exibido no canto inferior direito da tela de bloqueio. Essa configuração está definida como true por padrão, mas pode ser desativado 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 A configuração AVAILABLE controla se o recurso pode ser ativado e desativado no Configurações. Esta configuração é definida como true por WalletPluginService. Se QuickAccessWallet não for 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 desativado pelo usuário nas 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 o CTS e o manual provas. As mudanças no plug-in também devem exercitar o testes Robolectric.

Testes CTS

Execute os testes CTS localizados em cts/tests/quickaccesswallet

Testes manuais do Android 12

Testar os principais recursos da Carteira de acesso rápido exige um pagamento NFC real ou falso, e um app de pagamento NFC que implemente QuickAccessWalletService (app de carteira). Principais recursos que precisam ser testados incluem: disponibilidade, estado zero, seleção de cartões e comportamento da tela de bloqueio.

Disponibilidade

Se o app padrão de pagamento por aproximação não for compatível com o recurso, o Quick O Access Wallet não pode ser acessado nas configurações rápidas nem no bloqueio tela.
Se o app padrão de pagamento por aproximação oferecer suporte ao recurso, o Acesso rápido A Carteira pode ser acessada na aba de configurações rápidas.
Se o app padrão de pagamento por aproximação for compatível com o recurso e se o A configuração LOCKSCREEN_SHOW_WALLET é true, a Carteira de acesso rápido é acessíveis na tela de bloqueio.
Se o app padrão de pagamento por aproximação for compatível com o recurso e se o A configuração LOCKSCREEN_SHOW_WALLET é false, o que acontece com o Acesso rápido à Carteira acessíveis na tela de bloqueio.

Estado zero

Se QuickAccessWalletService for ativado e exportado, fornecer cartões, o bloco na sombra aparecerá como mostrado no exemplo na Figura 7. Um clique no bloco abre o app padrão de pagamento por aproximação.

Figura 7. Exemplo de bloco na tonalidade que mostra o app padrão de pagamento por aproximação.
Clicar na visualização de estado vazio, como mostrado na Figura 8, abre a padrão do app de pagamento por aproximação. Essa visualização de estado vazio é exibida somente quando o o usuário tem um cartão na carteira, remove-o dos detalhes do cartão; e volta para a visualização da carteira.
A tela de bloqueio mostra o ícone de carteira.

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

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

Estado diferente de zero

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

Figura 9. Exemplo de bloco na aba quando o app de carteira tem um ou mais cartões.
Um clique no bloco mostra um carrossel de cards.
A tela de bloqueio mostra um botão que abre o Acesso rápido à carteira.

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, segurando o smartphone a um terminal de pagamento NFC resulta no uso dessa forma de pagamento e a visualização de carteira será dispensada.
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 é capaz de 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 pode alterar a opção Mostrar carteira.

Testes de estado de bloqueio

Se o smartphone estiver bloqueado, a carteira vai aparecer nas Configurações rápidas tonalidade, com uma descrição de Adicionar um cartão se nenhum cartão existir na cor app de pagamento, ou desbloqueie para usar, se houver cartões no aplicativo de pagamento padrão.
Se o smartphone estiver bloqueado, a visibilidade da carteira na tela de bloqueio será controlado pela configuração Secure.LOCKSCREEN_SHOW_WALLET, que é controlado em "Configurações".
Se o smartphone estiver bloqueado, o valor de LOCKSCREEN_SHOW_WALLET vai ser false e nenhum cartão existir no app padrão de pagamento por aproximação, a carteira não será exibida no tela de bloqueio.
Se o smartphone estiver bloqueado, o valor de LOCKSCREEN_SHOW_WALLET vai ser true e nenhum cartão existir no app padrão de pagamento por aproximação, a carteira não será exibida no tela de bloqueio.
Se o smartphone estiver bloqueado, o valor de LOCKSCREEN_SHOW_WALLET será true, e os cartões existem no app padrão de pagamento por aproximação, a carteira é mostrada na fechadura tela.
Desbloquear o smartphone enquanto a carteira é mostrada na fechadura tela resulta em uma nova consulta dos cartões, o que pode resultar em conteúdos de cards diferentes.

Testes de acessibilidade

Os usuários do Talkback podem navegar pela visualização de 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 um card por vez. Os usuários do Talkback podem selecionar e usar uma forma de pagamento NFC em um pagamento por aproximação terminal.

Testes manuais para o Android 11

Testar os principais recursos da Carteira de acesso rápido exige um pagamento NFC real ou falso, e um app de pagamento NFC que implemente QuickAccessWalletService (app de carteira). Principais recursos que precisam ser testados incluem disponibilidade, estado zero, seleção de cartões e comportamento da tela de bloqueio.