Embed Player Timestamp Messaging API (DRAFT)
This document describes the request and response message format used to request the absolute timestamp of the content played by the Sporfie player embedded within an iframe using the postMessage() API.
Type Definitions
ts
type TimestampRequest = { version: 1; type: "sporfie:request-absolute-timestamp"; requestId?: string;};type TimestampResponse = { version: 1; type: "sporfie:absolute-timestamp"; requestId?: string; eventKey: string | null; absoluteTimestampMs: number | null; absoluteTimestampIso: string | null; error?: "not-ready" | "unresolved"; emittedAtMs: number;};Implementation Example
ts
const iframe = document.querySelector("iframe");const sporfieOrigin = "https://www.sporfie.com";// requestId is optional – set it if you have multiple embeds, repeated requests.const requestId = `request-${Date.now()}`;const request = { version: 1, type: "sporfie:request-absolute-timestamp", requestId,};iframe?.contentWindow?.postMessage(request, sporfieOrigin);window.addEventListener("message", (event) => { if (event.origin !== sporfieOrigin) return; const data = event.data as TimestampResponse; if (data.type !== "sporfie:absolute-timestamp") return; // Only check requestId if you sent one. if (request.requestId && data.requestId !== request.requestId) return; console.log("Timestamp ms:", data.absoluteTimestampMs); console.log("Timestamp ISO:", data.absoluteTimestampIso); console.log("Error:", data.error ?? null);});Implementation Notes
- Use an explicit Sporfie origin in
postMessage, never"*" - The iframe replies only to
event.sourceand usesevent.origin requestIdis optional, but useful for matching responseserror: "not-ready"means the player is not ready yeterror: "unresolved"means the player cannot safely map the current playback position to a real absolute time