SDK

You will install our iOS or Android library, identify the customer, show the paywall from the app and learn whether access is open.

Before you start

• Project ID. Cabinet: "Project settings" → "App connection" → "For developers". API address: https://api.subster.ai.
• iOS 14 or later, Android 7.0 (API 24) or later.

Step 1. Install the library

iOS. Xcode → File → Add Package Dependencies, address https://github.com/web2web-dev/web2app-ios-sdk.git, version 0.8.1, product Web2AppSDK.

Android. The library is on JitPack and declares the internet permission itself.

// 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")
}

Step 2. Call configure at launch

Once, before any other call. Without it, methods refuse and make no network requests.

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")

The cabinet example will not compile: import Web2App, a string address on iOS, no context on Android.

Step 3. Identify the customer

The library exchanges the handoff code for the buyer identifier (guid) and stores it on the device.

Getting the code from the link: Return to the app, step 3. What is behind each path: How we recognise the customer.

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) { }
)

Common mistakes:

• On iOS the stored identifier beats the code. If one exists, identify(deepLinkValue:) returns it without exchanging the code. A customer who already got an identifier from the library (say, when shown the paywall) will not switch via a new return link. On Android identifyWithDeepLinkValue always exchanges the code.
• In AppsFlyer the code is in deep_link_sub1, copied in af_sub1. deep_link_value holds the word handoff, which fails the exchange.
• The device fingerprint is tried for two hours from the first failure, the snapshot's lifetime on the server. Then the library asks for the email at once; the log shows identify.fingerprint_window_expired.
• The library sends the first-open mark after identification: skip step 5 of the Handoff page.

Step 4. Ask for the entitlement

entitlement asks by the stored identifier, via the public address from Check the 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()
}

Where the short answer misleads:

• The library returns one grant, the latest, not a list. If the latest of several expired or was revoked, isActive is false though an older one is valid. Selling more than one product? Read the whole list from your server or via the public address from the app.
• An empty answer has three causes: no grants, no stored identifier yet, no network response. Do not revoke access on one empty answer.

Step 5. Show the paywall from the app

Start with the embedded window: no return scheme needed, the outcome arrives at once, and screen events reach the listener.

The browser window is SFSafariViewController or Chrome Custom Tabs. Optional for all four: email prefills the email field; adaptyProfileId and revenuecatProfileId are for the subscription platform.

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()
    }
}

Copy the screen ID in the cabinet: "Funnels" → "Paywalls" tab → ⋮ in the screen row → "Copy the ID". An ID finds only a screen bound to a domain directly, not one inside a bound funnel.

The payment goes to the library's identifier, returned by currentGuid(); if none is stored, the library creates one. Pass it to your server.

On Android the browser window does not report closing, so a minute after opening the callback gets nil, even if the customer is still paying. Ask again when the app returns to the foreground.

A new display closes the previous one: two embedded windows never coexist.

Display without waiting on iOS

A preloaded screen opens by ID instantly.

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 */ }

Embedded window events

The embedded page reports every visitor step. The library has one listener: a new one replaces the old, an empty value removes it, nothing removes it automatically. The browser window has no events.

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 counts from one: screens the visitor has passed; screenTotal is the length of their own path. This holds since 3 September 2026; for branching funnels, earlier events overstate progress.
• The event cannot tell payment from closing: paywall_result arrives in both cases without an outcome. Use the display result.
• Events carry neither email nor answers. Your server collects answers: Buyer properties.

Quiz in the embedded window

openQuizEmbedded(quizURL:) on iOS and openQuizEmbedded(context, quizUrl) on Android open the quiz in the same window, with the same events. The result is the close reason: page, the page; user, the user; paid, a payment inside the window; unavailable, no configure or a broken display. Unlike the paywall, the quiz does not check access: after payment, ask for the entitlement (step 4).

There is no opening by ID for quizzes. GET /public/quiz-url/<quizId> returns the address: { "success": true, "data": { "url": "…" } }, or 404 if the quiz is unpublished or the domain is not bound to the quiz itself.

While test mode is on

Test mode is turned on in the cabinet: how. While it is on, the library gets an active test-level grant for any identifier the project knows.

• Recognize it by the testMode field (step 4) or level == "test".
• The paywall can also return "paid" without payment: the project learns the library's identifier once the page opens. Test payments with Stripe test keys.

What the library does and what is left to you

Debugging

• Threads. On Android all callbacks arrive on the main thread. On iOS so do displays and the listener, but identify, entitlement and requestEmailRecovery call back on a background thread: touch the UI via DispatchQueue.main.async.
• Log. The library logs each step to the Xcode console with the prefix [Web2App] and to Logcat with the tag Web2App. The cabinet shows the same feed: Troubleshooting.
• Re-identify on the same device. debugClear() erases the stored identifier, debugSetGuid sets your own. On Android both also ship in release builds: wrap calls in if (BuildConfig.DEBUG).

Next

• Return to the app: links that open the app from the browser, and the return scheme.
• How we recognise the customer: six identification paths and what to do when one fails.
• Check the entitlement: the full answer field by field, for customers with several grants.
• Troubleshooting: "SDK logs" and the complaint "I paid but have no access".