Integration Guide

Follow the Quick Start first. This page adds platform specifics and operational detail.

Hosted by Lynes

You do not deploy the Webview yourself. Lynes runs a dedicated instance (e.g. https://gamification.your-brand.example.com) connected to your Lynes tenant. Your only integration surface is:

• Loading that URL in a native WebView
• Sending a JWT on the initial request
• Handling the two native callback URLs

1. Choose path and query parameters

The path selects the screen. Query parameters configure language, theme, and back behaviour.

Replace {WEBVIEW_URL} with the base URL from Lynes onboarding.

entrypoint — back button only

entrypoint is stored for the browser session and controls when the header back button closes the Webview (via your close callback) and returns the user to your app — vs. navigating to the previous screen inside the Webview.

It does not auto-redirect to another route. If the user should land on the leaderboard, load /leaderboard directly and set entrypoint=leaderboard.

Example: user opened from your leaderboard menu → load:

{WEBVIEW_URL}/leaderboard?lang=de&platform=android&entrypoint=leaderboard

From /leaderboard/info, back stays inside the Webview. From /leaderboard with that entrypoint, back triggers your close callback.

Full parameter list: URL Parameters & Routes.

2. JWT on the initial request

Production integrations must send:

Authorization: Bearer <JWT>

on the first document load (the HTML request that opens the Webview).

• Sign the JWT on your backend with the Lynes API secret.
• Use the same sub (user ID) as for event tracking.
• Required claims: see JWT Authentication.

iOS (WKWebView)

let webviewURL = URL(string: "{WEBVIEW_URL}/overview?lang=de&platform=ios&darkmode=false")!
var request = URLRequest(url: webviewURL)
request.setValue("Bearer \(jwt)", forHTTPHeaderField: "Authorization")
webView.load(request)

If the user reloads the page or you open a new Webview session, send a fresh JWT again.

Android

val url = "{WEBVIEW_URL}/overview?lang=de&platform=android&darkmode=false"
webView.loadUrl(url, mapOf("Authorization" to "Bearer $jwt"))

3. Session (automatic)

After the first load the Webview:

1. Stores the JWT briefly in an auth-token cookie (from the Authorization header).
2. Calls POST /api/token-exchange on the Webview host.
3. Exchanges the JWT with POST {API_BASE_URL}/auth/token on the Lynes API.
4. Keeps a session cookie/token for further API calls inside the UI.

You do not call /api/token-exchange from native code.

Details: Authentication.

4. Native callbacks

Register handlers for the exact callback URLs Lynes configured for your deployment (example):

Specification and code samples: Native Bridge.

5. Token refresh

• Set a sensible JWT exp (e.g. 1 hour).
• Before opening or reloading the Webview, issue a new JWT if the old one expired.
• The Webview re-validates the session periodically; expired sessions may navigate to your back callback.

6. Troubleshooting

7. Debug (development only)

GET {WEBVIEW_URL}/api/auth
Authorization: Bearer <JWT>

Returns decoded sub, exp, etc. Not for production page loads.

Related

• Quick Start
• URL Parameters & Routes
• Authentication
• Native Bridge