Service: Test Adserver - EyevinnOSC/community GitHub Wiki

Test Adserver

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.

What it can do

  • 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.

Creating an instance

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.

Options

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.

Custom ads with an MRSS feed

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.

Using the instance

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.

Typical SSAI flow

  1. The client reaches an ad break and asks the SSAI stitcher for ads.
  2. The stitcher sends a VAST request, with client data, to the Test Adserver.
  3. The Test Adserver selects ads and returns VAST with creatives, impression URLs, tracking URLs and metadata.
  4. The stitcher inserts the ads into the stream; the client fires the tracking URLs as playback progresses.
  5. The Test Adserver logs the events and exposes them through its API.

API endpoints

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).

Resources

⚠️ **GitHub.com Fallback** ⚠️