Analytics metadata (design — not shipped)

Status: Design only (Phase 10.6). No breaking changes to event payloads in 0.3.x.

Current shipped events are minimal — mediaId and mediaType only. This page describes a proposed schema v2 for when analytics requirements are demonstrated in adoption audits.

Current schema (stable)

interface MediaViewEvent {
  mediaId: number;
  mediaType: "photo" | "video";
}

interface MediaDownloadEvent {
  mediaId: number;
  mediaType: "photo" | "video";
}

See Events for usage with trackView, trackDownload, and client.on().

Design questions (v2)

Field	Purpose	Recommendation
provider	Segment by Pexels vs Pixabay	Consider — apps often duplicate provider in listener today
query	Search context for view/download	Optional — app may know query from UI state; avoid stale query in event
photoFilters / videoFilters	Filter attribution	Defer — high cardinality; app responsibility
page	Pagination context	Defer — same as query
metadata?: Record<string, unknown>	App-defined bag	Preferred v2 path — additive, no provider-specific fields in core

Proposed v2 (additive)

interface MediaViewEventV2 {
  mediaId: number;
  mediaType: MediaType;
  provider?: string;
  metadata?: Record<string, unknown>;
}

interface MediaDownloadEventV2 {
  mediaId: number;
  mediaType: MediaType;
  provider?: string;
  metadata?: Record<string, unknown>;
}

trackView / trackDownload would accept optional metadata without requiring apps to fork listeners.

App forwarding pattern (today)

No SDK integration with GA4, Segment, etc. Apps attach listeners:

client.on("media:view", (event) => {
  analytics.track("media_view", {
    media_id: event.mediaId,
    media_type: event.mediaType,
    provider: activeProviderName, // app-supplied today
  });
});

Document this pattern in Events until v2 ships.

Promotion criteria (implement in core)

Ship v2 fields only when ≥2 of:

1. Dry-run / support feedback: listeners duplicate provider + context on every event
2. Third-party integration case study needs stable metadata bag
3. 1.0 readiness gate (§11 in PHASE-10-DESIGN) requires analytics decision closed with implementation

Default: defer implementation; design satisfies Phase 10.6.

Related

• Events — current API
• PHASE-10-DESIGN.md §10.6