Se usó la API de Cloud Translation para traducir esta página.

Cartera de acceso rápido

La función de billetera de acceso rápido, 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 apropiado 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 de billetera de acceso rápido está disponible desde la pantalla, como se muestra en la Figura 1 y la Figura 2.

Función de billetera de acceso rápido a la sombra — **Figura 1.** Función de billetera 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.

**Figura 3.** Función de billetera de acceso rápido en el menú de encendido.

Requisitos

Su dispositivo debe tener NFC para usar la función de billetera de acceso rápido. La función se vincula con QuickAccessWalletService de la aplicación de pago NFC predeterminada, lo que significa que el dispositivo también debe ser compatible con la emulación de tarjeta basada en host (HCE) NFC.

Resumen de características

La billetera de acceso rápido consta de dos partes: la interfaz de usuario de la billetera de acceso rápido y el proveedor de tarjetas de la billetera de acceso rápido.

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 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 se establece como predeterminada inicialmente, pero los usuarios pueden seleccionar una aplicación diferente en Configuración. Si solo se instala una aplicación de pago NFC, se convierte automáticamente en la predeterminada (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 debe 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 de QuickAccessWalletService , consulte QuickAccessWalletService y la prueba CTS de TestQuickAccessWalletService .

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

Para configurar la billetera de acceso rápido para que esté disponible desde el menú de encendido en Android 11, incluya el destino de la billetera de acceso rápido en la compilación y habilite el globalactions.wallet QuickAccessWallet la línea en negrita en el ejemplo de código a continuación a la 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 mediante 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 siguiente diagrama de secuencia ilustra una secuencia de llamadas cuando se ve la billetera de acceso rápido inmediatamente antes de un pago NFC.

Diagrama de secuencia de la billetera de acceso rápido

Ejemplo de secuencia de llamadas cuando se ve la billetera de acceso rápido — **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 procede de la siguiente manera:

El usuario realiza un gesto para abrir la billetera de acceso rápido.
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, la billetera de acceso rápido no se muestra.
La interfaz de usuario de Quick Access Wallet se vincula con QuickAccessWalletService y llama a onWalletCardsRequested . Este método toma un objeto de solicitud que contiene datos sobre el número 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 subproceso en segundo plano.
QuickAccessWalletService calcula las tarjetas que quiere mostrar, luego llama al método onSuccess en la devolución de llamada proporcionada. Se recomienda que el servicio realice estas acciones en un subproceso 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 a onWalletCardSelected .
- onWalletCardSelected se llama cada vez que el usuario selecciona una nueva tarjeta.
- onWalletCardSelected podría llamarse incluso si la tarjeta seleccionada actualmente no ha cambiado.
Cuando el usuario descarta la billetera de acceso rápido, 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 tarjeta basada en host ). Se supone que la aplicación de pago inicia una actividad para mostrar el progreso y el 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 está oculta por la interfaz de usuario de Quick Access Wallet. Para corregir esto, la aplicación debe notificar a la interfaz de usuario del sistema que se debe descartar la interfaz de usuario de la billetera de acceso rápido. Puede hacerlo obteniendo una referencia al QuickAccessWalletService enlazado y llamando a sendWalletServiceEvent con el tipo de evento TYPE_NFC_PAYMENT_STARTED .

Implementación de ejemplo 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 de 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 que posee la IU del sistema, lo que significa que solo el proceso de la IU del sistema puede vincularse a las implementaciones de QuickAccessWalletService . Tenga en cuenta que las aplicaciones de carga lateral pueden reclamar este permiso y obtener acceso completo a los datos de 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 superior. No se requieren otros permisos de aplicaciones más allá de los necesarios para proporcionar servicios de pago de emulación de tarjeta 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.

Configuración en Android 12

Para habilitar o deshabilitar la billetera 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 deshabilitar 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 la palanca de billetera en la página de la pantalla de bloqueo en Configuración.

Configuración en Android 11

Los usuarios pueden desactivar la función de billetera de acceso rápido 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 de billetera de acceso rápido.

personalización

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

La interfaz de usuario de Quick Access Wallet está construida como un complemento del sistema . Aunque la implementación de AOSP lo utiliza en GlobalActionsDialog (que se muestra con una pulsación prolongada), 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 mediante com.android.systemui.Dependency :

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

Después de verificar que el complemento no sea nulo y que el PanelViewController devuelto por onPanelShown no sea nulo, el cuadro de diálogo adjunta la View proporcionada por getPanelContent a su propia View y proporciona las 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 la billetera de acceso rápido del menú de encendido, QuickAccessWallet el objetivo de la billetera de acceso rápido de la compilación del sistema. Para eliminar la billetera de acceso rápido del menú de encendido pero agregarla a una vista proporcionada por la interfaz de usuario del sistema diferente, incluya el objetivo de compilación y elimine las referencias a GlobalActionsPanelPlugin de GlobalActionsImpl .

Establecer configuraciones predeterminadas

androide 12

En Android 12 o superior, la billetera de acceso rápido siempre está visible en el tono de configuración rápida. La visibilidad de la billetera de acceso rápido en la pantalla de bloqueo está bloqueada por la siguiente configuración segura: LOCKSCREEN_SHOW_WALLET . Esta configuración controla si el ícono de la billetera de acceso rápido se muestra en la parte inferior derecha de la pantalla de bloqueo. Esta configuración está configurada como true de manera 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 se establece 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 un terminal de pago NFC (real o falso) 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 tarjetas y comportamiento de la pantalla de bloqueo.

Disponibilidad

Si la aplicación de pago NFC predeterminada no es compatible con la función, no se puede acceder a la billetera de acceso rápido ni en la configuración rápida ni en la pantalla de bloqueo.
Si la aplicación de pago NFC predeterminada es compatible con la función, se puede acceder a la billetera de acceso rápido 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 es compatible con la función y si la configuración LOCKSCREEN_SHOW_WALLET es false , no se puede acceder a Quick Access Wallet en 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 elimina de la página de detalles de la tarjeta y luego vuelve a la vista de la billetera.
La pantalla de bloqueo muestra el ícono de la billetera.

Vista de estado vacío en la billetera de acceso rápido

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 billetera de acceso rápido.
Figura 10. Interfaz de usuario de Quick Access Wallet con una tarjeta mostrada.
Si la tarjeta que se muestra representa un método de pago NFC, al acercar el teléfono a un terminal de pago NFC, se utilizará ese método de pago y se descartará 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 de una tarjeta a otra.
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 una tarjeta en la aplicación de pago predeterminada, o desbloquear para usar 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 está controlada por 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 las tarjetas existen en la aplicación de pago NFC predeterminada, la billetera se muestra en la pantalla de bloqueo.
Si desbloquea el teléfono mientras se muestra la billetera en la pantalla de bloqueo, se solicitarán las tarjetas, lo que podría generar un contenido de tarjeta diferente.

Pruebas de accesibilidad

Los usuarios de Talkback pueden navegar por la vista de la billetera deslizando el dedo 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 activado, se selecciona cada tarjeta por turno. Los usuarios de Talkback pueden seleccionar y usar 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 un terminal de pago NFC (real o falso) 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 tarjetas y comportamiento de la pantalla de bloqueo.