📚 Technical Documentation

🎯 System Overview

This application demonstrates a complete video streaming solution with ad insertion, real-time analytics, and interactive advertising. It combines multiple technologies to create a premium video experience similar to platforms like YouTube or Hulu.

Core Technologies

• HLS.js Streaming - JavaScript library for adaptive bitrate video playback
• AWS Elemental MediaTailor Ad Insertion - Server-side ad insertion service
• Datazoom Analytics - Video analytics platform and ad tracking
• Brightline Interactive Ads - SDK for interactive ads and overlays

🏗️ System Architecture

📦 Main Components

1. Video Players

The application includes two players to demonstrate different configurations:

Player	Features	Use Case
Video 1 - Standard	HLS.js only, no ads	Basic video playback
Video 2 - Premium	HLS.js + MediaTailor + Datazoom + Brightline	Full experience with ads and analytics

2. Event System

The on-screen event monitor displays real-time activity:

• SISTEMA - SDK initialization and page load
• DATAZOOM - Context creation and MediaTailor sessions
• MEDIATAILOR - Linear and non-linear ad detection
• BRIGHTLINE - Interactive overlay open/close
• EVENTO_ANUNCIO - Linear ad start/end

3. Countdown Timer

During linear ads (video ads), a countdown timer displays that:

• Calculates remaining time based on ad duration
• Updates every second
• Automatically hides when ad completes
• Disables video controls during ad playback

🔧 SDK Integration

HLS.js - Video Player

const hls = new Hls();
hls.loadSource(url);
hls.attachMedia(video);

HLS.js handles adaptive bitrate (ABR) video playback, automatically selecting the best quality based on bandwidth.

Datazoom - Analytics and MediaTailor

// Initialization
datazoom.init({ 
    configuration_id: "2477d200-37bd-4c42-910d-22389350c3bd"
});

// Create MediaTailor session
const session = await datazoom.mediatailor.createSession({
    sessionInitUrl: sessionInitPrefix
});

// Create analytics context
const context = datazoom.createContext(hls, {
    adapterOptions: { hlsClass: Hls }
});

// Attach MediaTailor session
context.attachMediaTailorSession(session);

Datazoom acts as a bridge between HLS.js and MediaTailor, capturing ad events and sending metrics.

Brightline - Interactive Ads

// Device configuration
BL.on_deviceInfo = function() {
    return {
        configId: "1018",
        applicationName: "Mercado Libre Video Player",
        // ... more config
    };
};

// Event callbacks
BL.on_BL_expanded = function() { video.pause(); };
BL.on_BL_collapsed = function() { video.play(); };

// Initialize SDK
BL.init();

// Open interactive ad
BL.openAd(url, videoId, true, 'mercado-libre', trackingData, duration);

Brightline handles interactive overlays that appear over the video without interrupting playback.

🎬 Ad Types

Linear Ads (Video Ads)

Video ads that interrupt main content:

• Events: AD_START and AD_END
• Behavior: Pauses main video, shows countdown timer
• Controls: Disabled during ad
• Duration: Defined in event.detail.adObject.adData.duration

Non-Linear Ads (Overlay Ads)

Interactive ads that overlay the video:

• Events: NONLINEAR_AD_START and NONLINEAR_AD_END
• Behavior: Video continues playing, overlay appears on top
• Interactivity: User can click to expand or close
• Creatives: Two variants (iPhone ad, Meli+ subscription)

Pause Ads

Ads that appear when user pauses the video:

• Trigger: Video pause event
• Implementation: Brightline overlay with pause message
• Dismissal: User clicks "Resume" to continue

📊 Tracking System

MediaTailor Tracking URLs

MediaTailor provides tracking URLs for each ad:

• Impression URLs: Fired when ad is displayed
• Click URLs: Fired when user clicks
• Complete URLs: Fired when ad finishes

These URLs are passed to Brightline in the trackingNodeStr parameter for automatic firing by the SDK.

Tracking Data Visualization

The "View MediaTailor Tracking URLs" button displays:

• Timestamp of last ad
• Ad type (LINEAR or NON_LINEAR)
• Ad duration
• Complete list of tracking URLs with event types

🎨 Styles and UI

Animated Header

The header title uses the slideInRight animation that slides text from the right on page load.

Player Boxes with Hover Effect

Video containers have an elevation effect on hover, creating a sense of depth.

Event Log Terminal-Style

The event monitor uses a terminal style with:

• Dark background (#1a1a2e)
• Cyan text (#0ff) to simulate a console
• Timestamps in gray
• Event types in blue
• Actions in yellow

Brightline Container

The #BL_Container has special z-index and pointer-events configuration to allow overlays to appear over video while permitting clicks.

⚙️ Key JavaScript Functions

initPlayer(videoId, url, enableDatazoom, sessionPrefix)

Main function that initializes a video player with optional ad insertion and analytics:

Basic HLS.js Setup

const video = document.getElementById(videoId);
const hls = new Hls();
hls.loadSource(url);
hls.attachMedia(video);

Creates an HLS.js instance and attaches it to the video element. HLS.js handles adaptive bitrate streaming automatically.

Pause Ad Implementation (Video 2 only)

let pauseAdShown = false;
video.addEventListener('pause', () => {
    if (pauseAdShown || video.ended || video.currentTime === 0) return;
    pauseAdShown = true;
    BL.openAd(pauseAdUrl, videoId, true, 'mercado-libre-pause', '{}', 0);
});

// Listen for resume message from ad creative
window.addEventListener('message', (event) => {
    if (event.data.action === 'resumeVideo') {
        video.play();
        pauseAdShown = false;
    }
});

Key Points:

• Flag prevents showing multiple pause ads in one session
• Checks prevent showing ad at video start or end
• Uses postMessage API for communication between ad iframe and parent page
• Ad creative must send {action: 'resumeVideo'} message to resume playback

MediaTailor Session Creation

const sessionConfig = { sessionInitUrl: sessionPrefix };
const session = await datazoom.mediatailor.createSession(sessionConfig);

// Create Datazoom analytics context
const context = datazoom.createContext(hls, {
    adapterOptions: { hlsClass: Hls }
});

// Link MediaTailor session to Datazoom for ad tracking
context.attachMediaTailorSession(session);

// Get personalized playback URL with ad markers
const playbackUrl = session.getPlaybackUrl();
hls.loadSource(playbackUrl);

What This Does:

• createSession() - Calls MediaTailor to create a personalized session with unique tracking URLs
• createContext() - Wraps HLS.js player with Datazoom analytics layer
• attachMediaTailorSession() - Enables Datazoom to detect ad markers in the manifest and fire events
• getPlaybackUrl() - Returns session-specific URL that includes ad insertion parameters

Linear Ad Event Handling

session.addEventListener(datazoom.mediatailor.SessionUiEvent.AD_START, event => {
    const duration = event.detail?.adObject?.adData?.duration || 0;
    
    // Start countdown timer
    if (duration > 0) {
        startAdCountdown(duration);
    }
    
    // Store tracking data for inspection
    const adObject = event.detail?.adObject;
    if (adObject) {
        latestTrackingData = {
            timestamp: new Date().toISOString(),
            type: 'LINEAR_AD',
            duration: duration,
            adData: adObject.adData,
            trackingEvents: adObject.adData?.trackingEvents || []
        };
    }
    
    // Disable controls during ad
    video.controls = false;
});

session.addEventListener(datazoom.mediatailor.SessionUiEvent.AD_END, event => {
    stopAdCountdown();
    video.controls = true;
});

Implementation Notes:

• event.detail.adObject contains all ad metadata from VAST/VMAP response
• Duration is in seconds, extracted from ad data
• Disabling controls prevents user from skipping the ad
• Tracking events array contains impression/click/complete URLs from ad server

Non-Linear Ad Event Handling

session.addEventListener(datazoom.mediatailor.SessionUiEvent.NONLINEAR_AD_START, event => {
    const adData = event.detail?.nonLinearAdsObject?.adData;
    if (!adData) return;
    
    const { nonLinearAdList, trackingEvents, duration } = adData;
    const nonLinearAd = nonLinearAdList[0];
    
    // Store tracking data
    latestTrackingData = {
        timestamp: new Date().toISOString(),
        type: 'NON_LINEAR_AD',
        duration: duration,
        trackingUrls: trackingEvents
    };
    
    // Select random creative
    const adCreatives = [
        'https://cdn.mediaplaypen.com/meli/ad/index.html',
        'https://cdn.mediaplaypen.com/meli/ad/index2.html'
    ];
    const overrideUrl = adCreatives[Math.floor(Math.random() * adCreatives.length)];
    
    // Prepare tracking for Brightline
    const trackingNodeStr = JSON.stringify({
        trackingEvents: {
            createView: trackingEvents
                .filter(e => e.eventType === 'impression')
                .map(e => e.beaconUrls)
                .flat()
        }
    });
    
    // Open Brightline overlay
    BL.openAd(
        overrideUrl,           // Creative URL
        videoId,               // Video element ID
        true,                  // Enable interactivity
        'mercado-libre',       // Campaign ID
        trackingNodeStr,       // Tracking URLs
        duration               // Auto-close duration
    );
    
    // Fallback timeout (in case Brightline doesn't auto-close)
    setTimeout(() => {
        BL.closeAd();
    }, (duration + 2) * 1000);
});

Critical Implementation Details:

• Why override the creative URL? MediaTailor provides a generic iframe URL, but we want custom Mercado Libre branded ads
• Tracking URL format: Brightline expects {trackingEvents: {createView: [url1, url2]}} structure
• Filter by eventType: Only pass impression URLs to Brightline; it fires them when ad is displayed
• Fallback timeout: Adds 2 seconds buffer to ensure ad closes even if Brightline SDK fails
• Why ignore NONLINEAR_AD_END? MediaTailor sometimes fires spurious END events; let Brightline handle timing

startAdCountdown(duration) / stopAdCountdown()

function startAdCountdown(duration) {
    const countdown = document.getElementById('adCountdown');
    const timeDisplay = document.getElementById('adCountdownTime');
    let timeLeft = Math.floor(duration);
    
    countdown.style.display = 'block';
    
    function updateCountdown() {
        const mins = Math.floor(timeLeft / 60);
        const secs = timeLeft % 60;
        timeDisplay.textContent = `${mins}:${secs.toString().padStart(2, '0')}`;
        
        if (timeLeft > 0) {
            timeLeft--;
        } else {
            stopAdCountdown();
        }
    }
    
    updateCountdown();
    adCountdownInterval = setInterval(updateCountdown, 1000);
}

function stopAdCountdown() {
    document.getElementById('adCountdown').style.display = 'none';
    if (adCountdownInterval) {
        clearInterval(adCountdownInterval);
        adCountdownInterval = null;
    }
}

How It Works:

• Converts seconds to MM:SS format with padStart(2, '0') for leading zeros
• Updates every 1000ms (1 second) using setInterval
• Automatically stops and hides when reaching 0
• Stores interval ID globally so it can be cleared from other functions

logEvent(type, message, action)

function logEvent(type, message, action) {
    const logContent = document.getElementById('event-log-content');
    const time = new Date().toLocaleTimeString('es-ES');
    const entry = document.createElement('div');
    entry.className = 'event-entry';
    entry.innerHTML = `
        <span class="event-time">[${time}]</span>
        <span class="event-type">${type}</span> 
        ${message}
        ${action ? `<span class="event-action">→ ${action}</span>` : ''}
    `;
    logContent.appendChild(entry);
    
    // Auto-scroll to bottom
    const logBox = logContent.parentElement;
    setTimeout(() => {
        logBox.scrollTop = logBox.scrollHeight;
    }, 0);
}

Usage Examples:

logEvent('SISTEMA', 'Page loaded', 'Initializing SDKs');
logEvent('DATAZOOM', 'MediaTailor session created', session.id);
logEvent('BRIGHTLINE', 'Opening interactive overlay', `Duration: ${duration}s`);

• Automatically adds timestamp in local time format
• CSS classes apply different colors based on event type
• setTimeout ensures scroll happens after DOM update

showTrackingUrls() / closeTrackingOverlay()

function showTrackingUrls() {
    const overlay = document.getElementById('trackingOverlay');
    const content = document.getElementById('trackingDetailsContent');
    
    if (latestTrackingData) {
        content.textContent = JSON.stringify(latestTrackingData, null, 2);
    } else {
        content.textContent = 'No tracking data available yet.';
    }
    
    overlay.style.display = 'flex';
}

function closeTrackingOverlay() {
    document.getElementById('trackingOverlay').style.display = 'none';
}

// Close on outside click
document.addEventListener('DOMContentLoaded', () => {
    const overlay = document.getElementById('trackingOverlay');
    overlay.addEventListener('click', (e) => {
        if (e.target === overlay) {
            closeTrackingOverlay();
        }
    });
});

Key Features:

• JSON.stringify(data, null, 2) - Pretty-prints JSON with 2-space indentation
• Modal uses display: flex for centering content
• Click on backdrop (not content) closes modal
• e.target === overlay ensures clicks on content don't close modal

🔄 Detailed Event Flow

Linear Ad (Video Ad)

1. MediaTailor inserts ad marker in HLS manifest
2. Datazoom detects marker and fires AD_START event
3. JavaScript captures event and extracts duration
4. Countdown timer starts with startAdCountdown(duration)
5. Video controls are disabled (video.controls = false)
6. Tracking URLs stored in latestTrackingData
7. Ad plays normally
8. On completion, MediaTailor fires AD_END event
9. Countdown stops with stopAdCountdown()
10. Controls re-enabled (video.controls = true)

Non-Linear Ad (Overlay Ad)

1. MediaTailor inserts non-linear ad marker in manifest
2. Datazoom detects marker and fires NONLINEAR_AD_START event
3. JavaScript extracts tracking URLs and duration
4. Randomly selects one of two Mercado Libre creatives
5. Prepares trackingNodeStr object with impression URLs
6. Calls BL.openAd() with creative URL and tracking data
7. Brightline displays overlay over video (video continues playing)
8. Fallback timeout set to close ad after duration + 2 seconds
9. Brightline automatically closes overlay when duration expires
10. NONLINEAR_AD_END event is ignored (to avoid premature closes)

Pause Ad

1. User pauses video (Video 2 only)
2. Event listener detects pause event
3. Verifies pause ad hasn't been shown in this session
4. Calls BL.openAd() with pause ad creative
5. User sees ad and can click "Resume"
6. Creative sends postMessage with action: 'resumeVideo'
7. JavaScript captures message and calls video.play()
8. Resets pauseAdShown flag

🐛 Error Handling and Edge Cases

Known Issues and Solutions

• Spurious NONLINEAR_AD_END events: MediaTailor sometimes fires premature END events. Solution: Ignore the event and let Brightline handle timing.
• Brightline doesn't auto-close: We set a fallback timeout of duration + 2 seconds to force closure.
• SDK not loaded: We verify typeof datazoom and typeof BL before initializing.
• Multiple pause ads: Use pauseAdShown flag to prevent showing ad repeatedly.

Logging and Debugging

The system includes extensive logging:

• console.log() for debugging in DevTools
• logEvent() to display events to user
• Tracking data stored in latestTrackingData for inspection

📈 Analytics and Dashboards

Grafana Dashboard

Visualizes real-time metrics:

• Number of plays
• Watch time
• Ad completion rate
• Playback errors

CloudWatch Dashboard

Monitors AWS infrastructure:

• MediaTailor requests
• Response latency
• Server errors
• Bandwidth usage

🚀 Configuration and Deployment

Configuration URLs

// Video 1 - Standard stream
const url1 = 'https://fcd796e21ed48a1abb4824e834c02632.p05sqb.channel-assembly.mediatailor.us-west-2.amazonaws.com/v1/channel/ModernAdsTestStream/index.m3u8';

// Video 2 - MediaTailor stream
const url2 = 'https://36820097a1284a0c9e2fa0344b33a58e.mediatailor.us-west-2.amazonaws.com/v1/master/bb5755666fd4f9f014f0687a72e9a3726a78e563/Meli/index.m3u8';

// Session init for Datazoom
const sessionInitPrefix = 'https://36820097a1284a0c9e2fa0344b33a58e.mediatailor.us-west-2.amazonaws.com/v1/session/bb5755666fd4f9f014f0687a72e9a3726a78e563/Meli/index.m3u8';

Configuration IDs

• Datazoom Configuration ID: 2477d200-37bd-4c42-910d-22389350c3bd
• Brightline Config ID: 1018

Ad Creatives

• iPhone Ad: https://cdn.mediaplaypen.com/meli/ad/index.html
• Meli+ Subscription: https://cdn.mediaplaypen.com/meli/ad/index2.html
• Pause Ad: https://cdn.mediaplaypen.com/meli/ad/index3.html

🔐 Security and Best Practices

• HTTPS: All resources loaded via HTTPS
• CSP: Consider implementing Content Security Policy
• Error Handling: Verify SDK availability before use
• Fallbacks: Safari support with native HLS
• Timeouts: Implement timeouts to prevent stuck ads

📝 Final Notes

This implementation demonstrates a complete integration of multiple video advertising technologies. Key points:

• Datazoom acts as the "glue" between HLS.js and MediaTailor
• Brightline handles all overlay interactivity
• MediaTailor inserts ads server-side in the stream
• Tracking is handled automatically by the SDKs
• The UI provides visual feedback for all events