Esta página se ha traducido con Cloud Translation API.

Cartera de acceso rápido

La función Quick Access Wallet, disponible a partir de Android 11, permite al usuario acceder a tarjetas de pago y pases relevantes directamente desde el menú de encendido. Los principales casos de uso incluyen seleccionar el método de pago adecuado antes de realizar una transacción en una terminal NFC y acceder rápidamente a vuelos y otros pases para próximos eventos.

En Android 12 o superior, la función Quick Access Wallet está disponible en la pantalla como se muestra en la Figura 1 y la Figura 2.

Función Quick Access Wallet en sombra — **Figura 1.** Función Cartera de acceso rápido (dispositivo bloqueado).

En Android 11, la función está disponible desde el menú de encendido, como se muestra en la Figura 3.

Función Quick Access Wallet en el menú de encendido — **Figura 3.** Función Cartera de acceso rápido en el menú de encendido.

Requisitos

Su dispositivo debe tener NFC para utilizar la función Quick Access Wallet. La función se vincula a QuickAccessWalletService de la aplicación de pago NFC predeterminada, lo que significa que el dispositivo también debe admitir la emulación de tarjeta basada en host (HCE) NFC.

Descripción general de las funciones

Hay dos partes en Quick Access Wallet: la interfaz de usuario de Quick Access Wallet y el proveedor de la tarjeta Quick Access Wallet.

En Android 12 o superior, la interfaz de usuario de Wallet se ejecuta en la interfaz de usuario del sistema y se encuentra en frameworks/base/packages/SystemUI/src/com/android/systemui/wallet . En Android 11, la interfaz de usuario de Wallet, que se encuentra en platform/packages/apps/QuickAccessWallet , debe estar instalada y incluida en la lista blanca.

El proveedor de la tarjeta Quick Access Wallet es la aplicación de pago NFC predeterminada. Los usuarios pueden tener varias aplicaciones de pago NFC instaladas simultáneamente, pero solo la aplicación de pago NFC predeterminada puede mostrar tarjetas en el menú de encendido. Puede especificar qué aplicación de pago NFC está configurada como predeterminada inicialmente, pero los usuarios pueden seleccionar una aplicación diferente en Configuración. Si solo hay instalada una aplicación de pago NFC, se convierte en la predeterminada automáticamente (consulte CardEmulationManager ).

Implementación

Para proporcionar tarjetas a la interfaz de usuario de Quick Access Wallet, las aplicaciones de pago NFC deben implementar QuickAccessWalletService . Las aplicaciones de pago deben incluir una entrada de manifiesto que anuncie el servicio.

Para garantizar que solo la interfaz de usuario del sistema pueda vincularse a QuickAccessWalletService , la aplicación de pago NFC debe requerir el permiso android.permission.BIND_QUICK_ACCESS_WALLET_SERVICE . Requerir este permiso garantiza que solo la interfaz de usuario del sistema pueda vincularse 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>

Se incluye información adicional sobre la billetera en el archivo 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"/>

A continuación, la aplicación de pago debe 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
    }
}

Si HostApduService comienza a manejar una transacción NFC y, como consecuencia, inicia una actividad para mostrar el progreso y el resultado del pago, también debería intentar obtener una referencia al QuickAccessWalletService vinculado y llamar a QuickAccessWalletService#sendEvent con un tipo de evento de TYPE_NFC_PAYMENT_STARTED . . Esto hace que se descarte la interfaz de usuario de Quick Access Wallet, lo que permite al usuario una vista sin obstáculos de la actividad de pago.

Para obtener documentación adicional sobre la implementación QuickAccessWalletService , consulte QuickAccessWalletService y la prueba CTS TestQuickAccessWalletService .

Habilitación de la interfaz de usuario de Wallet de acceso rápido en Android 11

Para configurar Quick Access Wallet para que esté disponible desde el menú de encendido en Android 11, incluya el destino QuickAccessWallet en la compilación y habilite el complemento globalactions.wallet agregando la línea en negrita en el ejemplo de código siguiente a overlay/frameworks/base/packages/SystemUI/res/values/config.xml archivo.

<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 la aplicación de pago NFC predeterminada en el archivo de configuración usando def_nfc_payment_component .

La aplicación de pago NFC predeterminada debe exponer QuickAccessWalletService para proporcionar tarjetas a Quick Access Wallet. Si la aplicación de pago NFC predeterminada no exporta este servicio, la interfaz de usuario de la billetera está oculta.

Detalles de implementación de QuickAccessWalletService

QuickAccessWalletService tiene tres métodos abstractos que deben implementarse: onWalletCardsRequested , onWalletCardSelected y onWalletDismissed . El diagrama de secuencia a continuación ilustra una secuencia de llamadas cuando se ve la billetera de acceso rápido inmediatamente antes de un pago NFC.

Diagrama de secuencia de billetera de acceso rápido

Secuencia de llamada de ejemplo cuando se visualiza Quick Access Wallet — **Figura 4.** Ejemplo de secuencia de llamadas cuando se visualiza Quick Access Wallet.

No todas las vistas de Quick Access Wallet van seguidas de un pago NFC, pero la Figura 4 anterior ilustra todas las capacidades de QuickAccessWalletService . En este ejemplo, el proveedor de la tarjeta Quick Access Wallet implementa los elementos resaltados en azul. Se supone que las tarjetas de pago se almacenan en el dispositivo en una base de datos y se accede a ellas a través de una interfaz denominada PaymentCardManager . Además, se supone que una actividad llamada PaymentActivity muestra el resultado de un pago NFC. El flujo se desarrolla de la siguiente manera:

El usuario realiza un gesto para abrir Quick Access Wallet.
La interfaz de usuario de Quick Access Wallet (parte de la interfaz de usuario del sistema) verifica el administrador de paquetes para ver si la aplicación de pago NFC predeterminada exporta QuickAccessWalletService .
- Si el servicio no se exporta, no se muestra Quick Access Wallet.
La interfaz de usuario de Quick Access Wallet se vincula a QuickAccessWalletService y llama onWalletCardsRequested . Este método toma un objeto de solicitud que contiene datos sobre la cantidad y el tamaño de las tarjetas que se pueden proporcionar y una devolución de llamada. La devolución de llamada se puede llamar desde un hilo en segundo plano.
QuickAccessWalletService calcula las tarjetas que quiere mostrar y luego llama al método onSuccess en la devolución de llamada proporcionada. Se recomienda que el servicio realice estas acciones en un hilo en segundo plano.
Tan pronto como se muestran las tarjetas, la interfaz de usuario del sistema notifica a QuickAccessWalletService que se seleccionó la primera tarjeta llamando onWalletCardSelected .
- Se llama onWalletCardSelected cada vez que el usuario selecciona una nueva tarjeta.
- Se puede llamar onWalletCardSelected incluso si la tarjeta seleccionada actualmente no ha cambiado.
Cuando el usuario descarta Quick Access Wallet, la interfaz de usuario del sistema notifica a QuickAccessWalletService llamando a onWalletDismissed .

En el ejemplo anterior, el usuario acerca el teléfono al alcance de un terminal de pago NFC mientras se muestra la billetera. Un componente clave del manejo de pagos NFC es HostApduService , que debe implementarse para procesar las APDU proporcionadas por el lector NFC (para obtener más información, consulte Emulación de tarjetas basada en host ). Se supone que la aplicación de pago inicia una actividad para mostrar el progreso y resultado de la interacción con el terminal NFC. Sin embargo, la interfaz de usuario de Quick Access Wallet se muestra en la parte superior de la ventana de la aplicación, lo que significa que la actividad de pago queda oculta por la interfaz de usuario de Quick Access Wallet. Para rectificar esto, la aplicación debe notificar a la interfaz de usuario del sistema que se debe descartar la interfaz de usuario de Quick Access Wallet. Puede hacerlo obteniendo una referencia al QuickAccessWalletService vinculado y llamando a sendWalletServiceEvent con el tipo de evento TYPE_NFC_PAYMENT_STARTED .

Implementación de muestra de 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 obtener más detalles sobre QuickAccessWalletService , consulte la referencia de la API QuickAccessWalletService .

Permisos

La entrada del manifiesto para QuickAccessWalletService debe requerir el permiso android.permission.BIND_QUICK_ACCESS_WALLET_SERVICE introducido en Android 11. Este es un permiso de nivel de firma mantenido por la interfaz de usuario del sistema, lo que significa que solo el proceso de la interfaz de usuario del sistema puede vincularse a implementaciones de QuickAccessWalletService . Tenga en cuenta que las aplicaciones de carga lateral pueden reclamar este permiso y obtener acceso completo a los datos QuickAccessWalletService en dispositivos con Android 10 o inferior. Para evitar esto, se recomienda que el servicio verifique la versión de compilación en onCreate y habilite el servicio solo en dispositivos con Android 11 y versiones posteriores. No se requieren otros permisos de la aplicación más allá de los necesarios para proporcionar servicios de pago de emulación de tarjeta de host.

Si la aplicación de pago NFC predeterminada no implementa ni exporta QuickAccessWalletService , no se muestra la interfaz de usuario de Quick Access Wallet.

Configuraciones en Android 12

Para habilitar o deshabilitar la Cartera de acceso rápido desde la pantalla de bloqueo, los usuarios pueden usar la opción Mostrar billetera en Configuración > Pantalla > Pantalla de bloqueo . Para desactivar la billetera en la sombra, los usuarios deben editarla manualmente en la sombra de configuración rápida.

Alternar para habilitar o deshabilitar la billetera desde la pantalla de bloqueo

Figura 5. Mostrar alternancia de billetera en la página de la pantalla de bloqueo en Configuración.

Configuraciones en Android 11

Los usuarios pueden desactivar la función Quick Access Wallet desde la aplicación Configuración. La página de configuración se encuentra en Configuración > Sistema > Gestos > Tarjetas y pases .

**Figura 6.** Página de configuración para habilitar o deshabilitar la función Quick Access Wallet.

Personalización

Agregar la vista Cartera de acceso rápido a otra ubicación en la interfaz de usuario del sistema

La interfaz de usuario de Quick Access Wallet está diseñada como un complemento del sistema . Aunque la implementación de AOSP lo utiliza en GlobalActionsDialog (que se muestra al presionarlo prolongadamente), puede mover la función detrás de un gesto diferente siempre que mantenga el contrato especificado por la interfaz del complemento.

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);
  }
}

La interfaz de usuario de Quick Access Wallet implementa GlobalActionsPanelPlugin y PanelViewController . GlobalActionsDialog obtiene una instancia del complemento de billetera usando com.android.systemui.Dependency :

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

Después de comprobar que el complemento no es nulo y que el PanelViewController devuelto por onPanelShown no es nulo, el cuadro de diálogo adjunta la View proporcionada por getPanelContent a su propia View y proporciona devoluciones de llamada apropiadas para los eventos del 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 eliminar Quick Access Wallet del menú de encendido, omita el destino QuickAccessWallet de la compilación del sistema. Para eliminar Quick Access Wallet del menú de encendido pero agregarlo a una vista proporcionada por la interfaz de usuario del sistema diferente, incluya el destino de compilación y elimine las referencias a GlobalActionsPanelPlugin de GlobalActionsImpl .

Establecer configuraciones predeterminadas

androide 12

En Android 12 o superior, Quick Access Wallet siempre está visible en el tono de configuración rápida. La visibilidad de Quick Access Wallet en la pantalla de bloqueo está controlada por la siguiente configuración segura: LOCKSCREEN_SHOW_WALLET . Esta configuración controla si el ícono de Quick Access Wallet se muestra en la parte inferior derecha de la pantalla de bloqueo. Esta configuración está configurada como true de forma predeterminada, pero el usuario puede desactivarla en Configuración > Pantalla > Pantalla de bloqueo > Mostrar billetera .

androide 11

En Android 11, la visibilidad de Quick Access Wallet está controlada por dos configuraciones seguras: GLOBAL_ACTIONS_PANEL_ENABLED y GLOBAL_ACTIONS_PANEL_AVAILABLE . La configuración AVAILABLE controla si la función se puede activar y desactivar en Configuración. WalletPluginService establece esta configuración en true . Si QuickAccessWallet no está incluido en la compilación, la configuración sigue siendo false . La configuración ENABLED está establecida en true de forma predeterminada en el mismo lugar, pero el usuario puede desactivarla en Configuración. Para cambiar el comportamiento predeterminado, modifique WalletPluginService#enableFeatureInSettings .

Validación

Para validar su implementación de Quick Access Wallet, ejecute CTS y pruebas manuales. Los cambios en el complemento también deberían ejercitar las pruebas roboeléctricas incluidas.

pruebas CTS

Ejecute las pruebas CTS ubicadas en cts/tests/quickaccesswallet .

Pruebas manuales para Android 12

Probar las funciones principales de Quick Access Wallet requiere una terminal de pago NFC (real o falsa) y una aplicación de pago NFC que implemente QuickAccessWalletService (aplicación de billetera). Las características principales que deben probarse incluyen: disponibilidad, estado cero, selección de tarjeta y comportamiento de la pantalla de bloqueo.

Disponibilidad

Si la aplicación de pago NFC predeterminada no admite la función, no se puede acceder a Quick Access Wallet ni en la configuración rápida ni en la pantalla de bloqueo.
Si la aplicación de pago NFC predeterminada admite la función, se puede acceder a Quick Access Wallet en la pantalla de configuración rápida.
Si la aplicación de pago NFC predeterminada admite la función y si la configuración LOCKSCREEN_SHOW_WALLET es true , se puede acceder a Quick Access Wallet en la pantalla de bloqueo.
Si la aplicación de pago NFC predeterminada admite la función y si la configuración LOCKSCREEN_SHOW_WALLET es false , no se podrá acceder a Quick Access Wallet desde la pantalla de bloqueo.

Estado cero

Si QuickAccessWalletService está habilitado y exportado pero no proporciona ninguna tarjeta, el mosaico en Shade aparece como se muestra en el ejemplo de la Figura 7. Al hacer clic en el mosaico se abre la aplicación de pago NFC predeterminada.
Figura 7. Mosaico de ejemplo en la sombra que muestra la aplicación de pago NFC predeterminada.
Al hacer clic en la vista de estado vacía como se muestra en la Figura 8, se abre la aplicación de pago NFC predeterminada. Esta vista de estado vacío se muestra solo cuando al usuario le queda una tarjeta en la billetera, la quita de la página de detalles de la tarjeta y luego regresa a la vista de la billetera.
La pantalla de bloqueo muestra el ícono de la billetera.

Vista de estado vacío en Quick Access Wallet

Figura 8. Vista de estado vacío en la interfaz de usuario de Quick Access Wallet.

Estado distinto de cero

Si la aplicación de billetera proporciona una o más tarjetas, el mosaico en la sombra aparece como se muestra en la Figura 9.
Figura 9. Ejemplo de mosaico en la sombra cuando la aplicación de billetera tiene una o más tarjetas.
Al hacer clic en el mosaico se muestra un carrusel de tarjetas.
La pantalla de bloqueo muestra un botón que abre la Cartera de acceso rápido.
Figura 10. UI de acceso rápido a Wallet con una tarjeta mostrada.
Si la tarjeta mostrada representa un método de pago NFC, al acercar el teléfono a una terminal de pago NFC se utiliza ese método de pago y se descarta la vista de billetera.
Al hacer clic en una tarjeta mostrada, se abre la actividad detallada de esa tarjeta.
Si QuickAccessWalletService proporciona varias tarjetas, el usuario puede pasar entre tarjetas.
El menú adicional contiene una entrada: abra la configuración de la pantalla de bloqueo para que el usuario pueda cambiar la opción Mostrar billetera .

Pruebas de estado de bloqueo

Si el teléfono está bloqueado, la billetera es visible en la pantalla de configuración rápida, con una descripción de Agregar una tarjeta si no existe ninguna tarjeta en la aplicación de pago predeterminada, o desbloquearla para usarla si existen tarjetas en la aplicación de pago predeterminada.
Si el teléfono está bloqueado, la visibilidad de la billetera en la pantalla de bloqueo se controla mediante la configuración Secure.LOCKSCREEN_SHOW_WALLET , que se controla en Configuración.
Si el teléfono está bloqueado, LOCKSCREEN_SHOW_WALLET es false y no existe ninguna tarjeta en la aplicación de pago NFC predeterminada, la billetera no se muestra en la pantalla de bloqueo.
Si el teléfono está bloqueado, LOCKSCREEN_SHOW_WALLET es true y no existe ninguna tarjeta en la aplicación de pago NFC predeterminada, la billetera no se muestra en la pantalla de bloqueo.
Si el teléfono está bloqueado, LOCKSCREEN_SHOW_WALLET es true y existen tarjetas en la aplicación de pago NFC predeterminada, la billetera se muestra en la pantalla de bloqueo.
Al desbloquear el teléfono mientras se muestra la billetera en la pantalla de bloqueo, se vuelven a consultar las tarjetas, lo que puede resultar en un contenido diferente de la tarjeta.

Pruebas de accesibilidad

Los usuarios de Talkback pueden navegar por la vista de billetera deslizándose hacia la izquierda y hacia la derecha y escuchando las descripciones del contenido de las tarjetas.
Al deslizar el dedo hacia la izquierda y hacia la derecha con Talkback habilitado, se selecciona cada tarjeta por turno. Los usuarios de Talkback pueden seleccionar y utilizar un método de pago NFC en una terminal de pago NFC.

Pruebas manuales para Android 11

Probar las funciones principales de Quick Access Wallet requiere una terminal de pago NFC (real o falsa) y una aplicación de pago NFC que implemente QuickAccessWalletService (aplicación de billetera). Las funciones principales que deben probarse incluyen disponibilidad, estado cero, selección de tarjeta y comportamiento de la pantalla de bloqueo.