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

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

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

Требования

React Native 0.79–0.85 (интеграция протестирована с этими версиями)
iOS 15+
Android 7.0+ (min API 24)
OkHttp 5.1.0
Kotlin 2.2.0

iOS SDK собран с использованием Xcode 26.2 и Swift 6.2.

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

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

В поставку React Native SDK входят нативные Android и iOS SDK, а также файлы интеграции с сетевым слоем React Native:

android/libs/servicepipe-core-1.0.3-release.aar — ядро Servicepipe Android SDK;
android/libs/servicepipe-okhttp-1.0.3-release.aar — интеграция Android SDK с OkHttp, который используется сетевым модулем React Native;
ios/SPURLSession-1.0.3.xcframework — фреймворк Servicepipe iOS SDK;
ios/Networking — файлы, которые подключают Servicepipe SDK к RCTNetworking;
ios/SPExample-Bridging-Header.h — пример Objective-C Bridging Header для iOS-проекта;
examples — демо-приложения для разных версий React Native.

React Native-интеграция подключает Servicepipe SDK к запросам, которые проходят через стандартный сетевой стек React Native: fetch, XMLHttpRequest и библиотеки, которые используют их внутри.

Если в вашем приложении есть собственные нативные модули с отдельными OkHttpClient, URLSession или другими HTTP-клиентами, подключите Servicepipe SDK к этим клиентам отдельно.

Интеграция

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

Скопируйте каталог android/libs из архива SDK в каталог android/app вашего React Native-проекта.

В build.gradle Android-модуля app добавьте зависимости:

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

После этого выполните Gradle Sync.

2. Подключите SDK к сетевому модулю React Native на Android

В MainApplication инициализируйте SDK, зарегистрируйте Activity lifecycle callbacks и передайте React Native OkHttp-клиент с добавленным SPInterceptor.

import com.facebook.react.modules.network.OkHttpClientFactory
import com.facebook.react.modules.network.OkHttpClientProvider
import com.facebook.react.modules.network.OkHttpClientProvider.getOkHttpClient

import okhttp3.OkHttpClient

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

...

override fun onCreate() {
    super.onCreate()

    SPService.init(this)
    registerActivityLifecycleCallbacks(
        SPService.getSPInstance().getActivityCallbacks()
    )
    OkHttpClientProvider.setOkHttpClientFactory(
        SPOkHttpClientFactory(getOkHttpClient())
    )

    ...
}

Создайте SPOkHttpClientFactory:

class SPOkHttpClientFactory(
    private val defaultClient: OkHttpClient
) : OkHttpClientFactory {
    override fun createNewNetworkModuleClient(): OkHttpClient {
        return defaultClient.newBuilder()
            .addInterceptor(SPInterceptor(SPService.getSPInstance()))
            .followRedirects(false)
            .build()
    }
}

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

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

Если в проекте уже используется собственная OkHttpClientFactory, не заменяйте остальные настройки клиента. Добавьте SPInterceptor в существующий builder и сохраните остальные interceptor(ы), timeout(ы) и настройки приложения.

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

3. Добавьте iOS-файлы в проект

Откройте .xcworkspace iOS-приложения в Xcode.

Скопируйте из архива SDK в iOS-проект:

ios/SPURLSession-1.0.3.xcframework;
ios/Networking.

В настройках target откройте: General → Frameworks, Libraries, and Embedded Content. Убедитесь, что SPURLSession-1.0.3.xcframework добавлен в список, и выставьте для него режим Embed & Sign. Режим нужен, чтобы Xcode встроил фреймворк в приложение и подписал его вместе с app bundle.

Убедитесь, что файлы из каталога Networking добавлены в Build Phases → Compile Sources для target приложения:

RCTNetworking+Servicepipe.m;
ServicepipeHttpHandler.mm;
URLSessionAdapter.swift.

Если Xcode предложит создать Objective-C Bridging Header из-за добавления Swift-файла, согласитесь. Если bridging header уже есть, добавьте в него содержимое из SPExample-Bridging-Header.h или используйте этот файл как пример.

В Build Settings target проверьте значение Objective-C Bridging Header. Оно должно указывать на bridging header вашего iOS-проекта.

Также проверьте импорт generated Swift header в файле ServicepipeHttpHandler.mm. В демо-приложении он выглядит так:

#import <SPExample-Swift.h>

В вашем проекте имя header обычно соответствует Product Module Name. Если target называется иначе, замените импорт на header вашего приложения, например:

#import <YourApp-Swift.h>

После добавления файлов React Native-запросы на iOS будут проходить через ServicepipeHttpHandler. Он использует SPURLSession, поэтому JS-код приложения менять не нужно: запросы через fetch, XMLHttpRequest и библиотеки на их основе продолжат работать как раньше.

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

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

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

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

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

SPService.init(this, CaptchaConfiguration.FULLSCREEN)

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

import ru.servicepipe.core.CaptchaConfiguration

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

Если вы используете конфигурацию отображения, передайте её в SPService.init в MainApplication вместо вызова SPService.init(this).

На iOS по умолчанию используется windowed со следующими параметрами:

width: 360;
height: 640;
cornerRadius: 48;
backgroundColor: UIColor.black.withAlphaComponent(0.3).

Чтобы поменять режим отображения на iOS, вызовите setCaptchaPresentationMode в нативном iOS-коде приложения до первого защищаемого запроса. Например, для полноэкранного отображения:

import SPURLSessionFramework

SPURLSession.setCaptchaPresentationMode(
    captchaPresentationMode: .fullScreen
)

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

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

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

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

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

Запустите React Native-приложение с подключённым SDK на Android и iOS.
Пройдите основные сценарии, где приложение обращается к API: например, авторизацию, загрузку данных, отправку формы или оформление заказа.
Убедитесь, что запросы выполняются успешно, ответы API обрабатываются как раньше и пользовательские сценарии завершаются без ошибок.

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

https://servicepipe.ru/F2xN8dM3sPqK6aZt

Запрос должен выполняться через стандартный сетевой стек React Native: например, через fetch или библиотеку, которая использует XMLHttpRequest/fetch внутри React Native.

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

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

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

Запуск демо-приложения

В архиве SDK в каталоге examples находятся демо-приложения для разных версий React Native. В них уже интегрирован Servicepipe SDK, а тестовый URL добавлен по умолчанию.

Чтобы запустить демо-приложение, распакуйте архив с нужной версией React Native, затем в корне папки SPExample выполните:

yarn install

cd ios
pod install

cd ..

yarn start --reset-cache

yarn ios
yarn android