Интеграция для iOS
Как интегрировать SDK в ваше iOS-приложение.
| SDK не требует дополнительных разрешений приложения и не добавляет транзитивные зависимости. |
Требования
-
iOS 15+
SDK собран с использованием Xcode 26.2 и Swift 6.2. Если в вашем проекте используется другая версия Xcode или Swift, проверьте интеграцию на тестовой сборке.
Состав сборки
В поставку iOS SDK входит:
-
SPURLSession-1.0.3.xcframework— фреймворк Servicepipe SDK; -
integration_guide.md— краткая инструкция по подключению.
SPURLSession-1.0.3.xcframework содержит сборки для:
-
реальных iOS-устройств:
ios-arm64; -
iOS Simulator:
ios-arm64_x86_64-simulator.
Интеграция
1. Добавьте фреймворк в проект
Перетащите SPURLSession-1.0.3.xcframework в навигатор Xcode.
В настройках target откройте: General → Frameworks, Libraries, and Embedded Content. Убедитесь, что фреймворк добавлен в список, и выставьте для него режим: Embed & Sign. Режим нужен, чтобы Xcode встроил фреймворк в приложение и подписал его вместе с app bundle. Без этого приложение может не запуститься на устройстве или не пройти проверку подписи.
2. Подключите SDK в коде
В файлах, где выполняются защищаемые сетевые запросы (то есть запросы к ресурсу, который защищает Servicepipe), импортируйте SDK:
import SPURLSessionFramework
3. Замените URLSession на SPURLSession
В защищаемых сетевых взаимодействиях замените использование URLSession на SPURLSession.
Например, измените вызовы вида:
let (data, _) = try await URLSession(
configuration: URLSessionConfiguration.default
).data(for: request)
На вызовы вида:
let (data, _) = try await SPURLSession(
configuration: URLSessionConfiguration.default
).data(for: request)
SPURLSession — это сетевой клиент Servicepipe SDK с интерфейсом, идентичным URLSession. Он поддерживает dataTask, uploadTask, downloadTask, async-запросы и работу с delegate. Особенность в том, что помимо функционала URLSession он может обрабатывать служебную логику Servicepipe:
-
добавляет к запросам служебные cookies Servicepipe;
-
считывает и сохраняет
Set-Cookie, которые передала в ответе система защиты; -
если система защиты выдала CAPTCHA или JS-челлендж, обрабатывает этот сценарий и отображает проверку внутри приложения.
Логика обработки запроса и ответа в приложении при этом остаётся такой же, как при использовании URLSession.
4. Настройте отображение антибот-проверок
SDK может отображать CAPTCHA и JS-челлендж в двух режимах:
-
fullScreen— на весь экран. -
windowed— в окне поверх приложения.
По умолчанию используется windowed со следующими параметрами:
width: 360 height: 640 cornerRadius: 48 backgroundColor: UIColor.black.withAlphaComponent(0.3)
Вы можете поменять настройки через setCaptchaPresentationMode.
Чтобы отображать проверки на весь экран, задайте:
SPURLSession.setCaptchaPresentationMode(
captchaPresentationMode: .fullScreen
)
Чтобы отображать проверки в окне с заданными параметрами:
let captchaPresentationMode = CaptchaPresentationMode.windowed(
width: 320,
height: 560,
cornerRadius: 24,
backgroundColor: UIColor.black.withAlphaComponent(0.4)
)
SPURLSession.setCaptchaPresentationMode(
captchaPresentationMode: captchaPresentationMode
)
Доступные режимы описаны в CaptchaPresentationMode:
public enum CaptchaPresentationMode {
case fullScreen
case windowed(
width: CGFloat = 360,
height: CGFloat = 640,
cornerRadius: CGFloat = 48,
backgroundColor: UIColor = UIColor.black.withAlphaComponent(0.3)
)
}
|
Также можно кастомизировать CAPTCHA (делается вне вашего приложения):
Как это сделать, описано в статьях 403 и CAPTCHA с вашим дизайном и CAPTCHA с вашими картинками. |
5. Добавьте feature toggle
Наш SDK тщательно протестирован, но на первое время всё равно рекомендуем включать его через feature toggle. Так вы сможете сначала включить SDK для части пользователей и убедиться, что всё работает штатно, а если возникнут проблемы — быстро отключить его без выпуска новой версии приложения.
Это обычная практика для мобильных приложений, когда в них добавляют новый сетевой компонент. Пример ниже показывает общий принцип подключения через feature toggle.
|
|
// Пример: замените на ваш механизм feature toggle / remote config / A/B testing.
let servicepipeIntegrationEnabled = YourFeatureFlags.servicepipeIntegrationEnabled()
let (data, response) = if servicepipeIntegrationEnabled {
try await SPURLSession(
configuration: URLSessionConfiguration.default,
delegate: delegate,
delegateQueue: nil
).data(for: request)
} else {
try await URLSession(
configuration: URLSessionConfiguration.default,
delegate: delegate,
delegateQueue: nil
).data(for: request)
}
6. Протестируйте интеграцию
После подключения SDK проверьте, что приложение работает как раньше:
-
Запустите приложение с подключённым SDK.
-
Пройдите основные сценарии, где приложение обращается к API: например, авторизацию, загрузку данных, отправку формы или оформление заказа.
-
Убедитесь, что запросы выполняются успешно, ответы API обрабатываются как раньше и пользовательские сценарии завершаются без ошибок.
Затем проверьте, что SDK корректно обрабатывает CAPTCHA. Для этого выполните из приложения запрос к тестовому URL с помощью SPURLSession:
https://servicepipe.ru/F2xN8dM3sPqK6aZt
Если SDK подключён корректно, приложение отобразит CAPTCHA внутри WKWebView. Если пройти её успешно, тестовый URL вернёт ответ 404. При повторных запросах CAPTCHA уже не будет показываться, потому что SDK получит «разрешающую» cookie от системы защиты и будет добавлять её в запросы. Когда срок жизни этой cookie истечёт либо хранилище cookies будет очищено путём переустановки приложения, URL снова будет выдавать CAPTCHA.