1 /* 2 * Copyright 2020 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.service.quickaccesswallet; 18 19 import android.annotation.CallbackExecutor; 20 import android.annotation.NonNull; 21 import android.annotation.Nullable; 22 import android.annotation.TestApi; 23 import android.app.PendingIntent; 24 import android.content.Context; 25 import android.content.Intent; 26 import android.graphics.drawable.Drawable; 27 28 import java.io.Closeable; 29 import java.util.concurrent.Executor; 30 31 /** 32 * Facilitates accessing cards from the {@link QuickAccessWalletService}. 33 * 34 * @hide 35 */ 36 @TestApi 37 public interface QuickAccessWalletClient extends Closeable { 38 39 /** 40 * Create a client for accessing wallet cards from the {@link QuickAccessWalletService}. If the 41 * service is unavailable, {@link #isWalletServiceAvailable()} will return false. 42 */ 43 @NonNull create(@onNull Context context)44 static QuickAccessWalletClient create(@NonNull Context context) { 45 return create(context, null /* bgExecutor */); 46 } 47 48 /** 49 * Create a client for accessing wallet cards from the {@link QuickAccessWalletService}. If the 50 * service is unavailable, {@link #isWalletServiceAvailable()} will return false. 51 * @param context Context. 52 * @param bgExecutor A background {@link Executor} for service registration. 53 * @hide 54 */ 55 @NonNull create(@onNull Context context, @Nullable Executor bgExecutor)56 static QuickAccessWalletClient create(@NonNull Context context, @Nullable Executor bgExecutor) { 57 return new QuickAccessWalletClientImpl(context, bgExecutor); 58 } 59 60 /** 61 * @return true if the {@link QuickAccessWalletService} is available. This means that the 62 * default NFC payment application has an exported service that can provide cards to the Quick 63 * Access Wallet. However, it does not mean that (1) the call will necessarily be successful, 64 * nor does it mean that cards may be displayed at this time. Addition checks are required: 65 * <ul> 66 * <li>If {@link #isWalletFeatureAvailable()} is false, cards should not be displayed 67 * <li>If the device is locked and {@link #isWalletFeatureAvailableWhenDeviceLocked} is 68 * false, cards should not be displayed while the device remains locked. (A message 69 * prompting the user to unlock to view cards may be appropriate).</li> 70 * </ul> 71 */ isWalletServiceAvailable()72 boolean isWalletServiceAvailable(); 73 74 /** 75 * Wallet cards should not be displayed if: 76 * <ul> 77 * <li>The wallet service is unavailable</li> 78 * <li>The device is not provisioned, ie user setup is incomplete</li> 79 * <li>If the wallet feature has been disabled by the user</li> 80 * <li>If the phone has been put into lockdown mode</li> 81 * </ul> 82 * <p> 83 * Quick Access Wallet implementers should call this method before calling 84 * {@link #getWalletCards} to ensure that cards may be displayed. 85 */ isWalletFeatureAvailable()86 boolean isWalletFeatureAvailable(); 87 88 /** 89 * Wallet cards may not be displayed on the lock screen if the user has opted to hide 90 * notifications or sensitive content on the lock screen. 91 * <ul> 92 * <li>The device is not provisioned, ie user setup is incomplete</li> 93 * <li>If the wallet feature has been disabled by the user</li> 94 * <li>If the phone has been put into lockdown mode</li> 95 * </ul> 96 * 97 * <p> 98 * Quick Access Wallet implementers should call this method before calling 99 * {@link #getWalletCards} if the device is currently locked. 100 * 101 * @return true if cards may be displayed on the lock screen. 102 */ isWalletFeatureAvailableWhenDeviceLocked()103 boolean isWalletFeatureAvailableWhenDeviceLocked(); 104 105 /** 106 * Get wallet cards from the {@link QuickAccessWalletService}. 107 */ getWalletCards( @onNull GetWalletCardsRequest request, @NonNull OnWalletCardsRetrievedCallback callback)108 void getWalletCards( 109 @NonNull GetWalletCardsRequest request, 110 @NonNull OnWalletCardsRetrievedCallback callback); 111 112 /** 113 * Get wallet cards from the {@link QuickAccessWalletService}. 114 */ getWalletCards( @onNull @allbackExecutor Executor executor, @NonNull GetWalletCardsRequest request, @NonNull OnWalletCardsRetrievedCallback callback)115 void getWalletCards( 116 @NonNull @CallbackExecutor Executor executor, 117 @NonNull GetWalletCardsRequest request, 118 @NonNull OnWalletCardsRetrievedCallback callback); 119 120 /** 121 * Callback for getWalletCards 122 */ 123 interface OnWalletCardsRetrievedCallback { onWalletCardsRetrieved(@onNull GetWalletCardsResponse response)124 void onWalletCardsRetrieved(@NonNull GetWalletCardsResponse response); 125 onWalletCardRetrievalError(@onNull GetWalletCardsError error)126 void onWalletCardRetrievalError(@NonNull GetWalletCardsError error); 127 } 128 129 /** 130 * Notify the {@link QuickAccessWalletService} service that a wallet card was selected. 131 */ selectWalletCard(@onNull SelectWalletCardRequest request)132 void selectWalletCard(@NonNull SelectWalletCardRequest request); 133 134 /** 135 * Notify the {@link QuickAccessWalletService} service that the Wallet was dismissed. 136 */ notifyWalletDismissed()137 void notifyWalletDismissed(); 138 139 /** 140 * Register an event listener. 141 */ addWalletServiceEventListener(@onNull WalletServiceEventListener listener)142 void addWalletServiceEventListener(@NonNull WalletServiceEventListener listener); 143 144 /** 145 * Register an event listener. 146 */ addWalletServiceEventListener( @onNull @allbackExecutor Executor executor, @NonNull WalletServiceEventListener listener)147 void addWalletServiceEventListener( 148 @NonNull @CallbackExecutor Executor executor, 149 @NonNull WalletServiceEventListener listener); 150 151 /** 152 * Unregister an event listener 153 */ removeWalletServiceEventListener(@onNull WalletServiceEventListener listener)154 void removeWalletServiceEventListener(@NonNull WalletServiceEventListener listener); 155 156 /** 157 * A listener for {@link WalletServiceEvent walletServiceEvents} 158 */ 159 interface WalletServiceEventListener { onWalletServiceEvent(@onNull WalletServiceEvent event)160 void onWalletServiceEvent(@NonNull WalletServiceEvent event); 161 } 162 163 /** 164 * Unregister all event listeners and disconnect from the service. 165 */ disconnect()166 void disconnect(); 167 168 /** 169 * The QuickAccessWalletService may provide a {@link PendingIntent} to start the activity that 170 * hosts the Wallet view. This is typically the home screen of the Wallet application. If this 171 * method returns null, the value returned by getWalletIntent() will be used instead. 172 */ getWalletPendingIntent(@onNull @allbackExecutor Executor executor, @NonNull WalletPendingIntentCallback walletPendingIntentCallback)173 void getWalletPendingIntent(@NonNull @CallbackExecutor Executor executor, 174 @NonNull WalletPendingIntentCallback walletPendingIntentCallback); 175 176 /** 177 * Callback for getWalletPendingIntent. 178 */ 179 interface WalletPendingIntentCallback { onWalletPendingIntentRetrieved(@ullable PendingIntent walletPendingIntent)180 void onWalletPendingIntentRetrieved(@Nullable PendingIntent walletPendingIntent); 181 } 182 183 /** 184 * The manifest entry for the QuickAccessWalletService may also publish information about the 185 * activity that hosts the Wallet view. This is typically the home screen of the Wallet 186 * application. 187 */ 188 @Nullable createWalletIntent()189 Intent createWalletIntent(); 190 191 /** 192 * The manifest entry for the {@link QuickAccessWalletService} may publish the activity that 193 * hosts the settings 194 */ 195 @Nullable createWalletSettingsIntent()196 Intent createWalletSettingsIntent(); 197 198 /** 199 * Returns the logo associated with the {@link QuickAccessWalletService}. This is specified by 200 * {@code android:logo} manifest entry. If the logo is not specified, the app icon will be 201 * returned instead ({@code android:icon}). 202 * 203 * @hide 204 */ 205 @Nullable getLogo()206 Drawable getLogo(); 207 208 /** 209 * Returns the tile icon associated with the {@link QuickAccessWalletService}. 210 * 211 * @hide 212 */ 213 @Nullable getTileIcon()214 Drawable getTileIcon(); 215 216 /** 217 * Returns the service label specified by {@code android:label} in the service manifest entry. 218 * 219 * @hide 220 */ 221 @Nullable getServiceLabel()222 CharSequence getServiceLabel(); 223 224 /** 225 * Returns the text specified by the {@link android:shortcutShortLabel} in the service manifest 226 * entry. If the shortcutShortLabel isn't specified, the service label ({@code android:label}) 227 * will be returned instead. 228 * 229 * @hide 230 */ 231 @Nullable getShortcutShortLabel()232 CharSequence getShortcutShortLabel(); 233 234 /** 235 * Returns the text specified by the {@link android:shortcutLongLabel} in the service manifest 236 * entry. If the shortcutShortLabel isn't specified, the service label ({@code android:label}) 237 * will be returned instead. 238 * 239 * @hide 240 */ 241 @Nullable getShortcutLongLabel()242 CharSequence getShortcutLongLabel(); 243 } 244