快速存取電子錢包

「快速存取錢包」功能， Android 11 可讓使用者 直接透過電源鍵存取付款卡和相關票證。主要用途 包括選取合適的付款方式，然後才執行 透過 NFC 感應式刷卡機快速取得航班和其他票證 吸引即將到來的活動

在 Android 12 以上版本中，「快速存取錢包」 功能是以圖 1 和圖 2 所示的色調提供。

圖 1. 快速存取錢包功能 (裝置已鎖定)。

圖 2. 快速存取錢包功能 (裝置已解鎖)。

在 Android 11 中，這項功能可透過電源選單存取，如 圖 3.

圖 3. 快速存取錢包功能 選單。

需求條件

您的裝置必須具有 NFC 才能使用「快速存取錢包」功能。功能 繫結至預設 NFC 付款應用程式的 QuickAccessWalletService (也就是 裝置也必須支援 NFC 主機型卡片模擬 (HCE)。

功能總覽

「快速存取」錢包有兩個部分：「快速存取錢包」使用者介面和 卡片供應商。

在 Android 12 以上版本中，錢包 UI 會在「系統」中執行 它位於 frameworks/base/packages/SystemUI/src/com/android/systemui/wallet。於 Android 11 (錢包 UI，位於 platform/packages/apps/QuickAccessWallet, 必須安裝並加入許可清單。

「快速存取錢包」卡片供應商是預設的 NFC 付款應用程式。使用者可以 同時安裝多個 NFC 付款應用程式，但只有預設 NFC 付款應用程式可在電源選單中顯示卡片。您可以指定 付款應用程式一開始是設為「預設」，但使用者可以選取其他選項 應用程式。如果只安裝一個 NFC 付款應用程式，該應用程式就會成為 預設為自動儲存 (請參閱 CardEmulationManager)。

實作

為提供卡片給「快速存取錢包」使用者介面，透過 NFC 付款 應用程式必須實作 QuickAccessWalletService。 付款應用程式必須包含宣傳服務的資訊清單項目。

為確保只有系統 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 的參照，並呼叫 QuickAccessWalletService#sendEvent，事件類型為 TYPE_NFC_PAYMENT_STARTED。如此一來，「快速存取錢包」使用者介面就會成為 已關閉，方便使用者查看付款活動。

如需其他實作 QuickAccessWalletService 的說明文件，請參閱 QuickAccessWalletService 和 TestQuickAccessWalletService CTS 測試。

在 Android 11 中啟用錢包使用者介面

注意： 使用者不必啟用「快速存取」錢包使用者介面 搭載 Android 12 以上版本。

設定可透過電源選單使用的快速存取錢包 請在 Android 11 中加入 QuickAccessWallet 建構目標，並新增 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>

指定預設的 NFC 付款應用程式，方法如下： 設定檔 使用 def_nfc_payment_component。

預設的 NFC 付款應用程式必須公開 QuickAccessWalletService 為「快速存取錢包」提供卡片。如果預設的 NFC 付款應用程式 如果未匯出這項服務，錢包 UI 會隱藏。

QuickAccessWalletService 實作詳情

QuickAccessWalletService 有三個必須實作的抽象方法： onWalletCardsRequested、onWalletCardSelected和onWalletDismissed。 下方序列圖說明快速存取錢包時的呼叫序列 會在 NFC 付款前顯示。

圖 4. 「快速存取錢包」為以下情況時呼叫序列範例 。

並非所有「快速存取錢包」都會出現在 NFC 付款之後， 上方圖 4 說明瞭 QuickAccessWalletService。在此示例中，我們可以看到「快速存取錢包」資訊卡 供應商會實作以藍色標明的元素。算是該筆款項 卡片會儲存在裝置的資料庫中，而且可以透過 名為 PaymentCardManager 的介面。進一步假設 「PaymentActivity」會顯示 NFC 付款的結果。流程 方法如下：

1. 使用者做出手勢，開啟快速存取錢包。

2. 「快速存取錢包 UI」(系統 UI 的一部分) 會檢查套件 ，確認預設的 NFC 付款應用程式是否匯出。 QuickAccessWalletService。

   • 如果不匯出這項服務，「快速存取錢包」就不會匯出 高度。

3. 「快速存取錢包」使用者介面會繫結至 QuickAccessWalletService 和 呼叫 onWalletCardsRequested。這個方法會接收要求物件 內含資訊卡數量和大小的相關資料 以及回呼。可從背景執行緒呼叫回呼。

4. QuickAccessWalletService 會計算想要顯示的資訊卡。 然後在提供的回呼上呼叫 onSuccess 方法。是 建議服務在背景執行緒上執行這些動作。

5. 資訊卡顯示後，系統 UI 會立即通知 QuickAccessWalletService 已致電給所選第一張卡片 onWalletCardSelected。

   • 每當使用者選取時，系統就會呼叫 onWalletCardSelected 另一張卡片顯示
   • onWalletCardSelected即使目前 所選的卡片沒有變更。

6. 使用者關閉快速存取錢包時，系統 UI 會發出通知 呼叫 onWalletDismissed 即可QuickAccessWalletService。

在上述範例中，使用者將手機帶入 NFC 付款的範圍內 。處理 NFC 的重要元件 付款為 HostApduService，必須導入才能處理 APDU NFC 讀取器提供的功能 (如需詳細資訊，請參見 主機型卡片模擬)。 系統會假設付款應用程式啟動活動以顯示進度， 。不過，「快速存取」功能 錢包 UI 會顯示在應用程式視窗的頂端，也就是說， 付款活動會遭到「快速存取錢包」使用者介面遮蓋。解決這個問題 應用程式必須通知系統 UI，告知「快速存取錢包」使用者介面 已關閉。方法是取得繫結的參照 QuickAccessWalletService 並透過事件呼叫 sendWalletServiceEvent 輸入 TYPE_NFC_PAYMENT_STARTED。

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 的資訊清單項目必須包含 android.permission.BIND_QUICK_ACCESS_WALLET_SERVICE 權限導入 Android 11。這是擁有簽章層級的權限 也就是系統 UI 只有系統 UI 程序可以繫結至 QuickAccessWalletService。請注意，側載的應用程式 權限並取得裝置端 QuickAccessWalletService 資料的完整存取權 搭載 Android 10 以下版本如要避免這種情況， 建議使用服務 查看 onCreate 中的版本，並只在裝置上啟用服務 搭載 Android 11 以上版本。沒有其他應用程式權限 規定，提供主機卡片模擬付款所需的資訊，則不在此限 免費 Google Cloud 服務

如果預設的 NFC 付款應用程式未執行或匯出 QuickAccessWalletService，畫面上並未顯示「快速存取錢包」使用者介面。

Android 12 的設定

如要在螢幕鎖定畫面上啟用或停用「快速存取錢包」，使用者可以： 使用「設定」中的「顯示錢包」切換鈕 >顯示 > 螢幕鎖定畫面。如要停用在色調中的錢包，使用者必須手動編輯 快速設定通知欄

圖 5. 在「設定」的「螢幕鎖定」頁面中顯示錢包切換按鈕。

Android 11 的設定

使用者可以在「設定」應用程式中關閉「快速存取錢包」功能。 可以在以下位置找到設定頁面： 「設定」>系統 >手勢 >卡片與票證

圖 6. 在「設定」頁面中啟用或停用 快速存取 Google 錢包功能。

自訂

在系統 UI 中將「快速存取錢包」檢視畫面新增至其他位置

快速存取 Google 錢包使用者介面 是建構於 系統外掛程式。 雖然 Android 開放原始碼計畫實作會在 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);
  }
}

快速存取 Google 錢包使用者介面 實作 GlobalActionsPanelPlugin 和 PanelViewController。 GlobalActionsDialog 取得錢包外掛程式的執行個體 com.android.systemui.Dependency：

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

檢查外掛程式是否為空值，且 PanelViewController onPanelShown 傳回的非空值，對話方塊會附加 View 由 getPanelContent 套用至自己的 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 提供的檢視畫面， 包含建構目標並移除對 GlobalActionsPanelPlugin 的參照 來自 GlobalActionsImpl。

調整預設設定

Android 12

在 Android 12 以上版本中，「快速存取錢包」是 一律會顯示在快速設定欄中。快速存取的瀏覽權限 螢幕鎖定畫面上的 Google 錢包會受到下列安全設定管制： LOCKSCREEN_SHOW_WALLET。這項設定可控制「快速存取」錢包 圖示會顯示在螢幕鎖定畫面的右下方。這項設定已設為 預設為true，但使用者可以前往 [設定] > [關閉] 多媒體 >螢幕鎖定畫面 >顯示錢包。

Android 11

在 Android 11 中，「快速存取錢包」的瀏覽權限設有兩項安全設定： 《GLOBAL_ACTIONS_PANEL_ENABLED》和《GLOBAL_ACTIONS_PANEL_AVAILABLE》。 AVAILABLE 設定可控制是否要在以下位置啟用或停用這項功能： 。這項設定已設為 true， WalletPluginService。 如果版本未包含 QuickAccessWallet，則設定仍維持不變 false。ENABLED 設定在相同位置預設為 true。 但使用者可在「設定」中關閉如要變更預設行為 修改 WalletPluginService#enableFeatureInSettings。

驗證

如要驗證快速存取錢包的實作結果，請執行 CTS 和手動操作 測試。對外掛程式所做的變更也應練習 Robolectric 測試。

CTS 測試

執行位於 cts/tests/quickaccesswallet。

Android 12 手動測試

測試「快速存取錢包」的核心功能需要 NFC 付款 感應器 (無論是真實或假造)，以及導入 QuickAccessWalletService (錢包應用程式)。需要測試的核心功能 包括可用性、零狀態、卡片選取，以及螢幕鎖定行為

適用地區

• 如果預設的 NFC 付款應用程式不支援此功能， 無法透過快速設定或門鎖存取「錢包」 。
• 如果預設的 NFC 付款應用程式支援這項功能，就會啟用「快速存取」功能 您可以在快速設定欄中存取「錢包」。
• 如果預設的 NFC 付款應用程式支援此功能，且 LOCKSCREEN_SHOW_WALLET 的設定為「true」，快速存取錢包為 。
• 如果預設的 NFC 付款應用程式支援此功能，且 LOCKSCREEN_SHOW_WALLET 的設定為「false」，但快速存取錢包並未 。

零狀態

• 如果 QuickAccessWalletService 已啟用並匯出但未匯出 提供任何資訊卡，陰影中的圖塊便會顯示在 如圖 7 中的範例。按一下動態磚開啟預設的 NFC 付款應用程式。

  

  圖 7. 通知欄中的資訊方塊範例，顯示預設的 NFC 付款應用程式。

• 按一下圖 8 中顯示的空白狀態檢視畫面，即可開啟 預設 NFC 付款應用程式。只有在系統顯示 使用者錢包中有一張卡片，請將卡片從卡片資料中移除 頁面，然後回到錢包檢視畫面。

• 螢幕鎖定畫面顯示「錢包」圖示。

圖 8. 「快速存取錢包」使用者介面的空白狀態檢視畫面。

非零狀態

• 如果錢包應用程式提供一或多張卡片，通知欄中的資訊方塊。 如圖 9 所示

  

  圖 9.錢包應用程式有一或多張卡片時的範例資訊方塊。

• 按一下圖塊即可顯示資訊卡輪轉介面。

• 螢幕鎖定畫面上會顯示一個按鈕，可用來開啟「快速存取錢包」。

  

  圖 10. 顯示卡片的快速存取錢包 UI。

• 如果顯示的卡片代表 NFC 付款方式，請保留 手機連線到 NFC 付款感應器，導致消費者使用該付款方式 並關閉錢包檢視畫面

• 按一下所顯示的資訊卡，即可開啟該資訊卡的詳細活動。

• 如果 QuickAccessWalletService 提供多張卡片，使用者 或滑動切換資訊卡

• 溢位選單包含一個項目：開啟螢幕鎖定設定， 讓使用者變更「顯示錢包」選項。

鎖定狀態測試

• 如果手機處於鎖定狀態，快速設定上就會顯示錢包 顏色，帶有「新增資訊卡」(如果預設沒有卡片的話) 付款應用程式，或解鎖預設付款應用程式中的卡片。
• 如果手機處於鎖定狀態，螢幕鎖定畫面的錢包顯示設定會： 由 Secure.LOCKSCREEN_SHOW_WALLET 設定控制 您可在「設定」中控制這些功能。
• 如果手機處於鎖定狀態，LOCKSCREEN_SHOW_WALLET 為 false，且沒有卡片 ，且錢包未顯示在預設的 NFC 付款應用程式中。 鎖定螢幕。
• 如果手機處於鎖定狀態，LOCKSCREEN_SHOW_WALLET 為 true，且沒有卡片 ，且錢包未顯示在預設的 NFC 付款應用程式中。 鎖定螢幕。
• 如果手機處於鎖定狀態，LOCKSCREEN_SHOW_WALLET 會處於「true」狀態，且卡片會處於鎖定狀態 錢包在預設的 NFC 付款應用程式中，錢包就顯示在智慧門鎖上 。
• 當智慧門鎖顯示錢包時，將手機解鎖 導致資訊卡遭到重新查詢， 資訊卡的內容也各不相同

無障礙功能測試

• Talkback 使用者可以左右滑動，以瀏覽錢包檢視畫面 聆聽資訊卡的內容說明
• 左右滑動啟用 TalkBack 時，系統會逐一選取每張資訊卡。 Talkback 使用者可以選取及使用 NFC 付款方式進行 NFC 付款 終端機。

Android 11 手動測試

測試「快速存取錢包」的核心功能需要 NFC 付款 感應器 (無論是真實或假造)，以及導入 QuickAccessWalletService (錢包應用程式)。需要測試的核心功能 包括可用性、零狀態、卡片選取和螢幕鎖定行為。

適用地區

• 如果 GLOBAL_ACTIONS_PANEL_ENABLED 設定為 true 且預設值 NFC 付款應用程式支援這項功能，即可使用「快速存取錢包」。
• 如果 GLOBAL_ACTIONS_PANEL_ENABLED 設定為 false 且預設值 NFC 付款應用程式支援這項功能，但「不支援」快速存取錢包 方便存取
• 如果 GLOBAL_ACTIONS_PANEL_ENABLED 設定為 true 且預設值 NFC 付款應用程式「不」支援「快速存取錢包」這項功能。 「未」存取。
• 如果 GLOBAL_ACTIONS_PANEL_ENABLED 設定為 false 且預設值 NFC 付款應用程式「不」支援「快速存取錢包」這項功能。 「未」存取。

零狀態

• 如果 QuickAccessWalletService 已啟用並匯出但未匯出 提供任何卡片，「快速存取錢包」使用者介面會顯示空白狀態檢視畫面。

• 按一下空白狀態檢視畫面，開啟錢包應用程式。

  

  圖 11.快速存取中的空白狀態檢視畫面 錢包 UI。

非零狀態

• 如果錢包應用程式提供一或多張卡片，卡片就會顯示 「快速存取錢包」使用者介面中。

  

  圖 12.透過卡片快速存取錢包使用者介面

• 如果顯示的卡片代表 NFC 付款方式，請按住 手機連線到 NFC 付款感應器，導致消費者使用該付款方式 並關閉錢包檢視畫面

• 按一下顯示的卡片，即可關閉錢包檢視畫面並開啟 該資訊卡的詳細活動

• 如果 QuickAccessWalletService 提供多張卡片，使用者 或滑動切換資訊卡

• 溢位選單包含兩個項目：一個開啟錢包應用程式 以及開啟顯示資訊卡和「設定」中的畫面。

鎖定狀態測試

• 如果手機處於鎖定狀態，錢包的瀏覽權限是由 Settings.Secure.POWER_MENU_LOCK_SHOW_CONTENT 設定，可設為 您可在「設定」中控制這些功能。
• 如果手機處於鎖定狀態，且POWER_MENU_LOCK_SHOW_CONTENT為 false， 未顯示錢包。
• 如果手機處於鎖定狀態，且POWER_MENU_LOCK_SHOW_CONTENT為 true， 錢包出現了。
• 當智慧門鎖顯示錢包時，將手機解鎖 導致系統重新查詢資訊卡， 資訊卡的內容也各不相同

無障礙功能測試

• TalkBack 使用者可以左右滑動瀏覽錢包檢視畫面 聆聽資訊卡的內容說明
• 在啟用 TalkBack 的左右滑動會逐一選取每張資訊卡。 TalkBack 使用者可以選取及使用 NFC 付款方式進行 NFC 付款 終端機。