本頁面由 Cloud Translation API 翻譯而成。

快速訪問錢包，快速訪問錢包，快速訪問錢包，快速訪問錢包

Android 11 提供的快速訪問錢包功能允許用戶直接從電源菜單訪問支付卡和相關通行證。主要用例包括在 NFC 終端執行交易之前選擇合適的支付方式，以及快速訪問航班和其他通行證以迎接即將到來的活動。

在 Android 12 或更高版本中，快速訪問錢包功能可從陰影中使用，如圖 1 和圖 2 所示。

在 Android 11 中，該功能可從電源菜單中使用，如圖 3 所示。

要求

您的設備必須具有 NFC 才能使用快速訪問錢包功能。該功能綁定到默認 NFC 支付應用程序的QuickAccessWalletService ，這意味著設備還必須支持 NFC基於主機的卡模擬 (HCE) 。

功能概述

快速訪問錢包有兩個部分：快速訪問錢包 UI 和快速訪問錢包卡提供商。

在 Android 12 或更高版本中，Wallet UI 在 System UI 中運行，位於frameworks/base/packages/SystemUI/src/com/android/systemui/wallet中。在 Android 11 中，必須安裝位於platform/packages/apps/QuickAccessWallet中的 Wallet UI 並將其列入白名單。

快速訪問錢包卡提供商是默認的 NFC 支付應用程序。用戶可以同時安裝多個 NFC 支付應用，但只有默認的 NFC 支付應用才能在電源菜單上顯示卡片。您可以指定最初將哪個 NFC 支付應用程序設置為默認應用程序，但用戶可以在“設置”中選擇其他應用程序。如果只安裝了一個 NFC 支付應用程序，它會自動成為默認應用程序（請參閱CardEmulationManager ）。

執行

要向 Quick Access Wallet UI 提供卡片，NFC 支付應用程序必須實現QuickAccessWalletService 。支付應用程序必須包含廣告服務的清單條目。

為確保只有 System UI 可以綁定QuickAccessWalletService ，NFC 支付應用必須需要android.permission.BIND_QUICK_ACCESS_WALLET_SERVICE權限。要求此權限可確保只有系統 UI 可以綁定到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>

有關錢包的其他信息包含在鏈接的 XML 文件中：

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

接下來，支付應用程序必須實現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
    }
}

如果HostApduService開始處理 NFC 交易並因此啟動一個活動來顯示付款的進度和結果，它還應該嘗試獲取對綁定的QuickAccessWalletService的引用並使用事件類型 TYPE_NFC_PAYMENT_STARTED 調用QuickAccessWalletService#sendEvent TYPE_NFC_PAYMENT_STARTED .這會導致快速訪問錢包 UI 被關閉，從而使用戶可以暢通無阻地查看支付活動。

有關實現QuickAccessWalletService的其他文檔，請參閱QuickAccessWalletService和TestQuickAccessWalletService CTS 測試。

在 Android 11 中啟用快速訪問錢包 UI

要將 Quick Access Wallet 配置為可從 Android 11 的電源菜單中使用，請在構建中包含QuickAccessWallet目標，並通過將以下代碼示例中的粗體行添加到overlay/frameworks/base/packages/SystemUI/res/values/config.xml來啟用globalactions.wallet插件overlay/frameworks/base/packages/SystemUI/res/values/config.xml文件。

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

使用def_nfc_payment_component在設置配置文件中指定默認的 NFC 支付應用程序。

默認的 NFC 支付應用程序必須公開QuickAccessWalletService以向快速訪問錢包提供卡片。如果默認的 NFC 支付應用沒有導出此服務，則錢包 UI 是隱藏的。

QuickAccessWalletService 實現細節

QuickAccessWalletService具有三個必須實現的抽象方法： onWalletCardsRequested 、 onWalletCardSelected和onWalletDismissed 。下面的序列圖說明了在 NFC 支付之前查看快速訪問錢包時的調用序列。

快速訪問錢包時序圖

查看快速訪問錢包時的示例調用順序 — **圖 4.**查看 Quick Access Wallet 時的示例調用序列。

並非快速訪問錢包的所有視圖都跟隨 NFC 支付，但上面的圖 4 說明了QuickAccessWalletService的所有功能。在此示例中，快速訪問錢包卡提供商實現了藍色輪廓的元素。假設支付卡存儲在設備上的數據庫中，並通過名為PaymentCardManager的接口進行訪問。進一步假設名為PaymentActivity的活動顯示 NFC 支付的結果。流程如下：

用戶執行手勢以調出快速訪問錢包。
Quick Access Wallet UI（系統 UI 的一部分）檢查包管理器以查看默認 NFC 支付應用程序是否導出QuickAccessWalletService 。
- 如果服務未導出，則不會顯示快速訪問錢包。
Quick Access Wallet UI 綁定到QuickAccessWalletService並調用onWalletCardsRequested 。此方法接受一個請求對象，其中包含有關可提供的卡片數量和大小的數據以及一個回調。可以從後台線程調用回調。
QuickAccessWalletService計算它想要顯示的卡片，然後在提供的回調上調用onSuccess方法。建議服務在後台線程上執行這些操作。
卡片一顯示，系統 UI 就會通過調用onWalletCardSelected通知QuickAccessWalletService第一張卡片已被選中。
- 每次用戶選擇一張新卡時都會調用onWalletCardSelected 。
- 即使當前選擇的卡沒有更改，也可能會調用onWalletCardSelected 。
當用戶關閉快速訪問錢包時，系統 UI 通過調用onWalletDismissed QuickAccessWalletService

在上面的示例中，用戶在顯示錢包時將手機帶入 NFC 支付終端的範圍內。處理 NFC 支付的一個關鍵組件是HostApduService ，必須實現它來處理 NFC 讀取器提供的 APDU（有關更多信息，請參閱基於主機的卡模擬）。假設支付應用啟動了一個activity來顯示與NFC終端交互的進度和結果。但是，快速訪問錢包 UI 顯示在應用程序窗口的頂部，這意味著支付活動被快速訪問錢包 UI 遮擋。為了糾正這個問題，應用程序必須通知系統 UI 應該關閉快速訪問錢包 UI。它可以通過獲取對綁定QuickAccessWalletService的引用並使用事件類型TYPE_NFC_PAYMENT_STARTED調用sendWalletServiceEvent來實現。

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();
    });
  }
}

有關QuickAccessWalletService的更多詳細信息，請參閱QuickAccessWalletService API 參考。

權限

QuickAccessWalletService的 manifest 條目必須需要 Android 11 中引入的android.permission.BIND_QUICK_ACCESS_WALLET_SERVICE權限。這是系統 UI 擁有的簽名級權限，這意味著只有 System UI 進程才能綁定到QuickAccessWalletService的實現。請注意，側面加載的應用程序可以申請此權限，並在運行 Android 10 或更低版本的設備上獲得對QuickAccessWalletService數據的完全訪問權限。為防止出現這種情況，建議該服務檢查onCreate中的構建版本，並僅在運行 Android 11 及更高版本的設備上啟用該服務。除了提供主機卡模擬支付服務所需的權限外，不需要其他應用權限。

如果默認 NFC 支付應用未實現或導出QuickAccessWalletService ，則不會顯示快速訪問錢包 UI。

Android 12 中的設置

要從鎖定屏幕啟用或禁用快速訪問錢包，用戶可以使用設置>顯示>鎖定屏幕中的顯示錢包切換。要在陰影中禁用錢包，用戶必須在快速設置陰影中手動編輯它。

從鎖定屏幕切換以啟用或禁用錢包

圖 5.在設置的鎖定屏幕頁面中顯示錢包切換。

Android 11 中的設置

用戶可以從“設置”應用關閉快速訪問錢包功能。設置頁面位於Settings > System > Gestures > Cards & pass 。

設置頁面以啟用或禁用快速訪問錢包功能 — **圖 6.**啟用或禁用快速訪問錢包功能的設置頁面。

定制

將快速訪問錢包視圖添加到系統 UI 中的另一個位置

Quick Access Wallet UI是作為系統插件構建的。儘管 AOSP 實現在GlobalActionsDialog中使用了它（在長按時顯示），但只要您保持插件接口指定的合同，您就可以將該功能移動到不同的手勢後面。

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);
  }
}

快速訪問錢包 UI實現了GlobalActionsPanelPlugin和PanelViewController 。 GlobalActionsDialog使用com.android.systemui.Dependency獲取錢包插件的實例：

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

在檢查插件非空且onPanelShown返回的PanelViewController非空後，對話框將getPanelContent提供的View附加到它自己的View ，並為系統事件提供適當的回調。

// 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();

要從電源菜單中刪除快速訪問錢包，請從系統構建中省略QuickAccessWallet目標。要從電源菜單中刪除快速訪問錢包但將其添加到不同的系統 UI 提供的視圖中，請包含構建目標並從GlobalActionsImpl中刪除對GlobalActionsPanelPlugin的引用。

設置默認配置

安卓 12

在 Android 12 或更高版本中，快速訪問錢包始終在快速設置陰影中可見。鎖定屏幕中快速訪問錢包的可見性由以下安全設置控制： LOCKSCREEN_SHOW_WALLET 。此設置控制快速訪問錢包圖標是否顯示在鎖定屏幕的右下角。此設置默認設置為true ，但用戶可以在Settings > Display > Lock screen > Show wallet中關閉。

安卓 11

在 Android 11 中，快速訪問電子錢包的可見性由兩個安全設置控制： GLOBAL_ACTIONS_PANEL_ENABLED和GLOBAL_ACTIONS_PANEL_AVAILABLE 。 AVAILABLE設置控制是否可以在“設置”中打開和關閉該功能。此設置由WalletPluginService設置為true 。如果QuickAccessWallet未包含在構建中，則設置保持為false 。 ENABLED設置在同一位置默認設置為true ，但用戶可以在“設置”中關閉。要更改默認行為，請修改WalletPluginService#enableFeatureInSettings 。

驗證

要驗證您對快速訪問錢包的實施，請運行 CTS 和手動測試。對插件的更改還應執行包含的robolectric 測試。

CTS 測試

運行位於cts/tests/quickaccesswallet的 CTS 測試。

Android 12 的手動測試

測試快速訪問錢包的核心功能需要一個NFC支付終端（真假）和一個實現QuickAccessWalletService （錢包應用）的NFC支付應用。必須測試的核心功能包括：可用性、零狀態、卡選擇和鎖屏行為。

可用性

如果默認的 NFC 支付應用程序不支持該功能，則在快速設置和鎖定屏幕中都無法訪問快速訪問錢包。
如果默認 NFC 支付應用程序支持該功能，則可以在快速設置陰影中訪問快速訪問錢包。
如果默認 NFC 支付應用程序支持該功能並且LOCKSCREEN_SHOW_WALLET設置為true ，則可以在鎖定屏幕上訪問快速訪問錢包。
如果默認 NFC 支付應用支持該功能並且LOCKSCREEN_SHOW_WALLET設置為false ，則無法在鎖定屏幕上訪問快速訪問錢包。

零狀態

如果QuickAccessWalletService已啟用並導出但未提供任何卡片，則 Shade 中的磁貼將如圖 7 中的示例所示。單擊該磁貼將打開默認的 NFC 支付應用程序。
圖 7.陰影中顯示默認 NFC 支付應用程序的示例圖塊。
單擊圖 8 所示的空白狀態視圖會打開默認的 NFC 支付應用程序。此空狀態視圖僅在用戶在錢包中剩下一張卡時顯示，從卡詳細信息頁面中刪除該卡，然後返回到錢包視圖。
鎖定屏幕顯示錢包圖標。