Интеграция без использования приложения "Панель управления Рутокен"

Общая информация

Эта статья описывает интеграцию устройств Рутокен в мобильные приложения для платформы Android без использования приложения "Панель управления Рутокен".

Поддерживаемые версии Android

Android 7.0 (API Level 24) и выше.

Настройка зависимостей в проекте

Для встраивания необходимо добавить в зависимости библиотеку rtpcscbridge: 

implementation 'ru.rutoken.rtpcscbridge:rtpcscbridge:1.0.0'

implementation("ru.rutoken.rtpcscbridge:rtpcscbridge:1.0.0")

Инициализация библиотеки

Точкой входа встраивания является класс ru.rutoken.rtpcscbridge.RtPcscBridge, который необходим для инициализации библиотеки rtpcscbridge.

Для каждого процесса приложения, в котором происходит взаимодействие с устройствами Рутокен, необходимо вызвать статический метод setAppContext и передать ему в качестве параметра Android application context.

Типичное место вызова метода – внутри onCreate() класса-наследника Application.

public class App extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        RtPcscBridge.setAppContext(this);
    }
}

Режимы работы библиотеки

С библиотекой можно работать в двух режимах:

Ручной API

Для работы с библиотекой в Ручном режиме используется интерфейс ru.rutoken.rttransport.RtTransport. Его инстанс можно получить с помощью метода RtPcscBridge.getTransport().

Рекомендуется  следующий порядок вызова API:

Автоматический API

Для работы с библиотекой в Автоматическом режиме используется интерфейс ru.rutoken.rttransport.RtTransportExtension. Его инстанс можно получить из метода RtPcscBridge.getTransportExtension().

Для включения Автоматического режима необходимо вызвать метод attachToLifecycle внутри класса-наследника Application.

Пример.
Инициализация библиотеки и включение автоматического режима: 

public class App extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        RtPcscBridge.setAppContext(this);
        RtPcscBridge.getTransportExtension().attachToLifecycle(this, true);
    }
}

В параметры метода attachToLifecycle дополнительно можно передать флаг useAutoNfcHandling для включения/выключения автоматической обработки устройств Рутокен с NFC.
По умолчанию значение флага – true.

Для отключения Автоматического режима применяется метод RtTransportExtension.detachFromLifecycle(app).

Если взаимодействие с устройством Рутокен осуществляется на протяжении всей работы приложения, то данный метод можно не применять.

Автоматический API и жизненный цикл приложения

Жизненный цикл автоматического API непосредственно связан с жизненными циклами всех Activity приложения.

Вызов метода RtTransportExtension.attachToLifecycle(app) инициирует следующие операции внутри библиотеки:

• добавление подписчика ru.rutoken.rttransport.RtTransportProcessLifecycleObserver на жизненный цикл процесса приложения.
• добавление ru.rutoken.rttransport.RtTransportNfcLifecycleCallbacks в качестве Activity Lifecycle callbacks для данного приложения (если параметр useAutoNfcHandling = true и NFC адаптер физически существует).

Зависимость RtTransport от жизненного цикла Activity

Зависимость поведения RtTransport от жизненного цикла Activity при автоматическом режиме встраивания и включенном автоуправлении NFC приведена ниже:

После перехода первой Activity в состояние Started (событие Lifecycle.Event.ON_START) вызывается инициализация RtTransport.

После перехода последней Activity в состояние Stopped (событие Lifecycle.Event.ON_STOP) вызывается финализация RtTransport. Вызов финализации осуществляется с задержкой, что исключает лишнюю переинициализацию при:

• смене конфигурации (переворот экрана);
• быстром переключении между приложениями;
• быстром переключении на Home screen и обратно.

При включенном автоуправлении NFC дополнительно автоматически вызываются методы:

Когда Activity находится в стадии Resumed, библиотека реагирует на события о состоянии NFC адаптера через внутренний BroadcastReceiver:

• при переходе адаптера в состояние NfcAdapter.STATE_ON, вызывается enableNfcForegroundDispatch;
• при переходе адаптера в состояние NfcAdapter.STATE_OFF, вызывается disableNfcForegroundDispatch.

Отслеживание подключения (отключения) устройств Рутокен

Встраивание позволяет отслеживать подключение и отключение устройств Рутокен с помощью интерфейса ru.rutoken.rttransport.RtTransport.PcscReaderObserver.

Отслеживание устройств доступно в любом режиме использования встраивания.

Для старта отслеживания (в любой момент работы со встраиванием) используются интерфейс ru.rutoken.rttransport.RtTransport и метод addPcscReaderObserver.

Допускается добавление нескольких подписчиков на события. При добавлении подписчика ему поступят события обо всех подключенных на данный момент к устройству Рутокенах. Для каждого Рутокена будет вызываться метод RtTransport.PcscReaderObserver.onReaderAdded(reader).

Для отключения отслеживания используется метод RtTransport.removePcscReaderObserver.

Требования для встраивания в зависимости от физического интерфейса устройства Рутокен

USB

Для работы с USB-устройствами Рутокен в Ручном режиме необходимо вызвать методы RtTransport.initialize(context) и RtTransport.finalize(context).

Для работы в Автоматическом режиме  необходимо  использовать метод attachToLifecycle(application).

При каждом подключении Рутокена система запрашивает у пользователя разрешение на использование этого USB-устройства.

Дополнительных runtime permission  приложению получать не требуется.

Bluetooth

Для работы с Bluetooth-устройствами Рутокен в Ручном режиме необходимо вызвать методы RtTransport.initialize(context) и RtTransport.finalize(context).

Для работы в Автоматическом режиме  необходимо  использовать метод attachToLifecycle(application).

NFC

Для работы с NFC-устройствами Рутокен в Ручном режиме необходимо вызвать все методы раздела "Ручной API".

Для работы в Автоматическом режиме необходимо передать флаг useAutoNfcHandling=true в метод RtTransportExtension.attachToLifecycle(application, boolean)  или использовать метод attachToLifecycle(application)(по умолчанию включает авто-обработку NFC).

Дополнительных runtime permission приложению получать не требуется.

Работа встраивания в многопроцессных приложениях

Корректность работы встраивания не гарантируется при одновременном использовании устройств Рутокен несколькими процессами приложения.

Логирование

Уровень логирования в библиотеках по умолчанию – ERROR.

Для отладки можно расширить логирование до уровня DEBUG, который содержит информацию об:

• автоматической инициализации встраивания;
• автоматической финализации встраивания;
• обнаружении токенов по различным физическим интерфейсам.

Для расширения логирования необходимо вызвать RtPcscBridge.enableDebugLogs() перед началом работы со встраиванием, а именно – до вызова RtPcscBridge.setAppContext.

Конфигурация R8/ProGuard

При включении обфускации приложения для корректной работы библиотеки необходимо прописать следующие правила в proguard-rules.pro:

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

-dontwarn ru.rutoken.spi.SpiDevice
-dontwarn ru.rutoken.spi.SpiManager
-keep class ru.rutoken.rttransport.** { *; }
-keep class ru.rutoken.rtcore.** { *; }
-keep class ru.rutoken.rtpcscbridge.** { *; }
-keep class * extends com.google.protobuf.GeneratedMessageLite { *; }