Эта страница переведена с помощью Cloud Translation API.

Кошелек быстрого доступа

Функция кошелька быстрого доступа, доступная в Android 11, позволяет пользователю получать доступ к платежным картам и соответствующим пропускам непосредственно из меню питания. Основные варианты использования включают выбор подходящего способа оплаты перед выполнением транзакции в терминале NFC, а также быстрый доступ к рейсам и другим пропускам на предстоящие мероприятия.

В Android 12 или более поздней версии функция «Кошелек быстрого доступа» доступна в тени, как показано на рисунках 1 и 2.

Функция быстрого доступа к кошельку в тени — **Рисунок 1.** Функция кошелька быстрого доступа (устройство заблокировано).

В Android 11 эта функция доступна из меню питания, как показано на рисунке 3.

**Рисунок 3.** Функция быстрого доступа к кошельку в меню питания.

Требования

Для использования функции кошелька быстрого доступа ваше устройство должно иметь NFC. Эта функция привязывается к QuickAccessWalletService приложения для оплаты NFC по умолчанию, а это означает, что устройство также должно поддерживать эмуляцию карт на основе хоста NFC (HCE) .

Обзор функций

Кошелек быстрого доступа состоит из двух частей: пользовательский интерфейс кошелька быстрого доступа и поставщик карт кошелька быстрого доступа.

В Android 12 или более поздней версии пользовательский интерфейс Wallet работает в системном интерфейсе и находится в frameworks/base/packages/SystemUI/src/com/android/systemui/wallet . В Android 11 необходимо установить и внести в белый список пользовательский интерфейс Wallet, который находится в platform/packages/apps/QuickAccessWallet .

Поставщик карты Quick Access Wallet является приложением для оплаты NFC по умолчанию. Пользователи могут одновременно установить несколько приложений для оплаты NFC, но только приложение для оплаты NFC по умолчанию может отображать карты в меню питания. Вы можете указать, какое приложение для оплаты NFC изначально установлено по умолчанию , но пользователи могут выбрать другое приложение в настройках. Если установлено только одно платежное приложение NFC, оно автоматически становится приложением по умолчанию (см. CardEmulationManager ).

Выполнение

Чтобы предоставить карты пользовательскому интерфейсу кошелька быстрого доступа, платежные приложения NFC должны реализовать QuickAccessWalletService . Платежные приложения должны включать запись в манифесте, рекламирующую эту услугу.

Чтобы обеспечить привязку к QuickAccessWalletService только системного пользовательского интерфейса, приложению платежей NFC должно потребоваться разрешение android.permission.BIND_QUICK_ACCESS_WALLET_SERVICE . Требование этого разрешения гарантирует, что только системный пользовательский интерфейс может привязываться к 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 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 по умолчанию не экспортирует эту услугу, пользовательский интерфейс кошелька скрыт.

Подробности реализации QuickAccessWalletService

QuickAccessWalletService имеет три абстрактных метода, которые необходимо реализовать: onWalletCardsRequested , onWalletCardSelected и onWalletDismissed . На диаграмме последовательности ниже показана последовательность вызовов при просмотре кошелька быстрого доступа непосредственно перед платежом NFC.

Схема последовательности операций кошелька быстрого доступа

**Рисунок 4.** Пример последовательности вызовов при просмотре кошелька быстрого доступа.

Не все виды кошелька быстрого доступа сопровождаются платежом NFC, но на рисунке 4 выше показаны все возможности QuickAccessWalletService . В этом примере поставщик карт «Кошелек быстрого доступа» реализует элементы, выделенные синим цветом. Предполагается, что платежные карты хранятся на устройстве в базе данных, и доступ к ним осуществляется через интерфейс PaymentCardManager . Далее предполагается, что действие PaymentActivity отображает результат платежа NFC. Поток протекает следующим образом:

Пользователь выполняет жест, чтобы открыть кошелек быстрого доступа.
Пользовательский интерфейс кошелька быстрого доступа (часть системного пользовательского интерфейса) проверяет диспетчер пакетов, чтобы узнать, экспортирует ли приложение платежей NFC по умолчанию QuickAccessWalletService .
- Если услуга не экспортирована, кошелек быстрого доступа не отображается.
Пользовательский интерфейс кошелька быстрого доступа привязывается к QuickAccessWalletService и вызывает onWalletCardsRequested . Этот метод принимает объект запроса, содержащий данные о количестве и размере карт, которые могут быть предоставлены, и обратный вызов. Обратный вызов можно вызвать из фонового потока.
QuickAccessWalletService вычисляет карты, которые хочет показать, а затем вызывает метод onSuccess для предоставленного обратного вызова. Рекомендуется, чтобы служба выполняла эти действия в фоновом потоке.
Как только карты отображаются, системный пользовательский интерфейс уведомляет QuickAccessWalletService о том, что первая карта была выбрана, путем вызова onWalletCardSelected .
- onWalletCardSelected вызывается каждый раз, когда пользователь выбирает новую карту.
- onWalletCardSelected может быть вызван, даже если текущая выбранная карта не изменилась.
Когда пользователь закрывает кошелек быстрого доступа, системный пользовательский интерфейс уведомляет QuickAccessWalletService , вызывая onWalletDismissed .

В приведенном выше примере пользователь подносит телефон в зону действия платежного терминала NFC, пока отображается кошелек. Ключевым компонентом обработки платежей NFC является HostApduService , который необходимо реализовать для обработки APDU, предоставляемых устройством чтения NFC (дополнительную информацию см. в разделе Эмуляция карты на основе хоста ). Предполагается, что платежное приложение запускает активность для отображения хода и результата взаимодействия с NFC-терминалом. Однако пользовательский интерфейс кошелька быстрого доступа отображается в верхней части окна приложения, а это означает, что платежная активность скрыта пользовательским интерфейсом кошелька быстрого доступа. Чтобы исправить это, приложение должно уведомить системный пользовательский интерфейс о том, что пользовательский интерфейс кошелька быстрого доступа следует закрыть. Это можно сделать, получив ссылку на привязанный 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 см. в справочнике по API QuickAccessWalletService .

Разрешения

Запись манифеста для QuickAccessWalletService должна требовать разрешения android.permission.BIND_QUICK_ACCESS_WALLET_SERVICE , представленного в Android 11. Это разрешение уровня подписи, хранящееся в системном пользовательском интерфейсе, что означает, что только процесс системного пользовательского интерфейса может привязываться к реализациям QuickAccessWalletService . Имейте в виду, что неопубликованные приложения могут запросить это разрешение и получить полный доступ к данным QuickAccessWalletService на устройствах под управлением Android 10 или более ранней версии. Чтобы этого не произошло, рекомендуется проверить версию сборки в onCreate и включать службу только на устройствах под управлением Android 11 и выше. Никакие другие разрешения приложения не требуются, кроме тех, которые необходимы для предоставления платежных услуг по эмуляции карты хоста.

Если приложение оплаты NFC по умолчанию не реализует и не экспортирует QuickAccessWalletService , пользовательский интерфейс кошелька быстрого доступа не отображается.

Настройки в Android 12

Чтобы включить или отключить кошелек быстрого доступа на экране блокировки, пользователи могут использовать переключатель «Показать кошелек» в меню «Настройки» > «Дисплей» > «Экран блокировки» . Чтобы отключить кошелек в тени, пользователи должны вручную отредактировать его в панели быстрых настроек.

Переключите, чтобы включить или отключить кошелек на экране блокировки

Рисунок 5. Показывать переключатель кошелька на странице экрана блокировки в настройках.

Настройки в Android 11

Пользователи могут отключить функцию «Быстрый доступ к кошельку» в приложении «Настройки». Страница настроек находится в разделе « Настройки» > « Система» > «Жесты» > «Карты и пропуска» .

**Рисунок 6.** Страница настроек для включения или отключения функции кошелька быстрого доступа.

Кастомизация

Добавление представления «Кошелек быстрого доступа» в другое место в системном пользовательском интерфейсе

Пользовательский интерфейс кошелька быстрого доступа создан в виде системного плагина . Хотя реализация 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);
  }
}

Пользовательский интерфейс кошелька быстрого доступа реализует GlobalActionsPanelPlugin и PanelViewController . GlobalActionsDialog получает экземпляр плагина кошелька, используя com.android.systemui.Dependency :

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

После проверки того, что плагин не имеет значения NULL и что PanelViewController , возвращаемый onPanelShown не имеет значения NULL, диалоговое окно присоединяет 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 из сборки системы. Чтобы удалить кошелек быстрого доступа из меню питания, но добавить его в другое представление пользовательского интерфейса системы, включите цель сборки и удалите ссылки на GlobalActionsPanelPlugin из GlobalActionsImpl .

Установка конфигураций по умолчанию

Андроид 12

В Android 12 или более поздней версии кошелек быстрого доступа всегда отображается в области быстрых настроек. Видимость кошелька быстрого доступа на экране блокировки ограничивается следующей настройкой безопасности: LOCKSCREEN_SHOW_WALLET . Этот параметр определяет, отображается ли значок кошелька быстрого доступа в правом нижнем углу экрана блокировки. По умолчанию для этого параметра установлено значение true , но пользователь может его отключить в меню «Настройки » > «Дисплей » > «Экран блокировки» > «Показать кошелек» .

Андроид 11

В Android 11 видимость кошелька быстрого доступа ограничена двумя настройками безопасности: GLOBAL_ACTIONS_PANEL_ENABLED и GLOBAL_ACTIONS_PANEL_AVAILABLE . Параметр AVAILABLE определяет, можно ли включать и выключать эту функцию в настройках. WalletPluginService устанавливает для этого параметра значение true . Если QuickAccessWallet не включен в сборку, значение параметра остается false . По умолчанию для параметра ENABLED установлено значение true , но пользователь может его отключить в настройках. Чтобы изменить поведение по умолчанию, измените WalletPluginService#enableFeatureInSettings .

Проверка

Чтобы проверить реализацию кошелька быстрого доступа, запустите CTS и ручные тесты. Изменения в плагине также должны выполнять включенные роботоэлектрические тесты .

CTS-тесты

Запустите тесты CTS, расположенные по адресу cts/tests/quickaccesswallet .

Ручные тесты для Android 12

Для тестирования основных функций кошелька быстрого доступа требуется платежный терминал NFC (настоящий или поддельный) и платежное приложение 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. Пользовательский интерфейс кошелька быстрого доступа с отображенной картой.
Если отображаемая карта представляет собой способ оплаты 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 (настоящий или поддельный) и платежное приложение NFC, реализующее QuickAccessWalletService (приложение-кошелек). Основные функции, которые необходимо протестировать, включают доступность, нулевое состояние, выбор карты и поведение экрана блокировки.