Spectatr Player SDK

A custom video player built with Stencil with Shaka Player integration, featuring PostHog analytics for comprehensive video engagement tracking.

Installation

npm install spectatr-player-sdk posthog-js

Features

• Video Player: Custom video player with Shaka Player integration
• Interactive Elements: Quiz and Poll components for engagement
• Analytics Integration: PostHog analytics for tracking video completion rates, quiz participation, and poll results
• Live Streaming: Support for live video streaming with DVR
• Quality Control: Adaptive bitrate streaming and manual quality selection
• Accessibility: Full keyboard navigation and screen reader support

Quick Start

Basic Usage

<video-player
  videoId="your-video-id"
  baseUrl="https://your-api.com"
  clientId="your-client-id"
  userId="user-123"
  autoPlay={false}
  captureReaction={true}
></video-player>

With Analytics (Automatically Enabled)

<video-player
  videoId="your-video-id"
  baseUrl="https://your-api.com"
  clientId="your-client-id"
  userId="user-123"
  autoPlay={false}
  captureReaction={true}
></video-player>

Note: Analytics is automatically enabled and will track:

• Video completion rates
• Quiz and poll participation
• Most watched videos

The userId is automatically retrieved from localStorage spactatr_user_id and PostHog is pre-configured.

Analytics Integration

The SDK includes PostHog analytics integration to track three key metrics:

1. Video Completion Rates

• Track completion percentage: See how much of each video users actually watch
• Watch duration: Monitor total time spent watching
• Drop-off analysis: Identify where users stop watching

2. Quiz & Poll Participation

• Quiz participation: Track when quizzes are shown and when users participate
• Poll participation: Track when polls are shown and when users vote
• Engagement rates: Monitor interaction with interactive content

3. Most Watched Videos

• Popularity tracking: Identify your most engaging content
• Watch statistics: Track total views and average completion rates
• Content performance: Compare video performance across your library

Analytics Events

The SDK automatically tracks the following events:

Video Completion Events

• video_completion - Tracks completion rate and watch duration when video ends

Quiz Participation Events

• quiz_participation - Tracks when quizzes are shown and when users participate

Poll Participation Events

• poll_participation - Tracks when polls are shown and when users vote

Most Watched Video Events

• most_watched_video - Tracks video popularity and watch statistics

Configuration

Analytics Configuration

interface AnalyticsConfig {
  posthogKey?: string;       // Optional: PostHog project key (pre-configured)
  posthogHost?: string;      // Optional: PostHog host (pre-configured)
  userId?: string;           // Optional: User identifier (auto-retrieved from localStorage)
  clientId?: string;         // Optional: Client identifier
  enabled?: boolean;         // Optional: Enable/disable analytics (defaults to true)
}

Video Player Props

interface VideoPlayerProps {
  videoId: string;                    // Required: Video identifier
  nextVideoId?: string;               // Optional: Next video for autoplay
  clientId: string;                   // Required: Client identifier
  userId: string;                     // Required: User identifier
  baseUrl: string;                    // Required: API base URL
  autoPlay?: boolean;                 // Optional: Autoplay video (defaults to false)
  captureReaction?: boolean;          // Optional: Enable like/dislike (defaults to false)
  setVideoId?: (id: string) => void;  // Optional: Video change callback
  // Analytics is automatically enabled - no configuration needed
}

PostHog Dashboard

With the analytics integration, you can create insights in your PostHog dashboard to analyze:

1. Video Performance: Completion rates, watch times, and engagement
2. Quiz Analytics: Participation rates and performance metrics
3. Poll Results: Voting patterns and engagement
4. User Behavior: Interaction patterns and preferences
5. Content Insights: Most popular videos and content performance

Privacy & Compliance

• Analytics are only tracked when enabled: true in the configuration
• User data is sent to PostHog according to their privacy policy
• Consider implementing user consent mechanisms for GDPR compliance
• The SDK respects user privacy and only tracks engagement metrics

Development

# Install dependencies
npm install

# Start development server
npm start

# Build for production
npm run build

# Run tests
npm test

License

MIT