@thestatic-tv/dcl-sdk

Connect your Decentraland scene to thestatic.tv - the decentralized streaming platform.

This SDK allows DCL scene builders to:

• Track visitors to your Decentraland scene
• Display the full thestatic.tv channel lineup in their scenes
• Track video watching metrics
• Enable likes/follows from within DCL
• Get referral credit for driving traffic to channels

Pricing

| Mode | Price | Features | |------|-------|----------| | Lite | $5/mo | Session/visitor tracking only | | Full | $10/mo | Guide UI, Chat UI, Heartbeat, Sessions, Interactions |

All keys use dcls_ prefix - the server determines your subscription level.

Free Trial: All new scene keys include a 7-day free trial!

Expiry Warnings: You'll receive dashboard notifications at 7, 3, and 1 days before your subscription expires.

Get your key from thestatic.tv/dashboard → DCL Scenes tab.

Coordinate Locking

When you create a scene key, you'll be asked to confirm your parcel coordinates. Once confirmed, coordinates are permanently locked to prevent key reuse across different scenes. This ensures analytics accurately reflect a single scene.

Key Rotation

If you need to rotate your API key (e.g., if compromised), you can do so from the dashboard without losing your subscription or analytics history. The old key is immediately invalidated.

Example Scene

Clone our starter scene to get started quickly:

git clone https://github.com/thestatic-tv/thestatic-dcl-starter.git
cd thestatic-dcl-starter
npm install
npm start

See the starter repo for a complete working scene.

Installation

npm install @thestatic-tv/dcl-sdk

Quick Start

1. Get your API key from thestatic.tv/dashboard (DCL Scenes tab)

2. Initialize the client in your scene:

import { StaticTVClient } from '@thestatic-tv/dcl-sdk'

const staticTV = new StaticTVClient({
  apiKey: 'dcls_your_api_key_here',
  debug: true // Enable for development
})

3. Fetch channels and display them:

// Get all channels
const channels = await staticTV.guide.getChannels()

// Get only live channels
const liveChannels = await staticTV.guide.getLiveChannels()

// Get a specific channel
const channel = await staticTV.guide.getChannel('channel-slug')

4. Track video watching:

// When user enters video viewing area
staticTV.heartbeat.startWatching('channel-slug')

// When user leaves video viewing area
staticTV.heartbeat.stopWatching()

5. Enable interactions:

// Like a channel (requires wallet connection)
await staticTV.interactions.like('channel-slug')

// Follow a channel
await staticTV.interactions.follow('channel-slug')

6. Cleanup before scene unload:

await staticTV.destroy()

Lite Mode (Visitor Tracking Only)

If you don't have a channel but want to track visitors to your scene:

1. Get a scene key from thestatic.tv/dashboard (DCL Scenes tab)

2. Initialize with your scene key:

import { StaticTVClient } from '@thestatic-tv/dcl-sdk'

const staticTV = new StaticTVClient({
  apiKey: 'dcls_your_scene_key_here'
})

// Session tracking starts automatically
// Visitors are tracked when they enter your scene

3. Check if running in lite mode:

if (staticTV.isLite) {
  console.log('Running in lite mode - session tracking only')
}

// guide, heartbeat, and interactions are null in lite mode
if (staticTV.guide) {
  const channels = await staticTV.guide.getChannels()
}

API Reference

StaticTVClient

Main client class for interacting with thestatic.tv.

Constructor Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Your API key (all keys use dcls_ prefix) | | autoStartSession | boolean | true | Automatically start session tracking | | sessionHeartbeatInterval | number | 30000 | Session heartbeat interval (ms) | | watchHeartbeatInterval | number | 60000 | Watch heartbeat interval (ms) | | debug | boolean | false | Enable debug logging |

Properties

| Property | Type | Description | |----------|------|-------------| | keyType | 'channel' \| 'scene' | The detected key type | | isLite | boolean | true if using a scene key (lite mode) | | guide | GuideModule \| null | Guide module (null in lite mode) | | session | SessionModule | Session module (always available) | | heartbeat | HeartbeatModule \| null | Heartbeat module (null in lite mode) | | interactions | InteractionsModule \| null | Interactions module (null in lite mode) | | guideUI | GuideUIModule \| null | Guide UI module (null in lite mode) | | chatUI | ChatUIModule \| null | Chat UI module (null in lite mode) |

Guide Module (Full Mode Only)

staticTV.guide.getChannels()       // Get all channels (cached 30s)
staticTV.guide.getLiveChannels()   // Get only live channels
staticTV.guide.getChannel(slug)    // Get a specific channel
staticTV.guide.getVods()           // Get VODs
staticTV.guide.clearCache()        // Clear the channel cache

Session Module

Session tracking starts automatically by default.

staticTV.session.startSession()    // Manually start session
staticTV.session.endSession()      // End session
staticTV.session.getSessionId()    // Get current session ID
staticTV.session.isSessionActive() // Check if session is active

Heartbeat Module (Full Mode Only)

Track video watching. Each heartbeat represents 1 minute watched.

staticTV.heartbeat.startWatching(channelSlug)  // Start tracking
staticTV.heartbeat.stopWatching()               // Stop tracking
staticTV.heartbeat.getCurrentChannel()          // Get currently watched channel
staticTV.heartbeat.isCurrentlyWatching()        // Check if watching

Interactions Module (Full Mode Only)

Like and follow channels. Requires wallet connection.

staticTV.interactions.like(channelSlug)   // Like a channel
staticTV.interactions.follow(channelSlug) // Follow a channel

Guide UI Module (Full Mode Only)

Built-in channel browser UI. You provide a callback to handle video selection.

// Configure in constructor
const staticTV = new StaticTVClient({
  apiKey: 'dcls_your_api_key',
  guideUI: {
    onVideoSelect: (video) => {
      // Handle video playback in your scene
      console.log('Playing:', video.name, video.src)
    }
  }
})

// Initialize the UI (call once after client is created)
await staticTV.guideUI.init()

// Show/hide the guide
staticTV.guideUI.show()
staticTV.guideUI.hide()
staticTV.guideUI.toggle()

// Check visibility
if (staticTV.guideUI.isVisible) { ... }

// Update "PLAYING" indicator
staticTV.guideUI.currentVideoId = 'video-id'

// Refresh data
await staticTV.guideUI.refresh()

Chat UI Module (Full Mode Only)

Real-time chat with Firebase authentication.

// Configure in constructor
const staticTV = new StaticTVClient({
  apiKey: 'dcls_your_api_key',
  chatUI: {
    position: 'right',  // 'left', 'center', or 'right'
    fontScale: 1.0
  }
})

// Initialize the chat (call once after client is created)
await staticTV.chatUI.init()

// Show/hide the chat
staticTV.chatUI.show()
staticTV.chatUI.hide()
staticTV.chatUI.toggle()

// Check visibility
if (staticTV.chatUI.isVisible) { ... }

// Get unread message count (for badge display)
const unread = staticTV.chatUI.unreadCount

// Switch channels
staticTV.chatUI.setChannel('channel-slug')

Rendering UI Components

The UI modules provide getComponent() methods that return React-ECS elements. Call these in your UI renderer:

import { ReactEcsRenderer } from '@dcl/sdk/react-ecs'

// In your scene setup
ReactEcsRenderer.setUiRenderer(() => {
  return (
    <>
      {/* Your other UI elements */}
      {staticTV.guideUI?.getComponent()}
      {staticTV.chatUI?.getComponent()}
    </>
  )
})

Metrics Attribution

This SDK implements dual attribution:

• Watched Channel: Gets view metrics (minutes watched, likes, follows)
• Scene Owner: Gets referral metrics (unique visitors, traffic driven)

Your channel (linked to your API key) receives credit for all traffic your scene drives to thestatic.tv channels.

Types

interface Channel {
  id: string
  slug: string
  name: string
  streamUrl: string
  isLive: boolean
  currentViewers: number
  poster: string | null
  logo: string | null
  description: string
}

interface Vod {
  id: string
  title: string
  url: string
  thumbnail: string | null
  channelId: string
}

Requirements

• Decentraland SDK 7.0.0 or higher
• API key from thestatic.tv

Support

• Documentation: thestatic.tv/info
• Issues: GitHub Issues
• Discord: thestatic.tv Discord

License

MIT