CDN Integration Guide
Cache policies, header requirements, and common misconfigurations to avoid when integrating ApexMediation SSAI with your CDN.
Critical: Session Manifests Must Not Be Cached
SSAI session manifests (for example /v1/session/{id}/master.m3u8) are per-viewer personalized. Caching them will serve wrong ads to viewers and break tracking. Configure your CDN to bypass cache (or use very low TTL) for session manifest paths.
What to Cache vs Never Cache
Safe to Cache
- ●
/segments/*.tsMedia segments are immutable. Cache 24h+
- ●
/segments/*.m4sDASH segments. Cache 24h+
- ●
/init/*.mp4Init segments. Cache 7d
- ●
/slate/*Slate assets. Cache 7d
- ●
/ads/{creative_id}/*Transcoded creatives. Cache 1h (with stale-while-revalidate)
Never Cache
- ●
/v1/session/*Session manifests. Personalized per viewer.
- ●
/v1/session/initSession creation endpoint. Unique per request.
- ●
/tracking/*Tracking pixels. Must hit origin.
- ●
/live/*.m3u8Live manifests. Updates every segment duration.
- ●
*?_sid=*Any URL with session ID param. Personalized.
Required Response Headers
The SSAI origin returns these headers. Your CDN must respect them:
| Resource Type | Cache-Control Header |
|---|---|
| Session manifests | no-store, no-cache, must-revalidate |
| Live manifests | max-age=1, stale-while-revalidate=2 |
| VOD manifests | max-age=300, stale-while-revalidate=60 |
| Media segments | max-age=86400, immutable |
| Init segments | max-age=604800, immutable |
| Tracking endpoints | no-store |
CORS Headers
For cross-origin playback, ensure your CDN forwards our CORS headers:
Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET, OPTIONS Access-Control-Allow-Headers: Range Access-Control-Expose-Headers: Content-Range, Content-Length
CDN Configuration (Vendor-Agnostic)
Use the equivalent features in your CDN and keep the principles the same: never cache personalized session manifests, respect origin cache headers, and avoid normalization that drops required query parameters.
Recommended rules
- Bypass caching:
/v1/session/*(session manifests + per-viewer endpoints) - Cache aggressively:
/segments/*,/init/*,/slate/* - Always origin:
/tracking/* - Preserve query strings: do not drop or normalize query params on
/v1/session/* - Respect origin headers: honor
Cache-Control,Vary, andContent-Encoding
Common Misconfigurations
❌ Caching based on file extension only
Problem: Caching all .m3u8 files ignores that session manifests are personalized.
Fix: Cache by path pattern, not extension. /v1/session/* → bypass,/vod/*.m3u8 → cache.
❌ Stripping query parameters
Problem: CDN removes ?_sid=... for cache normalization. Session ID lost.
Fix: Preserve query parameters for /v1/session/* paths. Only normalize segments.
❌ Ignoring Vary headers
Problem: CDN caches a single variant, ignoring Vary: Accept-Encoding.
Fix: Enable Vary header support and cache per-encoding (gzip, br, identity).
❌ Over-aggressive connection coalescing
Problem: HTTP/2 connection reuse serves wrong session's segments.
Fix: Disable connection coalescing for /v1/session/ paths or use separate hostnames.
⚠️ Short TTL on segments
Problem: 5-minute TTL on segments causes unnecessary origin load.
Fix: Segments are immutable once created. Set 24h+ TTL.
Verification Checklist
After CDN configuration, verify with these tests:
- 1
Session manifest bypass
curl -I 'https://cdn.example.com/v1/session/<session_id>/master.m3u8?token=<token>'Should show
X-Cache: MISSor no cache headers. - 2
Segment caching
curl -I https://cdn.example.com/segments/1234.ts # twiceSecond request should show
X-Cache: HIT. - 3
Tracking bypass
curl -I https://cdn.example.com/tracking/impression/xyzEvery request must reach origin (no cache).
- 4
Cross-origin playback
Test from a different origin domain, verify CORS headers present.
- 5
Load test with unique sessions
Simulate 100+ viewers with unique session IDs. Each should see personalized ads.