Интеграция для Android
Как интегрировать SDK в ваше Android-приложение.
| SDK не требует дополнительных разрешений приложения и не добавляет транзитивные зависимости. |
Требования
-
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.0.3-release.aar— ядро Servicepipe SDK; -
servicepipe-okhttp-1.0.3-release.aar— интеграция с OkHttp и Retrofit; -
servicepipe-ktor-1.0.3-release.aar— интеграция с Ktor; -
servicepipe-example-1.0.3-release.apk— демо-приложение для проверки работы SDK; -
integration_guide.md— краткая инструкция по подключению.
В приложение нужно добавить servicepipe-core-1.0.3-release.aar и одну библиотеку интеграции — OkHttp или Ktor, в зависимости от того, какой HTTP-клиент используется в проекте.
Интеграция
1. Добавьте библиотеки в проект
Скопируйте нужные AAR-файлы в каталог libs вашего Android-модуля.
Если приложение использует OkHttp напрямую или Retrofit поверх OkHttp, добавьте зависимости:
dependencies {
implementation files("libs/servicepipe-core-1.0.3-release.aar")
implementation files("libs/servicepipe-okhttp-1.0.3-release.aar")
}
Если приложение использует Ktor, добавьте зависимости:
dependencies {
implementation files("libs/servicepipe-core-1.0.3-release.aar")
implementation files("libs/servicepipe-ktor-1.0.3-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.
|
|
Для 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()
|
Настройка Если приложение использует Retrofit, передайте созданный Как и другие interceptor-ы OkHttp, |
Для 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 (делается вне вашего приложения):
Как это сделать, описано в статьях 403 и CAPTCHA с вашим дизайном и CAPTCHA с вашими картинками. |
5. Добавьте 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)
}
}
6. Протестируйте интеграцию
После подключения SDK проверьте, что приложение работает как раньше:
-
Запустите приложение с подключённым SDK.
-
Пройдите основные сценарии, где приложение обращается к API: например, авторизацию, загрузку данных, отправку формы или оформление заказа.
-
Убедитесь, что запросы выполняются успешно, ответы API обрабатываются как раньше и пользовательские сценарии завершаются без ошибок.
Затем проверьте, что SDK корректно обрабатывает CAPTCHA. Для этого выполните из приложения запрос к тестовому URL через HTTP-клиент с подключённым SPInterceptor или SPPlugin:
https://servicepipe.ru/F2xN8dM3sPqK6aZt
Если SDK подключён корректно, приложение отобразит CAPTCHA внутри Android WebView. Если пройти её успешно, тестовый URL вернёт ответ 404. При повторных запросах CAPTCHA уже не будет показываться, потому что SDK получит «разрешающую» cookie от системы защиты и будет добавлять её в запросы. Когда срок жизни этой cookie истечёт либо хранилище cookies будет очищено путём переустановки приложения, URL снова будет выдавать CAPTCHA.