SDK

Вы поставите нашу библиотеку для iOS или Android, опознаете покупателя, покажете экран с ценами прямо из приложения и узнаете, открыт ли доступ.

Перед началом

• ID проекта. Кабинет: «Настройки проекта» → «Подключение приложения» → «Для разработчика». Адрес API — https://api.subster.ai.
• iOS 14 или новее, Android 7.0 (API 24) или новее.

Шаг 1. Поставьте библиотеку

iOS. Xcode → File → Add Package Dependencies, адрес https://github.com/web2web-dev/web2app-ios-sdk.git, версия 0.8.1, продукт Web2AppSDK.

Android. Библиотека лежит в JitPack; разрешение на интернет она объявляет сама.

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://jitpack.io") }
    }
}

// build.gradle.kts of the app module
dependencies {
    implementation("com.github.web2web-dev:web2app-android-sdk:0.7.2")
}

Шаг 2. Вызовите configure при запуске

Один раз, до любого другого вызова. Без него методы отвечают отказом и в сеть не ходят.

import Web2AppSDK

// once at launch; baseUrl is a URL, not a String
Web2App.configure(projectId: "<PROJECT_ID>", baseUrl: URL(string: "https://api.subster.ai")!)

import app.web2app.sdk.Web2AppSdk

// once at launch, e.g. in Application.onCreate(); Android needs a context
// since 0.7.2 configure warms up WebView (hundreds of ms on the main thread);
// opt out with warmUpWebView = false; call WebView.setDataDirectorySuffix before configure
Web2AppSdk.configure(applicationContext, "<PROJECT_ID>", "https://api.subster.ai")

Пример в кабинете не соберётся: там import Web2App, адрес строкой на iOS и нет контекста на Android.

Шаг 3. Опознайте покупателя

Библиотека меняет код перехода на идентификатор покупателя (guid) и сохраняет его на устройстве.

Как достать код из ссылки — «Возврат в приложение», шаг 3. Что стоит за каждым путём — «Как мы узнаём покупателя».

Web2App.identify(deepLinkValue: code) { result in
    switch result {
    case .success(let guid): print("identified:", guid)
    case .failure(.needsEmailFallback): showEmailField() // then Web2App.requestEmailRecovery(email) { _ in }
    case .failure(let error): print("identify failed:", error)
    }
}

Web2AppSdk.identify(
    onResult = { result -> result.onSuccess { guid -> /* identified */ } },
    onNeedEmail = { showEmailField() }, // then Web2AppSdk.requestEmailRecovery(email) { }
)

Где ошибаются чаще всего:

• На iOS сохранённый идентификатор главнее кода. Если он уже есть, identify(deepLinkValue:) возвращает его и код не обменивает. Покупатель, которому библиотека успела завести идентификатор — например, при показе экрана с ценами, — по новой ссылке возврата на другой не перейдёт. На Android identifyWithDeepLinkValue обменивает код всегда.
• У AppsFlyer код лежит в deep_link_sub1, дубль в af_sub1. В deep_link_value стоит слово handoff, и обмен с ним проваливается.
• Отпечаток устройства пробуется два часа с первой неудачи — столько живёт слепок на сервере. Потом библиотека сразу просит почту, в логах — шаг identify.fingerprint_window_expired.
• Отметку первого открытия шлёт библиотека после удачного опознания: шаг 5 страницы «Возврат в приложение» не нужен.

Шаг 4. Спросите право доступа

entitlement спрашивает право по сохранённому идентификатору — тем же открытым адресом, что в «Проверить право доступа».

Web2App.entitlement { grant in
    // iOS calls this closure on a background thread
    DispatchQueue.main.async {
        if grant?.isActive == true { unlockPremium() }
    }
}

Web2AppSdk.entitlement { grant ->
    if (grant?.isActive == true) unlockPremium()
}

Где короткий ответ подводит:

• Библиотека отдаёт одну запись, самую свежую, а не список. Если записей несколько и свежая истекла или отозвана, isActive будет false, хотя старая действует. Продаёте больше одного продукта — разбирайте весь список со своего сервера или открытым адресом из приложения.
• Пустой ответ приходит в трёх случаях: записей нет, идентификатор ещё не сохранён, сеть не ответила. Не отнимайте доступ по одному пустому ответу.

Шаг 5. Покажите экран с ценами из приложения

Начните со встроенного окна: схема возврата ему не нужна, исход приходит сразу, а события экрана доезжают до слушателя.

Окно браузера — это SFSafariViewController и Chrome Custom Tabs. Необязательные параметры у всех четырёх: email подставится в поле почты, adaptyProfileId и revenuecatProfileId — для подписочной платформы.

Web2App.openWebPaywallEmbedded(paywallId: "<PAYWALL_ID>", email: userEmail) { result in
    switch result {
    case .paid(let grant): unlockPremium(grant)
    case .pending: recheckEntitlementLater() // paid, the record has not arrived yet
    case .notPaid: break
    case .unavailable: showError()           // the screen was not shown
    }
}

Web2AppSdk.openWebPaywallEmbeddedById(context, "<PAYWALL_ID>", email = userEmail) { result ->
    when (result) {
        is PaywallResult.Paid -> unlockPremium(result.grant)
        PaywallResult.Pending -> recheckEntitlementLater()
        PaywallResult.NotPaid -> Unit
        PaywallResult.Unavailable -> showError()
    }
}

ID экрана копируется в кабинете: «Воронки» → вкладка «Пейволлы» → ⋮ в строке экрана → «Скопировать ID». По ID находится только экран, к которому домен привязан напрямую; экран внутри привязанной воронки не найдётся.

Оплата ложится на идентификатор библиотеки, тот, что отдаёт currentGuid(); если сохранённого нет, библиотека заводит новый. Его и передавайте своему серверу.

На Android окно браузера не сообщает о закрытии, поэтому через минуту после открытия колбэк получит nil, даже если покупатель ещё платит. Спросите право заново, когда приложение вернулось на передний план.

Новый показ закрывает прежний: два встроенных окна одновременно не живут.

Показ без ожидания на iOS

Экран, загруженный заранее, открывается по ID сразу.

Web2App.preloadPaywalls(paywallIds: ["<PAYWALL_ID>"], email: userEmail)
// later, with the same email and profile ids
Web2App.openWebPaywallEmbedded(paywallId: "<PAYWALL_ID>", email: userEmail) { result in /* as above */ }

События встроенного окна

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

Web2App.setFunnelEventListener { name, data in
    analytics.log(name, ["screen": data.screenIndex as Any])
}
Web2App.setFunnelEventListener(nil) // unsubscribe when the screen is gone

Web2AppSdk.setFunnelEventListener { name, data ->
    analytics.log(name, mapOf("screen" to data.screenIndex))
}
Web2AppSdk.setFunnelEventListener(null) // unsubscribe when the screen is gone

• screenIndex считается с единицы — сколько экранов посетитель уже прошёл, screenTotal — длина его собственного пути. Так считается с 3 сентября 2026 года; у ветвящихся воронок в событиях до этой даты доля пройденного завышена.
• Оплатил покупатель или закрыл экран, по событию не узнать: paywall_result приходит в обоих случаях без исхода. Смотрите результат показа.
• Почты и самих ответов в событиях нет. Ответы забирает ваш сервер — «Свойства покупателя».

Квиз во встроенном окне

openQuizEmbedded(quizURL:) на iOS и openQuizEmbedded(context, quizUrl) на Android открывают квиз в том же окне, с теми же событиями. Результат — причина закрытия: page — страница, user — пользователь, paid — внутри окна прошла оплата; unavailable — нет configure или сорванный показ. Квиз, в отличие от экрана с ценами, доступ не проверяет: после оплаты спросите право (шаг 4).

Открытия по ID у квиза нет. Адрес по ID отдаёт GET /public/quiz-url/<quizId> — ответ { "success": true, "data": { "url": "…" } }, либо 404, если квиз не опубликован или домен привязан не к нему самому.

Пока включён режим проверки

Режим проверки включают в кабинете — как. Пока он включён, библиотека получает действующую запись с уровнем test на любой идентификатор, который знает проект.

• Отличайте такую запись полем testMode (шаг 4) или проверкой level == "test".
• Показ экрана с ценами тоже может вернуть «оплачено» без оплаты: идентификатор библиотеки проект узнаёт, как только страница открылась. Путь оплаты проверяйте тестовыми ключами Stripe.

Что библиотека делает сама, а что остаётся вам

Отладка

• Потоки. На Android все колбэки приходят на главном потоке. На iOS так приходят показы и слушатель, а identify, entitlement и requestEmailRecovery зовут замыкание с фонового потока — интерфейс трогайте через DispatchQueue.main.async.
• Журнал. Каждый шаг библиотека пишет в консоль Xcode с префиксом [Web2App] и в Logcat с тегом Web2App. Ту же ленту видно в кабинете — «Диагностика».
• Опознать заново на том же устройстве. debugClear() стирает сохранённый идентификатор, debugSetGuid подставляет свой. На Android оба метода попадают и в релизную сборку: оборачивайте вызов в if (BuildConfig.DEBUG).

Дальше

• Возврат в приложение — ссылки, которыми браузер открывает приложение, и схема возврата.
• Как мы узнаём покупателя — шесть путей опознания и что делать, когда путь не сработал.
• Проверить право доступа — весь ответ по полям, если записей у покупателя больше одной.
• Диагностика — «Логи SDK» и разбор жалобы «оплатил, а доступа нет».