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.FlaggedApi; 21 import android.annotation.NonNull; 22 import android.annotation.Nullable; 23 import android.annotation.TestApi; 24 import android.app.PendingIntent; 25 import android.content.Context; 26 import android.content.Intent; 27 import android.graphics.drawable.Drawable; 28 import android.os.UserHandle; 29 30 import java.io.Closeable; 31 import java.util.concurrent.Executor; 32 33 /** 34 * Facilitates accessing cards from the {@link QuickAccessWalletService}. 35 * 36 * @hide 37 */ 38 @TestApi 39 public interface QuickAccessWalletClient extends Closeable { 40 41 /** 42 * Create a client for accessing wallet cards from the {@link QuickAccessWalletService}. If the 43 * service is unavailable, {@link #isWalletServiceAvailable()} will return false. 44 */ 45 @NonNull create(@onNull Context context)46 static QuickAccessWalletClient create(@NonNull Context context) { 47 return create(context, null /* bgExecutor */); 48 } 49 50 /** 51 * Create a client for accessing wallet cards from the {@link QuickAccessWalletService}. If the 52 * service is unavailable, {@link #isWalletServiceAvailable()} will return false. 53 * @param context Context. 54 * @param bgExecutor A background {@link Executor} for service registration. 55 * @hide 56 */ 57 @NonNull create(@onNull Context context, @Nullable Executor bgExecutor)58 static QuickAccessWalletClient create(@NonNull Context context, @Nullable Executor bgExecutor) { 59 return new QuickAccessWalletClientImpl(context, bgExecutor); 60 } 61 62 /** 63 * @return true if the {@link QuickAccessWalletService} is available. This means that the 64 * default NFC payment application has an exported service that can provide cards to the Quick 65 * Access Wallet. However, it does not mean that (1) the call will necessarily be successful, 66 * nor does it mean that cards may be displayed at this time. Addition checks are required: 67 * <ul> 68 * <li>If {@link #isWalletFeatureAvailable()} is false, cards should not be displayed 69 * <li>If the device is locked and {@link #isWalletFeatureAvailableWhenDeviceLocked} is 70 * false, cards should not be displayed while the device remains locked. (A message 71 * prompting the user to unlock to view cards may be appropriate).</li> 72 * </ul> 73 */ isWalletServiceAvailable()74 boolean isWalletServiceAvailable(); 75 76 /** 77 * Wallet cards should not be displayed if: 78 * <ul> 79 * <li>The wallet service is unavailable</li> 80 * <li>The device is not provisioned, ie user setup is incomplete</li> 81 * <li>If the wallet feature has been disabled by the user</li> 82 * <li>If the phone has been put into lockdown mode</li> 83 * </ul> 84 * <p> 85 * Quick Access Wallet implementers should call this method before calling 86 * {@link #getWalletCards} to ensure that cards may be displayed. 87 */ isWalletFeatureAvailable()88 boolean isWalletFeatureAvailable(); 89 90 /** 91 * Wallet cards may not be displayed on the lock screen if the user has opted to hide 92 * notifications or sensitive content on the lock screen. 93 * <ul> 94 * <li>The device is not provisioned, ie user setup is incomplete</li> 95 * <li>If the wallet feature has been disabled by the user</li> 96 * <li>If the phone has been put into lockdown mode</li> 97 * </ul> 98 * 99 * <p> 100 * Quick Access Wallet implementers should call this method before calling 101 * {@link #getWalletCards} if the device is currently locked. 102 * 103 * @return true if cards may be displayed on the lock screen. 104 */ isWalletFeatureAvailableWhenDeviceLocked()105 boolean isWalletFeatureAvailableWhenDeviceLocked(); 106 107 /** 108 * Get wallet cards from the {@link QuickAccessWalletService}. 109 */ getWalletCards( @onNull GetWalletCardsRequest request, @NonNull OnWalletCardsRetrievedCallback callback)110 void getWalletCards( 111 @NonNull GetWalletCardsRequest request, 112 @NonNull OnWalletCardsRetrievedCallback callback); 113 114 /** 115 * Get wallet cards from the {@link QuickAccessWalletService}. 116 */ getWalletCards( @onNull @allbackExecutor Executor executor, @NonNull GetWalletCardsRequest request, @NonNull OnWalletCardsRetrievedCallback callback)117 void getWalletCards( 118 @NonNull @CallbackExecutor Executor executor, 119 @NonNull GetWalletCardsRequest request, 120 @NonNull OnWalletCardsRetrievedCallback callback); 121 122 /** 123 * Callback for getWalletCards 124 */ 125 interface OnWalletCardsRetrievedCallback { onWalletCardsRetrieved(@onNull GetWalletCardsResponse response)126 void onWalletCardsRetrieved(@NonNull GetWalletCardsResponse response); 127 onWalletCardRetrievalError(@onNull GetWalletCardsError error)128 void onWalletCardRetrievalError(@NonNull GetWalletCardsError error); 129 } 130 131 /** 132 * Notify the {@link QuickAccessWalletService} service that a wallet card was selected. 133 */ selectWalletCard(@onNull SelectWalletCardRequest request)134 void selectWalletCard(@NonNull SelectWalletCardRequest request); 135 136 /** 137 * Notify the {@link QuickAccessWalletService} service that the Wallet was dismissed. 138 */ notifyWalletDismissed()139 void notifyWalletDismissed(); 140 141 /** 142 * Register an event listener. 143 */ addWalletServiceEventListener(@onNull WalletServiceEventListener listener)144 void addWalletServiceEventListener(@NonNull WalletServiceEventListener listener); 145 146 /** 147 * Register an event listener. 148 */ addWalletServiceEventListener( @onNull @allbackExecutor Executor executor, @NonNull WalletServiceEventListener listener)149 void addWalletServiceEventListener( 150 @NonNull @CallbackExecutor Executor executor, 151 @NonNull WalletServiceEventListener listener); 152 153 /** 154 * Unregister an event listener 155 */ removeWalletServiceEventListener(@onNull WalletServiceEventListener listener)156 void removeWalletServiceEventListener(@NonNull WalletServiceEventListener listener); 157 158 /** 159 * A listener for {@link WalletServiceEvent walletServiceEvents} 160 */ 161 interface WalletServiceEventListener { onWalletServiceEvent(@onNull WalletServiceEvent event)162 void onWalletServiceEvent(@NonNull WalletServiceEvent event); 163 } 164 165 /** 166 * Unregister all event listeners and disconnect from the service. 167 */ disconnect()168 void disconnect(); 169 170 /** 171 * The QuickAccessWalletService may provide a {@link PendingIntent} to start the activity that 172 * hosts the Wallet view. This is typically the home screen of the Wallet application. If this 173 * method returns null, the value returned by getWalletIntent() will be used instead. 174 */ getWalletPendingIntent(@onNull @allbackExecutor Executor executor, @NonNull WalletPendingIntentCallback walletPendingIntentCallback)175 void getWalletPendingIntent(@NonNull @CallbackExecutor Executor executor, 176 @NonNull WalletPendingIntentCallback walletPendingIntentCallback); 177 178 /** 179 * Callback for getWalletPendingIntent. 180 */ 181 interface WalletPendingIntentCallback { onWalletPendingIntentRetrieved(@ullable PendingIntent walletPendingIntent)182 void onWalletPendingIntentRetrieved(@Nullable PendingIntent walletPendingIntent); 183 } 184 185 /** 186 * Gets the {@link PendingIntent} provided by QuickAccessWalletService to be sent when the user 187 * launches Wallet via gesture. 188 */ 189 @FlaggedApi(Flags.FLAG_LAUNCH_WALLET_OPTION_ON_POWER_DOUBLE_TAP) getGestureTargetActivityPendingIntent( @onNull @allbackExecutor Executor executor, @NonNull GesturePendingIntentCallback gesturePendingIntentCallback)190 void getGestureTargetActivityPendingIntent( 191 @NonNull @CallbackExecutor Executor executor, 192 @NonNull GesturePendingIntentCallback gesturePendingIntentCallback); 193 194 /** Callback interface for getGesturePendingIntent. */ 195 @FlaggedApi(Flags.FLAG_LAUNCH_WALLET_OPTION_ON_POWER_DOUBLE_TAP) 196 interface GesturePendingIntentCallback { 197 /** Callback method for getGesturePendingIntent */ 198 @FlaggedApi(Flags.FLAG_LAUNCH_WALLET_OPTION_ON_POWER_DOUBLE_TAP) onGesturePendingIntentRetrieved(@ullable PendingIntent pendingIntent)199 void onGesturePendingIntentRetrieved(@Nullable PendingIntent pendingIntent); 200 } 201 202 /** 203 * The manifest entry for the QuickAccessWalletService may also publish information about the 204 * activity that hosts the Wallet view. This is typically the home screen of the Wallet 205 * application. 206 */ 207 @Nullable createWalletIntent()208 Intent createWalletIntent(); 209 210 /** 211 * The manifest entry for the {@link QuickAccessWalletService} may publish the activity that 212 * hosts the settings 213 */ 214 @Nullable createWalletSettingsIntent()215 Intent createWalletSettingsIntent(); 216 217 /** 218 * Returns the logo associated with the {@link QuickAccessWalletService}. This is specified by 219 * {@code android:logo} manifest entry. If the logo is not specified, the app icon will be 220 * returned instead ({@code android:icon}). 221 * 222 * @hide 223 */ 224 @Nullable getLogo()225 Drawable getLogo(); 226 227 /** 228 * Returns the tile icon associated with the {@link QuickAccessWalletService}. 229 * 230 * @hide 231 */ 232 @Nullable getTileIcon()233 Drawable getTileIcon(); 234 235 /** 236 * Returns the user that should receive the wallet intents 237 * 238 * @return UserHandle 239 * @hide 240 */ 241 @Nullable getUser()242 UserHandle getUser(); 243 244 /** 245 * Returns the service label specified by {@code android:label} in the service manifest entry. 246 * 247 * @hide 248 */ 249 @Nullable getServiceLabel()250 CharSequence getServiceLabel(); 251 252 /** 253 * Returns the text specified by the {@link android:shortcutShortLabel} in the service manifest 254 * entry. If the shortcutShortLabel isn't specified, the service label ({@code android:label}) 255 * will be returned instead. 256 * 257 * @hide 258 */ 259 @Nullable getShortcutShortLabel()260 CharSequence getShortcutShortLabel(); 261 262 /** 263 * Returns the text specified by the {@link android:shortcutLongLabel} in the service manifest 264 * entry. If the shortcutShortLabel isn't specified, the service label ({@code android:label}) 265 * will be returned instead. 266 * 267 * @hide 268 */ 269 @Nullable getShortcutLongLabel()270 CharSequence getShortcutLongLabel(); 271 } 272