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 WalletCard
s 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:
- The application hosting the QuickAccessWalletService is also the default NFC payment
application. This means that the same application must also have a
HostApduService
orOffHostApduService
that requires the android.permission.BIND_NFC_SERVICE permission. - The user explicitly selected the application as the default payment application in the Tap & pay settings screen.
- The QuickAccessWalletService requires that the binding application hold the
android.permission.BIND_QUICK_ACCESS_WALLET_SERVICE
permission, which only the System Service can hold. - 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:
- User performs a gesture to bring up the Quick Access Wallet, which is displayed by the Android System.
- The Android System creates a
GetWalletCardsRequest
, binds to theQuickAccessWalletService
, and delivers the request. - The service receives the request through
onWalletCardsRequested(GetWalletCardsRequest, GetWalletCardsCallback)
- The service responds by calling
GetWalletCardsCallback#onSuccess
with aresponse
that contains between 1 andmaxCards
cards. - 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. - 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)
. - 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 thecardId
of the card that is now selected. - 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 aWalletServiceEvent
of typeWalletServiceEvent#TYPE_NFC_PAYMENT_STARTED
should cause the quick access wallet UI to be dismissed. - 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 |
String |
SERVICE_META_DATA
Name under which a QuickAccessWalletService component publishes information about itself. |
Inherited constants | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
From class
android.app.Service
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From class
android.content.Context
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From interface
android.content.ComponentCallbacks2
|
Public constructors | |
---|---|
QuickAccessWalletService()
|
Public methods | |
---|---|
PendingIntent
|
getTargetActivityPendingIntent()
Specify a |
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 |
Inherited methods | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
From class
android.app.Service
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From class
android.content.ContextWrapper
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From class
android.content.Context
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From class
java.lang.Object
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From interface
android.content.ComponentCallbacks2
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From interface
android.content.ComponentCallbacks
|
Constants
ACTION_VIEW_WALLET
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
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
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
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
<
tag. This
is a a sample XML file configuring an QuickAccessWalletService:
quickaccesswallet-service
>
<quickaccesswallet-service android:walletActivity="foo.bar.WalletActivity" . . . />
Constant Value: "android.quickaccesswallet"
Public constructors
QuickAccessWalletService
public QuickAccessWalletService ()
Public methods
getTargetActivityPendingIntent
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
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
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
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
public abstract void onWalletDismissed ()
Indicates that the wallet was dismissed. This is received when the Quick Access Wallet is no longer visible.
sendWalletServiceEvent
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 . |