Docs/SSAI/DRM Integration

DRM Integration

ApexMediation SSAI supports SSAI workflows with Widevine, FairPlay, and PlayReady when your streams are packaged in compatible formats (e.g., CMAF) and DRM licenses/policies are provided. Policies cover clear vs encrypted ads, key continuity, and mixed-scheme handling.

Supported DRM Systems

The DRMPolicyHandler manages content protection policies across all major DRM schemes.

DRM Scheme	Platforms	Container	Protocol
Widevine	Chrome, Firefox, Android, Android TV	CMAF	DASH, HLS
FairPlay	Safari, iOS, tvOS, macOS	CMAF, TS	HLS
PlayReady	Edge, Xbox, Windows, Smart TVs	CMAF	DASH, HLS
ClearKey	All modern browsers	CMAF	DASH, HLS

DRM Type Definition

// From DRMPolicyHandler.ts
export type DRMScheme = 'widevine' | 'fairplay' | 'playready' | 'clearkey' | 'none';

export interface DRMInfo {
  scheme: DRMScheme;
  keyId?: string;
  licenseUrl?: string;
  initData?: string;
  isEncrypted: boolean;
}

Policy Configuration

DRM policy is configurable per-integration to match your security requirements and content licensing terms.

Default Configuration

// DRMPolicyConfig with defaults
{
  allowClearAdsInEncryptedContent: true,   // Clear ads OK in DRM content
  allowEncryptedAdsInClearContent: false,  // No encrypted ads in clear
  requireSameScheme: false,                // Mix schemes allowed
  requireKeyContinuity: true,              // Key changes tracked
  supportedSchemes: ['widevine', 'fairplay', 'playready', 'clearkey', 'none'],
  defaultScheme: 'none'
}

allowClearAdsInEncryptedContent

Default: true

When enabled, clear (unencrypted) ads can be inserted into DRM-protected content. This is common for programmatic ads which typically don't require encryption.

allowEncryptedAdsInClearContent

Default: false

When disabled (default), encrypted ads cannot be inserted into clear content. This prevents DRM licensing issues with unprotected content.

requireSameScheme

Default: false

When enabled, encrypted content and ads must use the same DRM scheme (e.g., both Widevine). Useful for strict licensing requirements.

requireKeyContinuity

Default: true

When enabled, key changes at splice boundaries are tracked and warnings generated. Key ID changes may cause decryption delays on some players.

Compatibility Validation

Before inserting ads, the system validates DRM compatibility between content and ad creatives.

Validation Result Interface

export interface DRMValidationResult {
  valid: boolean;       // No errors found
  compatible: boolean;  // Can be stitched
  warnings: string[];   // Non-blocking issues
  errors: string[];     // Blocking issues
  recommendation?: string; // Suggested fix
}

Validation Checks

Scheme Support

Validates both content and ad DRM schemes are in supportedSchemes

Clear/Encrypted Mixing

Checks if clear ads in encrypted content (or vice versa) are allowed by policy

Scheme Matching

If requireSameScheme is enabled, verifies both use the same DRM

Key Continuity

Key continuity refers to maintaining consistent encryption keys across splice boundaries to prevent decryption stalls.

Key Continuity Check

// From DRMPolicyHandler.checkKeyContinuity()
checkKeyContinuity(contentDrm: DRMInfo, adDrm: DRMInfo): {
  continuous: boolean;
  issue?: string;
}

// Cases:
// 1. Both clear → continuous: true
// 2. Mixed clear/encrypted → continuous: false
//    issue: "Key continuity broken: clear/encrypted boundary"
// 3. Both encrypted, same keyId → continuous: true
// 4. Both encrypted, different keyId → continuous: false
//    issue: "Key ID change: abc123 → def456"

Key Rotation Handling

When key rotation is detected during ad insertion, the system tracks:

export interface KeyRotationInfo {
  currentKeyId: string;
  nextKeyId?: string;
  rotationTime?: number;  // Position in stream
  requiresRekey: boolean;
}

Best Practices

Use Clear Ads by Default

Most programmatic ad sources deliver clear (unencrypted) creatives. The default configuration allows this while still protecting premium content with DRM.

Match Container Formats

DRM only works with CMAF containers. If using DRM, ensure both content and ads are packaged as CMAF/fMP4. TS containers have limited DRM support (FairPlay only).

Monitor Key Changes

Enable key continuity tracking to identify ads that cause decryption delays. Key changes at splice boundaries may cause player stalls on some devices.

Test Multi-DRM Scenarios

If serving to multiple platforms, test DRM on each: Widevine for Chrome/Android, FairPlay for Safari/iOS/tvOS, PlayReady for Edge/Xbox.

Platform DRM Coverage

Platform	Widevine	FairPlay	PlayReady
Chrome/Firefox	✓	—	—
Safari/macOS	—	✓	—
iOS/tvOS	—	✓	—
Android/Android TV	✓	—	—
Edge/Windows	✓	—	✓
Xbox	—	—	✓
Fire TV	✓	—	✓
Roku	✓	—	✓