iOS Native Integration for Web Widgets

This guide explains how to host Sportradar web widgets inside a native iOS app using SwiftUI and WKWebView.

The integration pattern is reusable for all widgets. The only widget-specific parts are:

• the widget name passed to SIR("addWidget", ...)
• the props object passed to that widget
• optional loader options (language, theme, adapters, and similar)
• optional JavaScript callbacks such as onTrack or onItemClick

How you assemble the HTML page is up to you. Follow the Sportradar web / JavaScript widget documentation for the loader bootstrap and SIR("addWidget", ...) call. On iOS, host that page with SportradarWidgetView, which provides layout helpers and JavaScript communication.

#Intended Audience

This tutorial is for:

• iOS developers integrating Sportradar web widgets into SwiftUI apps
• Technical integrators who already understand basic widget integration
• Developers familiar with WKWebView, UIViewRepresentable, and JavaScript bridges

#Goals

By completing this tutorial, you will:

• Build a reusable SwiftUI host (SportradarWidgetView) around WKWebView
• Load Sportradar widget HTML with the correct base URL so assets resolve
• Bridge JavaScript → Swift messages (height and widget callbacks)
• Bridge Swift → JavaScript so you can call SIR(...) without reloading
• Size the web view to the widget’s content height inside native scroll containers
• Swap widgets by changing HTML / props only — not the native host

#Prerequisites

Before starting, ensure you have:

• Xcode with SwiftUI and WebKit available (system frameworks only — no third-party dependencies)
• Client ID — see how to obtain one
• Basic widget integration experience — completed the Getting Started guide
• Familiarity with the SIR API (addWidget, updateWidget, setClientTheme, and related methods)
• A valid match ID (or other entity ID) for testing

#Overview

The generic integration flow is:

#What to implement

The following pieces are enough for an iOS integration:

1. The shared SwiftUI host web view: SportradarWidgetView
2. Widget HTML built according to Sportradar’s JS documentation
3. Handling of onMessage for height and widget callbacks
4. Optionally onBridgeReady / SrJavaScriptBridge for Swift → JS

#Generic vs widget-specific

#Building SportradarWidgetView

The steps below walk through recreating SportradarWidgetView. Capabilities are added progressively. The full host reference shows the finished combined implementation. After the host is complete, Using SportradarWidgetView covers widget HTML and consumer usage.

SportradarWidgetView is a reusable SwiftUI wrapper around WKWebView that should:

• load your HTML with loadHTMLString and base URL https://widgets.sir.sportradar.com/ (so relative loader/assets resolve)
• register a script message handler (this guide uses the name srBridge; any name works if Swift and JS agree)
• inject a height ResizeObserver and report height through the same handler
• clear the web-view background so the SwiftUI background can show through
• optionally disable web-view scrolling for nested native scroll UIs
• expose SrJavaScriptBridge for evaluating JavaScript (Swift → JS)

#Step 1: Implement a basic WKWebView UIViewRepresentable wrapper

Start with a host that only loads HTML into a WKWebView. No bridges yet — just enough to render a Sportradar widget page inside SwiftUI.

import SwiftUI
import WebKit

struct SportradarWidgetView: UIViewRepresentable {
    let html: String
    let disableScroll: Bool

    private static let baseURL = URL

Key points:

• Use base URL https://widgets.sir.sportradar.com/ so relative loader/assets resolve correctly
• Clear opacity and backgrounds so the SwiftUI background can show through
• Reload HTML only when the string changes (avoids tearing down the loader on every SwiftUI update)
• Use disableScroll: true together with an explicit .frame(height:) when embedding inside NavigationStack, ScrollView, or List (see Step 6)

#Step 2: Implement a message handler and JS → Swift communication

Register a WKScriptMessageHandler so JavaScript can post into Swift via window.webkit.messageHandlers.srBridge. Swift forwards each payload to an onMessage closure.

This guide chooses:

• the handler name "srBridge"
• a type key on every payload, with branching on type in onMessage
• a single message handler for all JS → Swift traffic (height in Step 3; widget callbacks in Step 7), to keep the example small

Extend the Step 1 host:

1. Make Coordinator conform to WKScriptMessageHandler
2. Register the handler on WKUserContentController in makeUIView
3. Forward message.body to an onMessage closure
4. Remove the handler in dismantleUIView to avoid retain leaks

struct SportradarWidgetView: UIViewRepresentable 

After this step, JS can send messages into Swift. Widget callbacks still post through the same srBridge handler — see Step 7 for onTrack / onItemClick examples.

#Step 3: Add height reporting

Height reporting is necessary so SwiftUI can constrain the web view to the widget’s actual content height. Without a reported height, a WKWebView in a flexible layout typically expands to fill all available vertical space. That fights nested scroll UIs (ScrollView, List, NavigationStack): you usually want the web view sized to the widget and the native container to scroll.

With disableScroll: true and .frame(height: reportedHeight), the host matches the widget instead of stretching full-height. Consumer-side sizing is covered in Step 6.

WKWebView does not tell SwiftUI how tall its HTML content is, so the page must measure itself and send the value into Swift over srBridge. installHeightObserverJS is a JavaScript string you inject once via WKUserScript. It is not Sportradar-specific API — you write it. The script’s job is:

1. Pick a DOM element whose height represents the widget
2. Measure that element
3. postMessage the height through srBridge
4. Re-measure whenever the element resizes (widgets grow/shrink as they load or update)

This guide observes [data-sr-height-root] and falls back to document.body if that attribute is missing. Mark the mount in your widget HTML (see Step 5):

<div id="sr-widget" data-sr-height-root></div>

Keep the widget HTML minimal and let the shared iOS host inject the height observer.

#Building the script

Construct the script from small pieces:

1. Resolve the element

function heightRoot() {
    return document.querySelector("[data-sr-height-root]") || document.body;
}

2. Measure and post — read layout height and send a JSON-friendly payload Swift can parse (type: "height" so onMessage can branch like other messages):

function postHeight() {
    var el = heightRoot();
    var height = Math.ceil(el.getBoundingClientRect().height);
    if (height > 0 && window.webkit && window.webkit.messageHandlers.srBridge) {
        window.webkit.messageHandlers.

3. Observe changes — attach a ResizeObserver and post once immediately so Swift gets an initial height:

new ResizeObserver(postHeight).observe(heightRoot());
postHeight();

4. Wrap in an IIFE — keep locals off window:

(function() {
    // heightRoot, postHeight, ResizeObserver…
})();

#Assembled script

private static let installHeightObserverJS = """
(function() {
    function heightRoot() {
        return document.querySelector("[data-sr-height-root]") || document.body;
    }
    function postHeight() {
        var el = heightRoot();
        var height = Math.ceil(el.getBoundingClientRect().height);
        if (height > 0 && window.webkit && window.webkit.messageHandlers.srBridge) {
            window.webkit.messageHandlers.srBridge.postMessage({
                type: "height",
                height: height
            });
        }
    }
    new ResizeObserver(postHeight).observe(heightRoot());

Inject it at document end in makeUIView (alongside the message handler):

configuration.userContentController.addUserScript(
    WKUserScript(
        source: Self.installHeightObserverJS,
        injectionTime: .atDocumentEnd,
        forMainFrameOnly: true
    )
)

Posted payloads look like:

{ "type": "height", "height": 420 }

#Step 4: Implement Swift → JS via SrJavaScriptBridge

To call SIR(...) from Swift without rebuilding HTML, wrap WKWebView.evaluateJavaScript in a small bridge and hand it to the consumer once the web view exists.

final class SrJavaScriptBridge {
    weak var webView: WKWebView?

    func evaluate(_ javaScript: String, completion: ((Any?, Error?) -> Void)? = nil) {
        DispatchQueue.main.async {
            self.webView?.evaluateJavaScript(javaScript, completionHandler

Wire it into the host:

1. Keep a SrJavaScriptBridge on the coordinator
2. Set bridge.webView = webView in makeUIView
3. Expose onBridgeReady: ((SrJavaScriptBridge) -> Void)? and call it on the next main-queue turn (mutations during makeUIView are often dropped, so deferring lets @State assignment work)

var onBridgeReady: ((SrJavaScriptBridge) -> Void)?

// In Coordinator:
let bridge = SrJavaScriptBridge()

// In makeUIView, after creating the web view:
context.coordinator.bridge.webView = webView
let bridge = context.coordinator.bridge
DispatchQueue.main.async {
    onBridgeReady?(bridge)
}

#Finished host surface

When Steps 1–4 are combined, the surface looks like:

init(
    html: String,
    disableScroll: Bool = false,
    onMessage: ((Any) -> Void)? = nil,
    onBridgeReady: ((SrJavaScriptBridge) -> Void)? = nil
)

#Full host reference

#Using SportradarWidgetView

With the host in place, build widget HTML and wire it into your SwiftUI UI.

#Step 5: Build the widget HTML from the JS docs

Use Sportradar’s web widget documentation for:

• the widgetloader bootstrap for your client ID
• SIR("addWidget", selector, widgetName, props)
• any loader options and callbacks the widget requires

See Getting Started and the SIR API for the authoritative JavaScript patterns.

A minimal page shape:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <style>
        html, body { margin: 0; padding: 0; }

Notes for iOS hosting:

• Put data-sr-height-root on the element that should drive native auto-height (usually the mount div). Its height is reported (and updated) via onMessage. If omitted, height falls back to document.body.
• Keep page backgrounds transparent if you want the SwiftUI background to show through.
• Replace the example client ID with your assigned client ID in production.
• Keep the page markup minimal. The native host injects the shared height observer instead of making each widget page responsible for that logic.

#Step 6: Host the page in your SwiftUI UI

Pass the HTML into the finished SportradarWidgetView, size from reported height, and optionally keep the JS bridge:

@State private var widgetHeight: CGFloat = 1
@State private var jsBridge: SrJavaScriptBridge?

SportradarWidgetView(
    html: myWidgetHTML,
    disableScroll: true,
    onMessage: { message in
        if let height = contentHeight(from: message) {

Use disableScroll: true when the widget sits inside a native scroll container (NavigationStack, ScrollView, List).

Parse height updates from onMessage and apply .frame(height:):

private func contentHeight(from message: Any) -> CGFloat? {
    guard
        let dict = message as? [String: Any],
        dict["type"] as? String == "height",
        let number = dict["height"] as? NSNumber
    else { return

#Step 7: Bridge widget callbacks to Swift

When the JS docs say to attach callbacks such as onTrack or onItemClick, forward them into native code through the message handler you registered (this guide uses srBridge):

onTrack: function(eventName, eventData) {
    if (window.webkit && window.webkit.messageHandlers.srBridge) {
        window.webkit.messageHandlers.srBridge.postMessage({
            type: "onTrack",
            eventName: eventName,
            eventData: eventData
        }

Payloads must be JSON-serializable. For nested objects, stringify in JS:

onItemClick: function(target, data) {
    if (window.webkit && window.webkit.messageHandlers.srBridge) {
        window.webkit.messageHandlers.srBridge.postMessage({
            type: "onItemClick",
            target: String(target),
            data: JSON.

Handle those messages in the same onMessage closure used for height. Branch on type:

onMessage: { message in
    guard let dict = message as? [String: Any],
          let type = dict["type"] as? String else { return }
    switch type {
    case "onTrack":
        print("onTrack", dict["eventName"] ?? ""

This pattern stays the same for all widgets:

1. Implement the callback per the Sportradar JS docs
2. postMessage to your message handler (for example srBridge) with a type
3. Branch on type (or equivalent) in Swift

Only the callback name and remaining payload fields change per widget.

#Step 8: Call SIR(...) from Swift (optional)

Keep the HTML string stable and update via the bridge from onBridgeReady:

jsBridge?.evaluate("""
SIR("updateWidget", "#sr-widget", { matchId: \(matchID) });
""")

jsBridge?.evaluate("SIR(\"setClientTheme\", \"sportradardark\");")
// SIR("changeLanguage", "de")

#Example of a widget swap

Swapping widgets should not require changing SportradarWidgetView. Change only the HTML you pass in (and how you interpret onMessage).

The SwiftUI host, height observer, and bridge remain the same.

#Key takeaways

#Further reading

#Sportradar widget documentation

• Getting Started — loader bootstrap and addWidget
• Global SIR API — updateWidget, themes, language, and other methods
• Widget Tracking & Analytics Guide — onTrack and analytics patterns
• Integration Best Practices — production hardening
• FAQ — Client ID, widget names, and entity IDs

#Apple platform references

• WKWebView — hosting web content in native apps
• WKScriptMessageHandler — JS → native messaging
• UIViewRepresentable — embedding UIKit views in SwiftUI

import SwiftUI
import WebKit

/// Evaluates JavaScript in the widget web view (Swift → JS).
final class SrJavaScriptBridge {
    weak var webView: WKWebView?

    func evaluate(_ javaScript: String, completion: ((Any?, Error?) -> Void)? = nil) {
        DispatchQueue.main.async {
            self.webView?.evaluateJavaScript(javaScript, completionHandler: completion)
        }
    }
}

struct SportradarWidgetView: UIViewRepresentable {
    /// Handler name exposed to JS as `webkit.messageHandlers.srBridge`.
    static let messageHandlerName = "srBridge"

    /// Observes `[data-sr-height-root]` (falls back to `body`) and posts `{ type: "height", height }` via `srBridge`.
    private static let installHeightObserverJS = """
    (function() {
        function heightRoot() {
            return document.querySelector("[data-sr-height-root]") || document.body;
        }
        function postHeight() {
            var el = heightRoot();
            var height = Math.ceil(el.getBoundingClientRect().height);
            if (height > 0 && window.webkit && window.webkit.messageHandlers.srBridge) {
                window.webkit.messageHandlers.srBridge.postMessage({
                    type: "height",
                    height: height
                });
            }
        }
        new ResizeObserver(postHeight).observe(heightRoot());
        postHeight();
    })();
    """

    let html: String
    let disableScroll: Bool

    /// Called when JS posts via `webkit.messageHandlers.srBridge.postMessage(...)`.
    var onMessage: ((Any) -> Void)?

    /// Provides a bridge for evaluating JavaScript after the web view is created.
    var onBridgeReady: ((SrJavaScriptBridge) -> Void)?

    private static let baseURL = URL(string: "https://widgets.sir.sportradar.com/")!

    init(
        html: String,
        disableScroll: Bool = false,
        onMessage: ((Any) -> Void)? = nil,
        onBridgeReady: ((SrJavaScriptBridge) -> Void)? = nil
    ) {
        self.html = html
        self.disableScroll = disableScroll
        self.onMessage = onMessage
        self.onBridgeReady = onBridgeReady
    }

    func makeCoordinator() -> Coordinator {
        Coordinator(onMessage: onMessage)
    }

    func makeUIView(context: Context) -> WKWebView {
        let configuration = WKWebViewConfiguration()
        // JS → Swift: window.webkit.messageHandlers.srBridge.postMessage(payload)
        configuration.userContentController.add(
            context.coordinator,
            name: Self.messageHandlerName
        )
        configuration.userContentController.addUserScript(
            WKUserScript(
                source: Self.installHeightObserverJS,
                injectionTime: .atDocumentEnd,
                forMainFrameOnly: true
            )
        )

        let webView = WKWebView(frame: .zero, configuration: configuration)
        webView.isOpaque = false
        webView.backgroundColor = .clear
        webView.scrollView.backgroundColor = .clear
        webView.scrollView.isScrollEnabled = !disableScroll
        webView.scrollView.bounces = !disableScroll

        context.coordinator.bridge.webView = webView
        // Defer so consumers can safely assign @State (mutations during makeUIView are often dropped).
        let bridge = context.coordinator.bridge
        DispatchQueue.main.async {
            onBridgeReady?(bridge)
        }

        context.coordinator.load(html, into: webView)
        return webView
    }

    func updateUIView(_ webView: WKWebView, context: Context) {
        context.coordinator.onMessage = onMessage
        context.coordinator.load(html, into: webView)
    }

    static func dismantleUIView(_ uiView: WKWebView, coordinator: Coordinator) {
        uiView.configuration.userContentController
            .removeScriptMessageHandler(forName: messageHandlerName)
    }

    final class Coordinator: NSObject, WKScriptMessageHandler {
        let bridge = SrJavaScriptBridge()
        var onMessage: ((Any) -> Void)?
        private var loadedHTML: String?

        init(onMessage: ((Any) -> Void)?) {
            self.onMessage = onMessage
        }

        func load(_ html: String, into webView: WKWebView) {
            guard html != loadedHTML else { return }
            loadedHTML = html
            webView.loadHTMLString(html, baseURL: SportradarWidgetView.baseURL)
        }

        func userContentController(
            _ userContentController: WKUserContentController,
            didReceive message: WKScriptMessage
        ) {
            guard message.name == SportradarWidgetView.messageHandlerName else { return }
            onMessage?(message.body)
        }
    }
}