duckplayer-userscript-integration

DuckPlayer UserScript Integration Guide

Overview

DuckPlayer uses two primary UserScript components to bridge native iOS functionality with web content:

• DuckPlayerUserScriptYouTube: Manages communication with YouTube.com pages
• DuckPlayerUserScriptPlayer: Handles communication within the DuckPlayer web view

Architecture Overview

UserScript Communication Flow

// Communication flow:
// Web Content -> UserScript -> Native Handler -> ViewModel/Presenter
// Native UI -> Publisher -> UserScript -> Web Content

// ✅ CORRECT - Bidirectional communication pattern
final class DuckPlayerUserScriptYouTube: NSObject, Subfeature {
    // Incoming: Web -> Native
    func handler(forMethodNamed methodName: String) -> Subfeature.Handler? {
        switch methodName {
        case "onCurrentTimeStamp": return onCurrentTimeStamp
        case "onYoutubeError": return onYoutubeError
        default: return nil
        }
    }
    
    // Outgoing: Native -> Web
    private func pushToWebView(method: String, params: [String: String]) {
        broker?.push(method: method, params: params, for: self, into: webView)
    }
}

DuckPlayerUserScriptYouTube Integration

Component Responsibilities

Primary Role: Bridge between YouTube.com pages and native DuckPlayer controls

Key Responsibilities:

• Manages media control events (play/pause)
• Handles audio muting state
• Tracks video timestamp updates
• Responds to URL changes
• Manages script readiness state with event queuing
• Provides initial setup configuration

Event Queuing System

The UserScript implements an event queuing system to handle events before scripts are ready:

// ✅ CORRECT - Event queuing implementation
private enum QueuedEvent {
    case mediaControl(pause: Bool)
    case muteAudio(mute: Bool)
    case urlChanged(pageType: String)
}

private var otherEventsQueue: [QueuedEvent] = []
private var areScriptsReady = false

private func handleEvent(_ event: QueuedEvent) {
    switch event {
    case .urlChanged:
        // URL changes are always processed immediately
        processEvent(event)
    default:
        if areScriptsReady {
            processEvent(event)
        } else {
            // Queue events until scripts are ready
            otherEventsQueue.append(event)
        }
    }
}

// Process queued events when scripts become ready
func onDuckPlayerScriptsReady(params: Any, original: WKScriptMessage) -> Encodable? {
    areScriptsReady = true
    while !otherEventsQueue.isEmpty {
        let event = otherEventsQueue.removeFirst()
        processEvent(event)
    }
    return nil
}