Native Bridge (Callbacks)

The hosted Webview cannot close itself or open the system browser. It triggers navigation to custom URL schemes that your app must intercept.

Configured per deployment

Lynes configures two callback URLs on your hosted Webview instance when it is provisioned. During onboarding you receive the exact strings — for example:

Callback	Example
Close Webview	`myapp://loyalty/back`
Open external link	`myapp://loyalty/external?url=…`

Your iOS/Android app must register the same URL scheme and handle these paths. If your handlers differ from what Lynes configured on the hosted instance, callbacks will not work.

ℹ️

You implement what Lynes configures

Do not invent callback URLs in isolation. Lynes aligns the hosted deployment with the scheme you register in the App Store / Play Console.

Close Webview (`back`)

Example:

myapp://loyalty/back

Triggered when:

User taps back on a root screen for the current entrypoint (see URL Parameters)
User is on / or /overview (always closes the Webview)
Session/token error handlers need to return control to the app

Your app: cancel WebView navigation, dismiss the WebView — the user returns to your app, your app stays open.

Open external URL (`external`)

Format:

myapp://loyalty/external?url={URL_ENCODED}

Query	Required	Description
`url`	Yes	Target HTTPS URL, percent-encoded

Triggered when: user opens a partner link, terms page, or other URL that must leave the Webview.

Your app: decode url, open in SFSafariViewController, Chrome Custom Tab, or external browser.

Example:
myapp://loyalty/external?url=https%3A%2F%2Fpartner.example.com%2Fterms
→ open https://partner.example.com/terms

Back vs. in-Webview back

Screen	Back button
`/` or `/overview`	→ close Webview (callback)
Feature root with matching `entrypoint` (e.g. `/leaderboard` + `entrypoint=leaderboard`)	→ close Webview (callback)
Deeper screens (e.g. `/offers/{id}`, `/leaderboard/info`)	previous page inside Webview
`/shops/{shopId}` with `entrypoint=shop`	→ close Webview (callback)

Load the correct path and entrypoint together — see Integration Guide.

iOS

func webView(
    _ webView: WKWebView,
    decidePolicyFor navigationAction: WKNavigationAction,
    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void
) {
    guard let url = navigationAction.request.url else {
        decisionHandler(.allow)
        return
    }
 
    // Use the exact back URL from Lynes onboarding, e.g. myapp://loyalty/back
    if url.absoluteString == "{BACK_CALLBACK_URL}" {
        decisionHandler(.cancel)
        dismissWebView()
        return
    }
 
    // External: myapp://loyalty/external?url=...
    if url.host == "loyalty", url.path == "/external",
       let target = URLComponents(url: url, resolvingAgainstBaseURL: false)?
           .queryItems?.first(where: { $0.name == "url" })?.value?
           .removingPercentEncoding {
        decisionHandler(.cancel)
        openExternalURL(target)
        return
    }
 
    decisionHandler(.allow)
}

Also handle application(_:open:options:) for cold starts.

Android

Intent filter for your scheme/host, then in WebViewClient:

override fun shouldOverrideUrlLoading(
    view: WebView?,
    request: WebResourceRequest?
): Boolean {
    val url = request?.url?.toString() ?: return false
 
    if (url == "{BACK_CALLBACK_URL}") {
        dismissWebView()
        return true
    }
 
    val uri = request.url
    if (uri.path == "/external") {
        uri.getQueryParameter("url")?.let { openExternalURL(Uri.decode(it)) }
        return true
    }
    return false
}

Replace {BACK_CALLBACK_URL} with the value Lynes gave you.

Security

Allow-list domains in external if needed.
Do not log full JWTs or session tokens.
Reject unknown paths on your callback host.

Authentication About Our Event-Driven Gamification Platform | Lynes Loyalty