View Source

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

Эта статья описывает интеграцию устройств Рутокен в мобильные приложения для платформы 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")

Библиотека доступна в репозитории Maven Central.

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

Точкой входа встраивания является класс 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);
    }
}

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

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

В данном режиме осуществляется явный вызов методов инициализации и финализации встраивания, а также управление считыванием устройств Рутокен с NFC.

Это обеспечивает полный контроль над поведением библиотеки со стороны приложения, например, при необходимости активации встраивания только для некоторых Activity приложения.

В данном режиме методы ручного API вызываются автоматически на определенных этапах жизненного цикла приложения.

Библиотека позволяет опционально включить автоматическую обработку NFC-устройств Рутокен для всех Activity, реализующих OnNewIntentProvider.

Остальные устройства Рутокен обрабатываются во всех Activity приложения.

Ручной API

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

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

Порядок вызова	Метод	Описание	Место вызова
1	RtTransport.initialize(context)	Инициализирует встраивание. Библиотека начинает отслеживать подключение и отключение устройств Рутокен (кроме подключений по NFC) и позволяет настроить дальнейшую работу с NFC	Рекомендуется: в методе Activity.onStart; в методе Service.onCreate – в случае использования внутри сервиса.
2	RtTransport.enableNfcForegroundDispatch(activity)	Включает NFC foreground dispatching для данной Activity	ТОЛЬКО из Main потока в методе Activity.onResume.
3	RtTransport.handleNfcIntent(intent)	Обрабатывает NFC интент, полученный при прикладывании устройств Рутокен. Интенты от устройств других производителей не обрабатываются. Применяется для дальнейшей установки соединения с Рутокен	При получении каждого NFC интента. Например. внутри Activity.onNewIntent
4	RtTransport.disableNfcForegroundDispatch(activity)	Выключает NFC foreground dispatching для данной Activity	ТОЛЬКО из Main потока в методе Activity.onPause
5	RtTransport.finalize(context)	Завершает работу встраивания	Рекомендуется: в методе Activity.onStop; в методе Service.onDestroy – в случае использования внутри сервиса.

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

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

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

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

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

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

Автоматическая обработка устройств Рутокен с NFC осуществляется только для тех Activity, которые реализуют OnNewIntentProvider.

Если базовый класс Activity уже реализует интерфейс OnNewIntentProvider (как в случае с ComponentActivity), то явная реализация интерфейса не обязательна.

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

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