Feature Plan: Landing Page Twitch Stream Embed

Summary

• Owner: Freddi
• Status: Discovery
• Target Release: 2025.11.x
• Backlog Entry: docs/agendas/uebliche.md → 📥 Inbox (Landing Page Twitch Stream Embed)

Goals

• Highlight live Übliche streams directly on the public landing page, prioritising higher-ranked players.
• Encourage visitors to join the community by showcasing real-time gameplay without leaving the site.
• Keep the embed performant and compliant with Twitch terms while adapting to cases with no eligible streams.

Scope

• Fetch live streamer data (linked accounts only) including rank, stream status, preview thumbnail, viewer count, and title.
• Define ranking rules (e.g., staff spotlight, rank tier priority, viewer count tie-breaks) and cache results for fast page loads.
• Render an embeddable player with stream carousel/tiles on the landing page, falling back to a call-to-action when no streams are live.
• Provide moderation controls to pin, hide, or reorder streams via dashboard settings.
• Out of scope: cosmetics unlocks, in-game live indicator (covered by Twitch Connect feature), and analytics beyond basic click tracking.

Implementation Outline

1. Data Source & Ranking
   • Reuse Twitch Connect link data to know which users can be surfaced.
   • Extend live status polling to include rank metadata and viewer counts; store a sorted shortlist in cache (Redis/Mongo).
   • Expose REST endpoint /api/public/streams returning ranked live streams with limited fields.
2. Moderation & Overrides
   • Add dashboard admin panel to flag streams as featured, hidden, or auto-ranked.
   • Persist override preferences with expiry (e.g., feature for 24h) to avoid stale pins.
3. Landing Page UI
   • Create LandingTwitchSection component showing primary embed (top-ranked) plus up to N secondary streams as thumbnails.
   • Implement responsive design: desktop embed, tablet static preview with “Watch on Twitch” CTA, mobile minimal card with external link.
   • Track click/impression metrics via existing analytics hooks.
4. Embed Compliance & Performance
   • Use Twitch Embed SDK with lazy loading (only instantiate player when section enters viewport).
   • Respect Twitch autoplay policies (muted start, user interaction for sound).
   • Ensure caching + CDN headers for preview thumbnails; throttle API refresh to avoid rate limits.
5. Fallback Experience
   • Display highlight reel or marketing block when no streams live; optionally show schedule teaser or Discord invite.

Dependencies

• Twitch Connect live status service delivering ranked stream data.
• Public API gateway to serve streams data with caching and rate limiting.
• Dashboard settings backend to manage overrides (likely services/gameserver/src/main/java/net/uebliche/platform/rest/editor/settings).
• Frontend public layout components for landing page integration.

Risks & Mitigations

• No live data available: Provide static fallback content and ensure page does not feel empty; consider showing latest VOD link.
• Performance impact: Lazy-load embed and fetch data asynchronously to keep initial load fast; cap refresh frequency client-side.
• Moderation needs: Streams could contain inappropriate content; add quick hide toggle plus auto-expiry on feature flags to reduce oversight burden.
• Privacy/consent: Only display streams from users who opted in via Twitch Connect; include terms acknowledgement during linking.

Validation Plan

• Unit tests for ranking logic and override precedence.
• Stage test hitting Twitch embed with sandbox streams; verify responsive layout and lazy loading.
• QA flows for override toggles, hidden streams, and fallback messaging.
• Monitoring on public API latency and Twitch embed error events post-launch.

Notes & Decisions

• 2025-11-05 – Prioritisation order: manual pin > rank tier (GM > Mod > Partner > Member > Unranked) > concurrent viewer count > recent activity timestamp.
• 2025-11-05 – Adopt 5-minute cache window for public endpoint to balance freshness and rate limit safety; dashboard override updates trigger cache invalidation.

References

• Twitch Embed docs: https://dev.twitch.tv/docs/embed
• Landing page module: app/dashboard/src/modules/public/pages/Landing.vue
• Settings service foundation: services/gameserver/src/main/java/net/uebliche/platform/rest/editor/settings