Expand | ||
---|---|---|
| ||
|
Общая информация
Эта статья описывает интеграцию устройств Рутокен в мобильные приложения для платформы Android без использования приложения "Панель управления Рутокен".
Поддерживаемые версии Android
Android 7.0 (API Level 24) и выше.
Настройка зависимостей в проекте
Для встраивания необходимо добавить в зависимости библиотеку rtpcscbridge:
...
Tip |
---|
Библиотека доступна в репозитории Maven Central. |
Инициализация библиотеки
Точкой входа встраивания является класс ru.rutoken.rtpcscbridge.RtPcscBridge, который необходим для инициализации библиотеки rtpcscbridge.
...
Code Block |
---|
public class App extends Application { @Override public void onCreate() { super.onCreate(); RtPcscBridge.setAppContext(this); } } |
Режимы работы библиотеки
С библиотекой можно работать в двух режимах:
UI Tabs | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
|
Ручной API
Для работы с библиотекой в Ручном режиме используется интерфейс ru.rutoken.rttransport.RtTransport. Его инстанс можно получить с помощью метода RtPcscBridge.getTransport().
...
Порядок | Метод | Описание | Место вызова |
---|---|---|---|
1 | RtTransport.initialize(context) | Инициализирует встраивание. Библиотека начинает отслеживать подключение и отключение устройств Рутокен (кроме подключений по NFC) и позволяет настроить дальнейшую работу с NFC | Рекомендуется:
|
2 | RtTransport.enableNfcForegroundDispatch(activity) | Включает NFC foreground dispatching для данной Activity | ТОЛЬКО из Main потока в методе Activity.onResume. |
3 | RtTransport.handleNfcIntent(intent) | Обрабатывает NFC интент, полученный при прикладывании устройств Рутокен. Интенты от устройств других производителей не обрабатываются. Применяется для дальнейшей установки соединения с Рутокен | При получении каждого NFC интента. Например. |
4 | RtTransport.disableNfcForegroundDispatch(activity) | Выключает NFC foreground dispatching для данной Activity | ТОЛЬКО из Main потока в методе Activity.onPause |
5 | RtTransport.finalize(context) | Завершает работу встраивания | Рекомендуется:
|
Автоматический API
Для работы с библиотекой в Автоматическом режиме используется интерфейс ru.rutoken.rttransport.RtTransportExtension. Его инстанс можно получить из метода RtPcscBridge.getTransportExtension().
...
Если взаимодействие с устройством Рутокен осуществляется на протяжении всей работы приложения, то данный метод можно не применять.
Автоматический API и жизненный цикл приложения
Жизненный цикл автоматического API непосредственно связан с жизненными циклами всех Activity приложения.
...
- добавление подписчика ru.rutoken.rttransport.RtTransportProcessLifecycleObserver на жизненный цикл процесса приложения.
- добавление ru.rutoken.rttransport.RtTransportNfcLifecycleCallbacks в качестве Activity Lifecycle callbacks для данного приложения (если параметр useAutoNfcHandling = true и NFC адаптер физически существует).
Зависимость RtTransport от жизненного цикла Activity
Зависимость поведения RtTransport от жизненного цикла Activity при автоматическом режиме встраивания и включенном автоуправлении NFC приведена ниже:
...
- при переходе адаптера в состояние NfcAdapter.STATE_ON, вызывается enableNfcForegroundDispatch;
- при переходе адаптера в состояние NfcAdapter.STATE_OFF, вызывается disableNfcForegroundDispatch.
Отслеживание подключения (отключения) устройств Рутокен
Встраивание позволяет отслеживать подключение и отключение устройств Рутокен с помощью интерфейса ru.rutoken.rttransport.RtTransport.PcscReaderObserver.
...
Warning |
---|
Если подписка производится внутри Activity или другого компонента, который может быть создан несколько раз за время жизни приложения, то необходимо своевременно отписываться во избежание утечки памяти. Пример. |
Требования для встраивания в зависимости от физического интерфейса устройства Рутокен
USB
Для работы с USB-устройствами Рутокен в Ручном режиме необходимо вызвать методы RtTransport.initialize(context) и RtTransport.finalize(context).
Для работы в Автоматическом режиме необходимо использовать метод attachToLifecycle(application).
При каждом подключении Рутокена система запрашивает у пользователя разрешение на использование этого USB-устройства.
...
Дополнительных runtime permission приложению получать не требуется.
Bluetooth
Для работы с Bluetooth-устройствами Рутокен в Ручном режиме необходимо вызвать методы RtTransport.initialize(context) и RtTransport.finalize(context).
Для работы в Автоматическом режиме необходимо использовать метод attachToLifecycle(application).
Note |
---|
На Android версии 12 и выше требуется самостоятельно запросить permission BLUETOOTH_CONNECT для всех режимов встраивания. |
NFC
Для работы с NFC-устройствами Рутокен в Ручном режиме необходимо вызвать все методы раздела "Ручной API".
Для работы в Автоматическом режиме необходимо передать флаг useAutoNfcHandling=true в метод RtTransportExtension.attachToLifecycle(application, boolean) или использовать метод attachToLifecycle(application)(по умолчанию включает авто-обработку NFC).
Дополнительных runtime permission приложению получать не требуется.
Работа встраивания в многопроцессных приложениях
Корректность работы встраивания не гарантируется при одновременном использовании устройств Рутокен несколькими процессами приложения.
Логирование
Уровень логирования в библиотеках по умолчанию – ERROR.
...
Для расширения логирования необходимо вызвать RtPcscBridge.enableDebugLogs() перед началом работы со встраиванием, а именно – до вызова RtPcscBridge.setAppContext.
Конфигурация R8/ProGuard
При включении обфускации приложения для корректной работы библиотеки необходимо прописать следующие правила в proguard-rules.pro:
Code Block | ||
---|---|---|
| ||
-dontwarn ru.rutoken.spi.SpiDevice -dontwarn ru.rutoken.spi.SpiManager -keep class ru.rutoken.rtcore.network.methodhandler.** { *; } -keep class ru.rutoken.rtpcscbridge.** { *; } -keep class * extends com.google.protobuf.GeneratedMessageLite { *; } |
При использовании расширенного логирования (уровень DEBUG), для сохранения читаемости логов, необходимо прописать следующие правила в proguard-rules.pro:
...