Mobile implementation

This guide covers best practices for integrating AgeKit+ widgets into mobile applications. On the web, widgets are commonly embedded in iframes, but mobile apps need different approaches to display widget URLs effectively.

Overview

AgeKit+ widgets are URLs returned from API calls that contain the complete age verification interface. When integrating these widgets into mobile applications, you have several options for displaying them, each with different capabilities and trade-offs. The key considerations are:

• AgeKeys support: Whether users can create and use AgeKeys (FIDO-based passkeys) for future verifications
• Result communication: How verification results are delivered back to your app
• User experience: The level of integration and native feel

Mobile implementation methods

Android options

Android provides three primary methods for displaying widget URLs:

• Chrome Custom Tabs ⭐ Recommended - Opens the widget URL in a customized Chrome browser tab that maintains your app's branding. This provides full browser capabilities while keeping users within your app's context. Custom Tabs share cookies and authentication state with Chrome, enabling seamless experiences.

• WebView - Embeds web content directly within your app using Android's native WebView component. While simple to implement, WebView has limited support for modern web standards and can't access certain browser features.

Not recommended

WebView doesn't support WebAuthn, which is required for AgeKeys. Users won't be able to create or use AgeKeys when widgets are embedded using WebView. For the best user experience with full AgeKeys support, use Chrome Custom Tabs instead.

• Trusted Web Activity (TWA) - Displays web content in full-screen mode, primarily designed for Progressive Web Apps. TWAs require establishing a digital asset link between your app and the k-ID domain. When digital asset links aren't detected, TWA automatically falls back to Chrome Custom Tabs.

Not recommended

Trusted Web Activities aren't supported for widget integration. Digital asset links would need to be configured on k-ID's domains, which isn't available. Since TWA falls back to Chrome Custom Tabs in this case, use Chrome Custom Tabs directly for a simpler implementation.

iOS options

iOS provides three primary methods for displaying widget URLs:

• ASWebAuthenticationSession ⭐ Recommended - Designed specifically for secure authentication flows, this method presents web content in a system-managed browser view. It shares cookies with Safari and provides access to modern web features such as WebAuthn, making it ideal for verification flows.

• SFSafariViewController - Presents web content in a Safari-like interface that shares cookies and authentication state with Safari. This provides a familiar browsing experience while maintaining app context.

• WKWebView - Apple's modern web view component that embeds web content within your app. Similar to Android's WebView, WKWebView has limitations with certain web standards and can't access all browser features.

Not recommended

WKWebView doesn't support WebAuthn, which is required for AgeKeys. Users won't be able to create or use AgeKeys when widgets are embedded using WKWebView. For the best user experience with full AgeKeys support, use ASWebAuthenticationSession instead.

AgeKeys support limitations

AgeKeys are reusable, anonymous age-proof credentials based on FIDO and WebAuthn standards. They allow users to verify their age once and reuse that verification across different services without revealing personal information.

AgeKeys limitation

AgeKeys require WebAuthn support, which isn't available in Android WebView or iOS WKWebView. If you embed widgets by using these components, users won't see AgeKeys as an option during verification, and they can't create AgeKeys after successful verification.

To enable AgeKeys for your users, you must use one of these methods:

• Android: Chrome Custom Tabs
• iOS: ASWebAuthenticationSession or SFSafariViewController

Receiving verification results

Your mobile app needs to receive verification results after users complete the widget flow. There are two approaches, each with different availability:

For detailed information about analyzing verification results, including field presence rules, status types, and implementation guidance, see the Verification Event Contract.

Callback URL (universal method)

Recommended approach

The recommended approach for all implementation methods is to use a callback URL. When you call the API to generate a widget URL, include a redirectUrl parameter. After verification completes, the widget redirects to this URL with the results included as query parameters.

Advantages of callback URLs:

• Works with all implementation methods
• More reliable than DOM messages
• Standard deep linking pattern for mobile apps
• Results are always delivered, even if the app moves to the background

How callback URLs work

1. Register a deep link handler in your app (for example, myapp://verification-complete)
2. Include the deep link as redirectUrl when calling the API
3. The widget redirects to your deep link after completion
4. Your app handles the deep link and extracts the results

note

Redirects only occur when the widget URL is opened directly in a browser or web view, not when embedded in an iframe.

Callback URL parameters

When the widget redirects to your callback URL, it includes these query parameters:

• verificationId: The unique identifier for this verification
• result: Either PASS or FAIL

Example callback URL:

myapp://verification-complete?verificationId=7854909b-9124-4bed-9282-24b44c4a3c97&result=PASS

Implementing callback URLs

Include redirectUrl in the options object when calling AgeKit+ APIs. The URL can be:

• An HTTPS URL: https://example.com/verification-complete
• A custom deep link: myapp://verification-complete

For more details about the redirectUrl parameter, see the Waterfall flow guide.

DOM messages (WebView/WKWebView only)

When using Android WebView or iOS WKWebView, you can listen for JavaScript messages sent from the widget. This allows you to:

• Receive verification results in real-time
• Control when the web view closes
• Update your app's UI based on widget events

DOM messages are sent as postMessage events that you can intercept in your native code. For details about available events, see the DOM events overview.

Limited availability

DOM messages only work with WebView and WKWebView. They're not available with Chrome Custom Tabs, Trusted Web Activity, ASWebAuthenticationSession, or SFSafariViewController.

Method comparison

Method	Platform	AgeKeys	DOM Messages	Callback URL	Best For
WebView	Android	❌	✅	✅	Not recommended (no AgeKeys support)
Chrome Custom Tabs	Android	✅	❌	✅	Most use cases (recommended)
Trusted Web Activity	Android	✅	❌	✅	Not recommended (requires digital asset links)
WKWebView	iOS	❌	✅	✅	Not recommended (no AgeKeys support)
ASWebAuthenticationSession	iOS	✅	❌	✅	Most use cases (recommended)
SFSafariViewController	iOS	✅	❌	✅	Safari-like experience

Recommended implementation

Android: Chrome Custom Tabs

Use Chrome Custom Tabs with callback URLs for the best balance of features and user experience.

Why Chrome Custom Tabs:

• Full AgeKeys support via WebAuthn
• Access to all modern web features
• Seamless user experience with app branding
• Reliable callback mechanism
• Shares authentication state with Chrome

Implementation steps:

1. Register a deep link handler for your callback URL
2. Include redirectUrl in your API request
3. Open the widget URL using Chrome Custom Tabs
4. Handle the deep link callback with verification results

iOS: ASWebAuthenticationSession

Use ASWebAuthenticationSession with callback URLs for secure, native-feeling verification flows.

Why ASWebAuthenticationSession:

• Full AgeKeys support via WebAuthn
• Access to all modern web features
• System-managed security UI
• Shares cookies with Safari
• Reliable callback mechanism

Implementation steps:

1. Register a URL scheme handler for your callback URL
2. Include redirectUrl in your API request
3. Present the widget URL using ASWebAuthenticationSession
4. Handle the URL scheme callback with verification results

Complete implementation example

Here's a step-by-step example of implementing the recommended approach with complete code samples:

Step 1: Register deep link handler

iOS (Swift)

Register a URL scheme in Info.plist:

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>myapp</string>
        </array>
    </dict>
</array>

Android (Kotlin)

Add an intent filter in AndroidManifest.xml:

<activity
    android:name=".MainActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="myapp" android:host="verification-complete" />
    </intent-filter>
</activity>

Step 2: Generate widget URL with callback

iOS (Swift)

import Foundation

func generateWidgetUrl(completion: @escaping (URL?) -> Void) {
    guard let url = URL(string: "https://game-api.k-id.com/api/v1/age-verification/perform-access-age-verification") else {
        completion(nil)
        return
    }
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.setValue("Bearer YOUR_API_KEY", forHTTPHeaderField: "Authorization")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    
    let requestBody: [String: Any] = [
        "jurisdiction": "US-CA",
        "criteria": [
            "ageCategory": "DIGITAL_YOUTH_OR_ADULT"
        ],
        "options": [
            "redirectUrl": "myapp://verification-complete"
        ]
    ]
    
    guard let httpBody = try? JSONSerialization.data(withJSONObject: requestBody) else {
        completion(nil)
        return
    }
    request.httpBody = httpBody
    
    URLSession.shared.dataTask(with: request) { data, response, error in
        if let error = error {
            completion(nil)
            return
        }
        
        guard let httpResponse = response as? HTTPURLResponse,
              (200...299).contains(httpResponse.statusCode),
              let data = data,
              let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
              let widgetUrlString = json["url"] as? String,
              let widgetUrl = URL(string: widgetUrlString) else {
            completion(nil)
            return
        }
        completion(widgetUrl)
    }.resume()
}

Android (Kotlin)

import okhttp3.*
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.RequestBody.Companion.toRequestBody
import org.json.JSONObject
import java.io.IOException

fun generateWidgetUrl(callback: (String?) -> Unit) {
    val client = OkHttpClient()
    val mediaType = "application/json".toMediaType()
    
    val requestBody = JSONObject().apply {
        put("jurisdiction", "US-CA")
        put("criteria", JSONObject().apply {
            put("ageCategory", "DIGITAL_YOUTH_OR_ADULT")
        })
        put("options", JSONObject().apply {
            put("redirectUrl", "myapp://verification-complete")
        })
    }.toString().toRequestBody(mediaType)
    
    val request = Request.Builder()
        .url("https://game-api.k-id.com/api/v1/age-verification/perform-access-age-verification")
        .post(requestBody)
        .addHeader("Authorization", "Bearer YOUR_API_KEY")
        .addHeader("Content-Type", "application/json")
        .build()
    
    client.newCall(request).enqueue(object : Callback {
        override fun onResponse(call: Call, response: Response) {
            if (!response.isSuccessful) {
                callback(null)
                return
            }
            response.body?.use { body ->
                val responseBody = body.string()
                try {
                    val jsonResponse = JSONObject(responseBody)
                    val widgetUrl = jsonResponse.optString("url", null)
                    callback(widgetUrl)
                } catch (e: Exception) {
                    callback(null)
                }
            } ?: callback(null)
        }
        
        override fun onFailure(call: Call, e: IOException) {
            callback(null)
        }
    })
}

Step 3: Display the widget

iOS (Swift)

import AuthenticationServices

// Store session as a property to prevent deallocation
var authSession: ASWebAuthenticationSession?

func displayWidget(widgetUrl: URL) {
    authSession = ASWebAuthenticationSession(
        url: widgetUrl,
        callbackURLScheme: "myapp"
    ) { callbackURL, error in
        if let error = error {
            // Handle error (user cancelled, etc.)
            return
        }
        if let callbackURL = callbackURL {
            handleVerificationCallback(callbackURL)
        }
    }
    authSession?.presentationContextProvider = self
    authSession?.start()
}

Android (Kotlin)

import android.app.Activity
import android.net.Uri
import androidx.browser.customtabs.CustomTabsIntent

fun displayWidget(activity: Activity, widgetUrl: String?) {
    if (widgetUrl == null) {
        // Handle error: failed to generate widget URL
        return
    }
    val builder = CustomTabsIntent.Builder()
    val customTabsIntent = builder.build()
    val uri = Uri.parse(widgetUrl)
    customTabsIntent.launchUrl(activity, uri)
}

Step 4: Handle the callback

iOS (Swift)

func handleVerificationCallback(_ callbackURL: URL) {
    guard let components = URLComponents(url: callbackURL, resolvingAgainstBaseURL: false),
          let queryItems = components.queryItems else {
        return
    }
    
    let verificationId = queryItems.first(where: { $0.name == "verificationId" })?.value
    let result = queryItems.first(where: { $0.name == "result" })?.value
    
    // Update UI based on verification result
    if result == "PASS" {
        // Handle successful verification
    } else if result == "FAIL" {
        // Handle failed verification
    }
    
    // Optionally verify server-side
    if let verificationId = verificationId {
        verifyResultServerSide(verificationId: verificationId)
    }
}

Android (Kotlin)

import android.content.Intent
import android.net.Uri

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    setIntent(intent) // Important: ensure the new intent is used
    val data: Uri? = intent.data
    if (data != null && data.scheme == "myapp" && data.host == "verification-complete") {
        val verificationId = data.getQueryParameter("verificationId")
        val result = data.getQueryParameter("result")
        
        // Update UI based on verification result
        if (result == "PASS") {
            // Handle successful verification
        } else {
            // Handle failed verification
        }
        
        // Optionally verify server-side
        if (verificationId != null) {
            verifyResultServerSide(verificationId)
        }
    }
}

Best practice

Always verify verification results server-side using the /age-verification/get-status endpoint rather than relying solely on client-side data for security and data integrity. For detailed information about analyzing verification results, including field presence rules, status types, and implementation guidance, see the Verification Event Contract.