QuickAccessWalletService

public abstract class QuickAccessWalletService
extends Service

java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ android.service.quickaccesswallet.QuickAccessWalletService


A QuickAccessWalletService provides a list of WalletCards shown in the Quick Access Wallet. The Quick Access Wallet allows the user to change their selected payment method and access other important passes, such as tickets and transit passes, without leaving the context of their current app.

An QuickAccessWalletService is only bound to the Android System for the purposes of showing wallet cards if:

  1. The application hosting the QuickAccessWalletService is also the default NFC payment application. This means that the same application must also have a HostApduService or OffHostApduService that requires the android.permission.BIND_NFC_SERVICE permission.
  2. The user explicitly selected the application as the default payment application in the Tap & pay settings screen.
  3. The QuickAccessWalletService requires that the binding application hold the android.permission.BIND_QUICK_ACCESS_WALLET_SERVICE permission, which only the System Service can hold.
  4. The user explicitly enables it using Android Settings (the Settings#ACTION_QUICK_ACCESS_WALLET_SETTINGS intent can be used to launch it).

Basic usage

The basic Quick Access Wallet process is defined by the workflow below:

  1. User performs a gesture to bring up the Quick Access Wallet, which is displayed by the Android System.
  2. The Android System creates a GetWalletCardsRequest, binds to the QuickAccessWalletService, and delivers the request.
  3. The service receives the request through onWalletCardsRequested(GetWalletCardsRequest, GetWalletCardsCallback)
  4. The service responds by calling GetWalletCardsCallback#onSuccess with a response that contains between 1 and maxCards cards.
  5. The Android System displays the Quick Access Wallet containing the provided cards. The card at the selectedIndex will initially be presented as the 'selected' card.
  6. As soon as the cards are displayed, the Android System will notify the service that the card at the selected index has been selected through onWalletCardSelected(SelectWalletCardRequest).
  7. The user interacts with the wallet and may select one or more cards in sequence. Each time a new card is selected, the Android System will notify the service through onWalletCardSelected(SelectWalletCardRequest) and will provide the cardId of the card that is now selected.
  8. If the user commences an NFC payment, the service may send a WalletServiceEvent to the System indicating that the wallet application now needs to show the activity associated with making a payment. Sending a WalletServiceEvent of type WalletServiceEvent#TYPE_NFC_PAYMENT_STARTED should cause the quick access wallet UI to be dismissed.
  9. When the wallet is dismissed, the Android System will notify the service through onWalletDismissed().

The workflow is designed to minimize the time that the Android System is bound to the service, but connections may be cached and reused to improve performance and conserve memory. All calls should be considered stateless: if the service needs to keep state between calls, it must do its own state management (keeping in mind that the service's process might be killed by the Android System when unbound; for example, if the device is running low in memory).

Error handling

If the service encountered an error processing the request, it should call GetWalletCardsCallback#onFailure. For performance reasons, it's paramount that the service calls either GetWalletCardsCallback#onSuccess or GetWalletCardsCallback#onFailure for each onWalletCardsRequested(GetWalletCardsRequest, GetWalletCardsCallback) received - if it doesn't, the request will eventually time out and be discarded by the Android System.

Manifest entry

QuickAccessWalletService must require the permission "android.permission.BIND_QUICK_ACCESS_WALLET_SERVICE".

 <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" />;
 </service>
 

The <meta-data> element includes an android:resource attribute that points to an XML resource with further details about the service. The quickaccesswallet_configuration in the example above specifies an activity that allows the users to view the entire wallet. The following example shows the quickaccesswallet_configuration XML resource:

 <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"/>
 
 

The entry for settingsActivity should contain the fully qualified class name of an activity that allows the user to modify the settings for this service. The targetActivity entry should contain the fully qualified class name of an activity that allows the user to view their entire wallet. The targetActivity will be started with the Intent action ACTION_VIEW_WALLET and the settingsActivity will be started with the Intent action ACTION_VIEW_WALLET_SETTINGS.

The shortcutShortLabel and shortcutLongLabel are used by the QuickAccessWallet in the buttons that navigate to the wallet app. The shortcutShortLabel is displayed next to the cards that are returned by the service and should be no more than 20 characters. The shortcutLongLabel is displayed when no cards are returned. This 'empty state' view also displays the service logo, specified by the android:logo manifest entry. If the logo is not specified, the empty state view will show the app icon instead.

Summary

Constants

String ACTION_VIEW_WALLET

Intent action to launch an activity to display the wallet.

String ACTION_VIEW_WALLET_SETTINGS

Intent action to launch an activity to display quick access wallet settings.

String SERVICE_INTERFACE

The Intent that must be declared as handled by the service.

String SERVICE_META_DATA

Name under which a QuickAccessWalletService component publishes information about itself.

Inherited constants

Public constructors

QuickAccessWalletService()

Public methods

PendingIntent getTargetActivityPendingIntent()

Specify a PendingIntent to be launched as the "Quick Access" activity.

IBinder onBind(Intent intent)

Return the communication channel to the service.

abstract void onWalletCardSelected(SelectWalletCardRequest request)

A wallet card was selected.

abstract void onWalletCardsRequested(GetWalletCardsRequest request, GetWalletCardsCallback callback)

Called when the user requests the service to provide wallet cards.

abstract void onWalletDismissed()

Indicates that the wallet was dismissed.

final void sendWalletServiceEvent(WalletServiceEvent serviceEvent)

Send a WalletServiceEvent to the Quick Access Wallet.

Inherited methods

Constants

ACTION_VIEW_WALLET

Added in API level 30
public static final String ACTION_VIEW_WALLET

Intent action to launch an activity to display the wallet.

Constant Value: "android.service.quickaccesswallet.action.VIEW_WALLET"

ACTION_VIEW_WALLET_SETTINGS

Added in API level 30
public static final String ACTION_VIEW_WALLET_SETTINGS

Intent action to launch an activity to display quick access wallet settings.

Constant Value: "android.service.quickaccesswallet.action.VIEW_WALLET_SETTINGS"

SERVICE_INTERFACE

Added in API level 30
public static final String SERVICE_INTERFACE

The Intent that must be declared as handled by the service. To be supported, the service must also require the Manifest.permission.BIND_QUICK_ACCESS_WALLET_SERVICE permission so that other applications can not abuse it.

Constant Value: "android.service.quickaccesswallet.QuickAccessWalletService"

SERVICE_META_DATA

Added in API level 30
public static final String SERVICE_META_DATA

Name under which a QuickAccessWalletService component publishes information about itself. This meta-data should reference an XML resource containing a <quickaccesswallet-service> tag. This is a a sample XML file configuring an QuickAccessWalletService:

 <quickaccesswallet-service
     android:walletActivity="foo.bar.WalletActivity"
     . . .
 />

Constant Value: "android.quickaccesswallet"

Public constructors

QuickAccessWalletService

public QuickAccessWalletService ()

Public methods

getTargetActivityPendingIntent

Added in API level 33
public PendingIntent getTargetActivityPendingIntent ()

Specify a PendingIntent to be launched as the "Quick Access" activity. This activity will be launched directly by the system in lieu of the card switcher activity provided by the system. In order to use the system-provided card switcher activity, return null from this method.

Returns
PendingIntent

onBind

Added in API level 30
public IBinder onBind (Intent intent)

Return the communication channel to the service. May return null if clients can not bind to the service. The returned IBinder is usually for a complex interface that has been described using aidl.

Note that unlike other application components, calls on to the IBinder interface returned here may not happen on the main thread of the process. More information about the main thread can be found in Processes and Threads.

Parameters
intent Intent: This value cannot be null.

Returns
IBinder This value may be null.

onWalletCardSelected

Added in API level 30
public abstract void onWalletCardSelected (SelectWalletCardRequest request)

A wallet card was selected. Sent when the user selects a wallet card from the list of cards. Selection may indicate that the card is now in the center of the screen, or highlighted in some other fashion. It does not mean that the user clicked on the card -- clicking on the card will cause the WalletCard#getPendingIntent() to be sent.

Card selection events are especially important to NFC payment applications because many NFC terminals can only accept one payment card at a time. If the user has several NFC cards in their wallet, selecting different cards can change which payment method is presented to the terminal.

Parameters
request SelectWalletCardRequest: This value cannot be null.

onWalletCardsRequested

Added in API level 30
public abstract void onWalletCardsRequested (GetWalletCardsRequest request, 
                GetWalletCardsCallback callback)

Called when the user requests the service to provide wallet cards.

This method will be called on the main thread, but the callback may be called from any thread. The callback should be called as quickly as possible. The service must always call either GetWalletCardsCallback#onSuccess(GetWalletCardsResponse) or GetWalletCardsCallback.onFailure(android.service.quickaccesswallet.GetWalletCardsError). Calling multiple times or calling both methods will cause an exception to be thrown.

Parameters
request GetWalletCardsRequest: This value cannot be null.

callback GetWalletCardsCallback: This value cannot be null.

onWalletDismissed

Added in API level 30
public abstract void onWalletDismissed ()

Indicates that the wallet was dismissed. This is received when the Quick Access Wallet is no longer visible.

sendWalletServiceEvent

Added in API level 30
public final void sendWalletServiceEvent (WalletServiceEvent serviceEvent)

Send a WalletServiceEvent to the Quick Access Wallet.

Background events may require that the Quick Access Wallet view be updated. For example, if the wallet application hosting this service starts to handle an NFC payment while the Quick Access Wallet is being shown, the Quick Access Wallet will need to be dismissed so that the Activity showing the payment can be displayed to the user.

Parameters
serviceEvent WalletServiceEvent: This value cannot be null.