Service: Test Adserver - EyevinnOSC/community GitHub Wiki
Eyevinn Test Adserver (serviceId eyevinn-test-adserver) is an open source ad server for testing client-side and server-side ad insertion (CSAI/SSAI) workflows. Instead of serving live ads it returns predictable VAST/VMAP responses with mock creatives and tracking URLs, so developers and QA teams can validate ad stitching and tracking. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance. Source: Eyevinn/test-adserver.
- Always return a valid VAST response with test ads, so tests are never blocked by campaign availability.
- Store all query parameters received for a request (session), to debug what a client device sends through the SSAI component.
- Store all impression pings and tracking events (start, firstQuartile, midpoint, thirdQuartile, complete) per session and expose them through an API, to verify client tracking.
- Act as the ad server when testing SSAI stitching (for example with Yospace or AWS MediaTailor), returning VAST, VMAP and pause-ad responses.
- Select creatives from a custom MRSS feed instead of the default test ads.
Test Adserver has no dependencies on other OSC services. Create the instance with create-service-instance using serviceId: "eyevinn-test-adserver". The instance name must be alphanumeric and at most 20 characters.
{ "name": "demo" }Wait with wait-for-service-ready or get-instance-status, then read the URL with describe-service-instance. The instance is available at https://<tenant>-demo.eyevinn-test-adserver.auto.prod-se.osaas.io, where <tenant> is your tenant id.
| Option | Required | Type | Meaning |
|---|---|---|---|
| name | Yes | string | Name of the instance. Letters, digits and underscore only; on OSC at most 20 characters. |
MRSS origin (upstream environment variable MRSS_ORIGIN) |
No | string | Base URL (origin) of the MRSS feeds the server selects ad creatives (mp4 files) from when generating VAST/VMAP. Without it the default ads are used. The feed is fetched from ${MRSS_ORIGIN}${coll}.mrss, where coll is the coll query parameter of the request (or, if absent, the host name of the request). Run get-service-schema for eyevinn-test-adserver to get the exact option name in the OSC catalog; it was not available when this page was revised. |
Neither option is a secret.
Create an MRSS file listing your ads (structure documented in the Test AdServer README) and host it at a publicly reachable URL, for example on GitHub Pages, AWS S3, or a MinIO bucket on OSC. Example feed with a 15s and a 30s ad:
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
<title>Open Source Cloud Test Ads</title>
<id>osc-test-ads</id>
<updated>2025-11-24T19:00:00Z</updated>
<entry>
<id>volvo-15s</id>
<universalId>OSC001</universalId>
<link>https://testcontent.eyevinn.technology/ads/volvo-15s.mp4</link>
<duration>00:00:15</duration>
<bitrate>10041</bitrate>
<width>1920</width>
<height>1080</height>
<codec>H.264</codec>
</entry>
<entry>
<id>eyevinn-stswe-30s</id>
<universalId>EYEVINN001</universalId>
<link>https://testcontent.eyevinn.technology/ads/stswe-ad-30sec.mp4</link>
<duration>00:00:30</duration>
<bitrate>10041</bitrate>
<width>1920</width>
<height>1080</height>
<codec>H.264</codec>
</entry>
</feed>If the file is at https://developer99.github.io/mrssstore/myads.mrss, set the MRSS origin to https://developer99.github.io/mrssstore/ and add &coll=myads to the VAST/VMAP request.
Interactive Swagger documentation is at https://<tenant>-demo.eyevinn-test-adserver.auto.prod-se.osaas.io/api/docs/static/index.html. To try endpoints there, authorize with your OSC API key (personal access token).
Request a VAST response from /api/v1/vast. Required parameters: dur and uid. Optional: coll to pick a custom MRSS file. The response contains ads in sequence, each with an impression URL, tracking URLs (start, firstQuartile, midpoint, thirdQuartile, complete), a click-through URL, duration and media file metadata. Abbreviated example:
<VAST version="4.0">
<Ad id="POD_AD-ID_001" sequence="1">
<InLine>
<Impression id="IMPRESSION-ID_001"><![CDATA[https://<instance-url>/api/v1/sessions/<sessionId>/tracking?adId=alvedon-10s_1&progress=vast]]></Impression>
<AdSystem><![CDATA[Test Adserver]]></AdSystem>
<Creatives>
<Creative id="CRETIVE-ID_001" adId="alvedon-10s" sequence="1">
<Linear>
<TrackingEvents>
<Tracking event="start"><![CDATA[https://<instance-url>/api/v1/sessions/<sessionId>/tracking?adId=alvedon-10s_1&progress=0]]></Tracking>
<Tracking event="complete"><![CDATA[https://<instance-url>/api/v1/sessions/<sessionId>/tracking?adId=alvedon-10s_1&progress=100]]></Tracking>
</TrackingEvents>
<Duration><![CDATA[00:00:10]]></Duration>
<MediaFiles>
<MediaFile width="718" height="404" codec="H.264" delivery="progressive" type="video/mp4" bitrate="1300"><![CDATA[https://testcontent.eyevinn.technology/ads/alvedon-10s.mp4]]></MediaFile>
</MediaFiles>
</Linear>
</Creative>
</Creatives>
</InLine>
</Ad>
</VAST>Tracking is stored on the Test Adserver itself; use /api/v1/sessions/{sessionId}/events to see which events from the VAST were fired.
- The client reaches an ad break and asks the SSAI stitcher for ads.
- The stitcher sends a VAST request, with client data, to the Test Adserver.
- The Test Adserver selects ads and returns VAST with creatives, impression URLs, tracking URLs and metadata.
- The stitcher inserts the ads into the stream; the client fires the tracking URLs as playback progresses.
- The Test Adserver logs the events and exposes them through its API.
| Endpoint | Purpose |
|---|---|
GET /api/v1/sessions |
List all stored sessions, with request parameters and the VAST response. |
GET /api/v1/sessions/{sessionId} |
One session by id. |
GET /api/v1/sessions/{sessionId}/tracking |
Tracking endpoint that serves as proof the client played the ad, with progression data (start, 25%, 50%, ...). |
GET /api/v1/sessions/{sessionId}/events |
List of tracking events that were triggered (tracking URLs actually hit by the client). |
GET /api/v1/sessions/{sessionId}/vast |
The VAST XML returned for the session. |
GET /api/v1/sessions/{sessionId}/vmap |
The VMAP document for the session. VMAP defines ad breaks and can include several VAST responses. |
GET /api/v1/users/{userId} |
All sessions for a user id, if a user id was given in the request. |
GET /api/v1/vast |
Start a session by requesting a VAST response. |
GET /api/v1/vmap |
Start a session by requesting a VMAP document, for multiple ad breaks and complex schedules. |
GET /api/v1/pause-ad |
Start a session by requesting a VAST for pause ads, static image ads shown when content is paused. These use <NonLinearAds> instead of <Linear>. |
GET /api/v1/ads |
Generic endpoint supporting VAST and VMAP, chosen with a query parameter. |
OPTIONS /* |
Shows which HTTP methods the client may use. |
For a visual way to browse sessions see Test Adserver UI (ablindberg-adserver-frontend, option name only).