Интеграция для Android

Как интегрировать SDK в ваше Android-приложение.

Особенности SDK

Не добавляет транзитивные зависимости.
Не требует обязательных дополнительных разрешений приложения.

Единственное опциональное разрешение, которое может понадобиться — если хотите, чтобы для определения страны устройства SDK мог использовать данные GPS, у приложения должен быть доступ к геолокации. Если доступа нет, вместо GPS SDK будет использовать мобильные данные и таймзону.
Добавляет в manifest разрешение ACCESS_NETWORK_STATE. Оно нужно, чтобы анализировать признаки активной сети. Пользователь не увидит системный запрос на это разрешение.

Требования

Android 7.0+ (min API 24)
OkHttp 5.1.0
Ktor 3.2.3
Kotlin 2.2.0

Если в вашем проекте используется другая версия OkHttp, Ktor или Kotlin, проверьте интеграцию на тестовой сборке.

Состав сборки

В поставку Android SDK входит:

servicepipe-core-1.1.0-release.aar — ядро Servicepipe SDK;
servicepipe-okhttp-1.1.0-release.aar — интеграция с OkHttp и Retrofit;
servicepipe-ktor-1.1.0-release.aar — интеграция с Ktor;
servicepipe-example-1.1.0-release.apk — демо-приложение для проверки работы SDK;
integration_guide.md — краткая инструкция по подключению.

В приложение нужно добавить servicepipe-core-1.1.0-release.aar и одну библиотеку интеграции — OkHttp или Ktor, в зависимости от того, какой HTTP-клиент используется в проекте.

Интеграция

1. Добавьте библиотеки в проект

Скопируйте нужные AAR-файлы в каталог libs вашего Android-модуля.

Если приложение использует OkHttp напрямую или Retrofit поверх OkHttp, добавьте зависимости:

dependencies {
    implementation files("libs/servicepipe-core-1.1.0-release.aar")
    implementation files("libs/servicepipe-okhttp-1.1.0-release.aar")
}

Если приложение использует Ktor, добавьте зависимости:

dependencies {
    implementation files("libs/servicepipe-core-1.1.0-release.aar")
    implementation files("libs/servicepipe-ktor-1.1.0-release.aar")
}

2. Инициализируйте SDK в Application

В классе Application инициализируйте SDK и зарегистрируйте Activity lifecycle callbacks — они нужны, чтобы SDK мог отображать антибот-проверки поверх экранов приложения.

import android.app.Application
import ru.servicepipe.core.SPService

class App : Application() {
    override fun onCreate() {
        super.onCreate()

        SPService.init(this)
        registerActivityLifecycleCallbacks(
            SPService.getSPInstance().getActivityCallbacks()
        )
    }
}

Если SDK не будет проинициализирован, при работе интеграции будет выброшено исключение IllegalStateException.

3. Подключите SDK к HTTP-клиенту

Подключите интеграцию Servicepipe к HTTP-клиенту, через который приложение отправляет запросы к ресурсу, защищённому Servicepipe. Для этого нужно добавить SPInterceptor или SPPlugin.

SPInterceptor и SPPlugin — это интеграции Servicepipe SDK с HTTP-клиентом приложения. Они не меняют бизнес-логику приложения, но подключают к HTTP-запросам служебную логику Servicepipe:

добавляют к запросам служебные cookies Servicepipe;
считывают и сохраняют Set-Cookie, которые передала в ответе система защиты;
если система защиты выдала CAPTCHA или JS-челлендж, обрабатывают этот сценарий и отображают антибот-проверку внутри приложения;
(если вы это включили) SDK может отправлять приложению события CAPTCHA: одно, когда CAPTCHA-проверка началась, второе — когда пользователь успешно её прошёл;
SDK может определять страну устройства и локальные признаки VPN, а также передавать эти данные вашему приложению локально (приложение должно вызывать API SDK) или добавлять к запросу в виде HTTP-заголовков (передачу заголовков вы настраиваете сами в ходе интеграции SDK).

Для OkHttp напрямую или Retrofit поверх OkHttp добавьте SPInterceptor:

import okhttp3.OkHttpClient
import ru.servicepipe.core.SPService
import ru.servicepipe.okhttp.SPInterceptor

val client = OkHttpClient.Builder()
    // другие настройки клиента
    .addInterceptor(SPInterceptor(SPService.getSPInstance()))
    .followRedirects(false)
    .build()

SPInterceptor должен быть последним interceptor-ом среди тех, которые затрагивают заголовки запроса.

Настройка followRedirects(false) нужна, чтобы корректно работал сценарий антибот-проверки: она отключает автопереход по редиректам, чтобы SDK смог работать с ними и распознавать, где обычный редирект, а где — переход на страницу CAPTCHA/JS-челленджа, который отдала система защиты.

Если приложение использует Retrofit, передайте созданный OkHttpClient в Retrofit.Builder.

Как и другие interceptor-ы OkHttp, SPInterceptor может пробросить IOException. Учитывайте это при обработке ошибок соединения.

Для Ktor установите SPPlugin в HttpClient:

import io.ktor.client.HttpClient
import io.ktor.client.engine.cio.CIO
import ru.servicepipe.ktor.SPPlugin

val httpClient = HttpClient(CIO) {
    // другие настройки клиента
    install(SPPlugin)
}

4. Настройте отображение антибот-проверок

SDK может отображать антибот-проверки в двух режимах:

FULLSCREEN — на весь экран;
WINDOWED — в окне поверх приложения.

По умолчанию используется WINDOWED с cornerRadius 48dp. Вы можете поменять настройки при инициализации SDK.

Чтобы отображать проверки на весь экран, задайте:

SPService.init(this, CaptchaConfiguration.FULLSCREEN)

Чтобы отображать проверки в окне с заданным радиусом скругления, используйте:

import ru.servicepipe.core.CaptchaConfiguration

val cornerRadius = 48f
SPService.init(
    this,
    CaptchaConfiguration.WINDOWED.withCornerRadius(cornerRadius)
)

Также можно кастомизировать CAPTCHA (делается вне вашего приложения):

установить другой вид CAPTCHA — по умолчанию используется с поворотом картинки, но можем заменить её на другую: с вводом символов либо с чекбоксом;
использовать в CAPTCHA присланные вами картинки;
сделать страницу CAPTCHA в вашем корпоративном стиле.

Как это сделать, описано в статьях 403 и CAPTCHA с вашим дизайном и CAPTCHA с вашими картинками.

5. (Опционально) настройте отслеживание состояния CAPTCHA

Если приложению нужно знать, что пользователь начал проходить CAPTCHA или успешно её прошёл, подпишитесь на события CAPTCHA.

В файле, где подписываетесь на события, импортируйте:

import ru.servicepipe.core.CaptchaStatusListener

Затем добавьте listener после инициализации SDK:

SPService.getSPInstance().setCaptchaStatusListener { status ->
    when (status) {
        CaptchaStatusListener.Status.IN_PROGRESS ->
            println("CAPTCHA status: ${status.name}, ${status.ip} id:${status.requestId}")
        CaptchaStatusListener.Status.SOLVED ->
            println("CAPTCHA status: ${status.name}, ${status.ip} id:${status.requestId}")
    }
}

SDK отправляет событие, когда CAPTCHA-проверка началась, и ещё одно, если она успешно пройдена. В событии передаются статус, IP и ID запроса.

6. (Опционально) настройте определение страны и VPN-признаков

SDK может определить страну, где находится устройство, и локальные признаки VPN. Эти данные ваше приложение может получить через API SDK либо их можно передать на ваш сервер в HTTP-заголовках.

Получить данные в приложении

Страна

Для определения страны SDK использует три источника данных:

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

В большинстве случаев приложению нужно получить только один код страны. Для этого вызовите:

val countryCode = SPService.getSPInstance().getCountryCode()

SDK сам выберет самый надёжный результат из доступных. Например, если GPS показывает одну страну, а таймзона — другую, SDK отдаст страну по более точному источнику; так как GPS надёжнее таймзоны, SDK выберет результат по GPS.

Если приложению нужны все найденные варианты, вызовите:

val countryCodes = SPService.getSPInstance().getCountryCodes()

SDK вернёт список CountryCode.Result. Каждый элемент содержит код страны по стандарту ISO 3166-1 alpha-2 и источник, по которому SDK его определил. Например:

countryCode: "ru", source: GPS
countryCode: "de", source: TIMEZONE

Такой вызов полезен, если вы хотите сами обработать спорные случаи в бизнес-логике: например, отдельно учитывать ситуацию, когда GPS, мобильные данные и таймзона указывают на разные страны.

Если источники не конфликтуют и указывают на одну страну, оба способа дадут один и тот же код страны.

VPN

Чтобы получить признаки VPN, вызовите:

val vpnSigns = SPService.getSPInstance().getVpnSigns()

SDK вернёт список найденных VPN-признаков. Для каждого признака доступны описание, тип и уровень уверенности.

Передать данные на сервер

SDK может добавлять к запросам HTTP-заголовки с информацией о стране устройства и VPN-признаках. Чтобы включить эту механику, используйте:

SPService.getSPInstance().setVpnHeadersState(true)

После этого SDK будет добавлять к запросам HTTP-заголовки x-cybert-mobile-country-code и x-cybert-mobile-vpn-signs, например:

x-cybert-mobile-country-code: ru
x-cybert-mobile-vpn-signs: direct_sign_1,direct_sign_2,indirect_sign_1

x-cybert-mobile-vpn-signs отправляется, только если SDK нашёл признаки VPN. Если признаков нет, заголовка не будет.

7. Добавьте feature toggle

Наш SDK тщательно протестирован, но на первое время всё равно рекомендуем включать его через feature toggle. Так вы сможете сначала включить SDK для части пользователей и убедиться, что всё работает штатно, а если возникнут проблемы — быстро отключить его без выпуска новой версии приложения.

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

Для OkHttp и Retrofit это может выглядеть так:

val builder = OkHttpClient.Builder()
    // другие настройки клиента

if (RemoteFeatures.servicepipeIntegrationEnabled()) {
    builder
        .addInterceptor(SPInterceptor(SPService.getSPInstance()))
        .followRedirects(false)
}

val client = builder.build()

Для Ktor так:

val httpClient = HttpClient(CIO) {
    // другие настройки клиента

    if (RemoteFeatures.servicepipeIntegrationEnabled()) {
        install(SPPlugin)
    }
}

8. Протестируйте интеграцию

После подключения SDK проверьте, что приложение работает как раньше:

Запустите приложение с подключённым SDK.
Пройдите основные сценарии, где приложение обращается к API: например, авторизацию, загрузку данных, отправку формы или оформление заказа.
Убедитесь, что запросы выполняются успешно, ответы API обрабатываются как раньше и пользовательские сценарии завершаются без ошибок.
Если включили передачу информации о стране устройства или VPN:
- напрямую приложению, через API SDK — проверьте на тестовой сборке, что приложение получило нужные данные;
- на сервер, в HTTP-заголовках — сначала проверьте на тестовой сборке, что запросы содержат x-cybert-mobile-country-code, затем включите VPN и проверьте, что появился x-cybert-mobile-vpn-signs.

Затем проверьте, что SDK корректно обрабатывает CAPTCHA. Для этого выполните из приложения запрос к тестовому URL через HTTP-клиент с подключённым SPInterceptor или SPPlugin:

https://servicepipe.ru/F2xN8dM3sPqK6aZt

Если SDK подключён корректно, приложение отобразит CAPTCHA внутри Android WebView. Если пройти её успешно, тестовый URL вернёт ответ 404. При повторных запросах CAPTCHA уже не будет показываться, потому что SDK получит «разрешающую» cookie от системы защиты и будет добавлять её в запросы. Когда срок жизни этой cookie истечёт либо хранилище cookies будет очищено путём переустановки приложения, URL снова будет выдавать CAPTCHA.

9. Интеграция завершена

Поздравляем, вы подключили Servicepipe Android SDK! Теперь он помогает защищать ваше приложение от эксплуатации автоматизациями.