This guide will show you how to set up and use a Test Ad Server, which can be used in different testing contexts. For example to verify what query parameters are passed from the client device through the SSAI component as it stores all received query parameters for a request (session). Another example is to verify that client devices implement correct tracking as the VAST response contains tracking URLs back to the test ad server. All tracked events for a session are stored and can be obtained by the API. And can be used as an Ad server for testing server-side ad-insertion (SSAI) stitching as the VAST response always contains ads and creatives.

Providing this service is the open source project Test Ad Server and it is available as a service in Open Source Cloud.

The Eyevinn Test Adserver is the ultimate solution for testing client-side and server-side ad insertion (CSAI/SSAI) workflows. It provides developers and QA teams with a controlled environment to validate ad stitching, verify tracking implementations, and ensure seamless integration across platforms using VAST-based ad workflows. Rather than serving live production ads, this Test Adserver generates predictable, controlled VAST responses with mock creatives and tracking URLs, simulating the behavior of a real ad system.

The Test Adserver mocks the behavior of a real adserver by selecting and returning ads in a standardized VAST format, allowing developers to avoid unnecessary requests to production ad servers. Unlike real ad servers, which may return varying responses, the Test Adserver always delivers consistent and accurate ad responses, making it ideal for automated and repeatable testing.

A typical flow looks like this:

1. User watches a stream: The client reaches an ad break.
2. Client requests ads: The client asks the SSAI stitcher (e.g., Yospace or AWS MediaTailor) for the ads to be played.
3. VAST request: The stitcher sends a VAST request to the Test Adserver, including relevant client data.
4. Ad server decision: The Test Adserver uses the client data to select which ads should be played.
5. VAST response: The Test Adserver sends a VAST response. This response includes a list of creatives (ads) and their sequence, impression URL(s) to confirm ad delivery, tracking URLs to monitor how much of the ad the user viewed (e.g., start, firstQuartile, midpoint, thirdQuartile, complete), and metadata such as ad duration, media file type (e.g., MP4/H.264), and click-through URLs.
6. Stitcher inserts ads: The stitcher inserts the ads into the stream and sends tracking data to the client.
7. Tracking events: As the user watches the stream, the client triggers the tracking URLs at key moments (e.g., start, 25%, 50%, 75%, and complete).
8. Test Adserver logs events: The Test Adserver logs all tracking events and exposes them via its API.

• Always returns ads: Every request receives a valid VAST response with test ads, ensuring you're never blocked by campaign availability.
• Stores all received query parameters: This makes it easy to debug and validate the data being sent from the client through the SSAI layer to the ad server.
• Tracks all playback events: All impression pings and tracking events (start, quartile, complete) are stored and viewable via API, which is critical for validating client behavior.
• Simulates real-world ad flows: Enables safe testing without risking incorrect impression reporting.

This makes the Eyevinn Test Adserver an essential tool for validating ad-related integrations, ensuring accurate ad responses, and supporting SSAI and client-side ad tracking workflows.

This process allows teams to:

• Verify that the correct ads are selected.
• Ensure that tracking works as expected.
• Test the end-to-end integration in a controlled, testable environment.

• If you have not already done so, sign up for an OSC account.

Log on to Open Source Cloud and navigate to the "Test Adserver" page. Take help of the service search bar at the top if needed.

Enter the name of the Test Adserver, for example demo. When created, the Test Adserver is available at https://<tenant>-demo.eyevinn-test-adserver.auto.prod.osaas.io where <tenant> is the id of your tenant.

You also have the option to configure an MRSS_ORIGIN, this is used for deciding what ad creatives (mp4-files) the Test Adserver should select from when generating a VAST/VMAP response.

Before you enter the origin URL, you will need to create a test ad server MRSS file containing your desired ads, following the defined MRSS structure documented in Test AdServer Docs. Here is one example of a MRSS feed with a 15s and a 30s ad video.

<?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>

Once you have an MRSS file, you'll need to store it somewhere where it is accessible on the public internet, on github, on AWS S3, on Google Drive, or perhaps you could even store it with MinIO hosted on Open Source Cloud, check out this guide for som help with that MinIO in OSC Guide. Once stored and accessible, then you can create a Test AdServer and input the origin URL to your very own MRSS file. OK, so the origin URL goes in MRSS_ORIGIN, but what about the rest? The actual path to the MRSS file? The answer to those questions are found in the next step

Once you have created your Test Adserver, the interactive Swagger documentation of the Test Adserver API will be available at https://<tenant>-demo.eyevinn-test-adserver.auto.prod.osaas.io/api/docs/static/index.html. Useful for trying out API calls on the Test Adserver. To test these endpoints, you will need to retrieve your API key from OSC which is located in Settings > API, and then authorize in the Swagger documentation page.

Try out making a VAST request on the /vast endpoint. The required parameters are:

• dur
• uid

Optional: Is you want the Test Adserver to select ad videos from your custom MRSS feed, then put the path to your MRSS file in the coll queryparameter.

I.e. If your MRSS file is located at https://developer99.github.io/mrssstore/myads.mrss then you'd set MRSS_ORIGIN=https://developer99.github.io/mrssstore/ and &coll=myads

Execute the API call and you should receive something like this:

<?xml version="1.0" encoding="utf-8"?>
  <VAST version="4.0">
    <Ad id="POD_AD-ID_001" sequence="1">
      <InLine>
        <Impression id="IMPRESSION-ID_001"><![CDATA[http://tv4-prism.eyevinn-test-adserver.auto.prod.osaas.io/api/v1/sessions/51a93676-a194-47b6-bb9a-e4df29c1569a/tracking?adId=alvedon-10s_1&progress=vast]]></Impression>
        <AdSystem><![CDATA[Test Adserver]]></AdSystem>
        <AdTitle><![CDATA[Ad That Test-Adserver Wants Player To See #1]]></AdTitle>
        <Creatives>
          <Creative id="CRETIVE-ID_001" adId="alvedon-10s" sequence="1">
            <UniversalAdId idRegistry="test-ad-id.eyevinn" idValue="AAA%2FBBBB123%2F1"><![CDATA[AAA%2FBBBB123%2F1]]></UniversalAdId>
            <Linear>
              <TrackingEvents>
                <Tracking event="start"><![CDATA[http://tv4-prism.eyevinn-test-adserver.auto.prod.osaas.io/api/v1/sessions/51a93676-a194-47b6-bb9a-e4df29c1569a/tracking?adId=alvedon-10s_1&progress=0]]></Tracking>
                <Tracking event="firstQuartile"><![CDATA[http://tv4-prism.eyevinn-test-adserver.auto.prod.osaas.io/api/v1/sessions/51a93676-a194-47b6-bb9a-e4df29c1569a/tracking?adId=alvedon-10s_1&progress=25]]></Tracking>
                <Tracking event="midpoint"><![CDATA[http://tv4-prism.eyevinn-test-adserver.auto.prod.osaas.io/api/v1/sessions/51a93676-a194-47b6-bb9a-e4df29c1569a/tracking?adId=alvedon-10s_1&progress=50]]></Tracking>
                <Tracking event="thirdQuartile"><![CDATA[http://tv4-prism.eyevinn-test-adserver.auto.prod.osaas.io/api/v1/sessions/51a93676-a194-47b6-bb9a-e4df29c1569a/tracking?adId=alvedon-10s_1&progress=75]]></Tracking>
                <Tracking event="complete"><![CDATA[http://tv4-prism.eyevinn-test-adserver.auto.prod.osaas.io/api/v1/sessions/51a93676-a194-47b6-bb9a-e4df29c1569a/tracking?adId=alvedon-10s_1&progress=100]]></Tracking>
              </TrackingEvents>
              <VideoClicks>
                <ClickThrough id="Eyevinn Test AdServer"><![CDATA[https://github.com/Eyevinn/test-adserver]]></ClickThrough>
              </VideoClicks>
              <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>
    <Ad id="POD_AD-ID_002" sequence="2">
      <InLine>
        <Impression id="IMPRESSION-ID_002"><![CDATA[http://tv4-prism.eyevinn-test-adserver.auto.prod.osaas.io/api/v1/sessions/51a93676-a194-47b6-bb9a-e4df29c1569a/tracking?adId=bromwel-15s_2&progress=vast]]></Impression>
        <AdSystem><![CDATA[Test Adserver]]></AdSystem>
        <AdTitle><![CDATA[Ad That Test-Adserver Wants Player To See #2]]></AdTitle>
        <Creatives>
          <Creative id="CRETIVE-ID_002" adId="bromwel-15s" sequence="2">
            <UniversalAdId idRegistry="test-ad-id.eyevinn" idValue="AAA%2FDDDD123%2F2"><![CDATA[AAA%2FDDDD123%2F2]]></UniversalAdId>
            <Linear>
              <TrackingEvents>
                <Tracking event="start"><![CDATA[http://tv4-prism.eyevinn-test-adserver.auto.prod.osaas.io/api/v1/sessions/51a93676-a194-47b6-bb9a-e4df29c1569a/tracking?adId=bromwel-15s_2&progress=0]]></Tracking>
                <Tracking event="firstQuartile"><![CDATA[http://tv4-prism.eyevinn-test-adserver.auto.prod.osaas.io/api/v1/sessions/51a93676-a194-47b6-bb9a-e4df29c1569a/tracking?adId=bromwel-15s_2&progress=25]]></Tracking>
                <Tracking event="midpoint"><![CDATA[http://tv4-prism.eyevinn-test-adserver.auto.prod.osaas.io/api/v1/sessions/51a93676-a194-47b6-bb9a-e4df29c1569a/tracking?adId=bromwel-15s_2&progress=50]]></Tracking>
                <Tracking event="thirdQuartile"><![CDATA[http://tv4-prism.eyevinn-test-adserver.auto.prod.osaas.io/api/v1/sessions/51a93676-a194-47b6-bb9a-e4df29c1569a/tracking?adId=bromwel-15s_2&progress=75]]></Tracking>
                <Tracking event="complete"><![CDATA[http://tv4-prism.eyevinn-test-adserver.auto.prod.osaas.io/api/v1/sessions/51a93676-a194-47b6-bb9a-e4df29c1569a/tracking?adId=bromwel-15s_2&progress=100]]></Tracking>
              </TrackingEvents>
              <VideoClicks>
                <ClickThrough id="Eyevinn Test AdServer"><![CDATA[https://github.com/Eyevinn/test-adserver]]></ClickThrough>
              </VideoClicks>
              <Duration><![CDATA[00:00:15]]></Duration>
              <MediaFiles>
                <MediaFile width="718" height="404" codec="H.264" delivery="progressive" type="video/mp4" bitrate="1000"><![CDATA[https://testcontent.eyevinn.technology/ads/bromwel-15s.mp4]]></MediaFile>
              </MediaFiles>
            </Linear>
          </Creative>
        </Creatives>
      </InLine>
    </Ad>
  </VAST>

The VAST will include test creatives with mp4 files and customized tracking links, whose tracking is stored on the Test Adserver itself. Simply use the /sessions/{sessionId}/events endpoint to see what events from that VAST was fired.

Fetch all sessions stored in the Test Adserver.
Each session contains information about individual ad requests, including the request parameters and the corresponding VAST response. This is useful for reviewing what was sent and received during testing.

Retrieve a specific session by its session ID.
Provides detailed insight into a single test session, allowing developers to inspect what request was made and what VAST response was returned.

The response serves as proof that the client played the ad, including progression data (start, 25%, 50%, etc.). Useful for verifying that tracking events fired correctly.

Returns a list of tracking events that were triggered.
This shows which tracking URLs were actually hit by the client.

View the VAST XML response associated with a specific session.
This endpoint allows you to see exactly what ad response was returned for a given request.

Returns the VMAP document for a given session.
VMAP is another XML-based standard that can include multiple VAST responses for defining ad breaks in a stream.

Fetch all sessions tied to a specific user ID.
This helps identify sessions initiated by a particular user, assuming the user ID was provided in the original request.

Initiates a session by requesting a VAST response.
This is the primary entry point for triggering a test ad response in the standard VAST format.

Initiates a session by requesting a VAST response for pause ads, which are static image ads shown when content is paused. Unlike standard video ads, the pause ads from our test ad server use the sub-element instead of the sub-element in the VAST response.

Similar to the VAST endpoint, but returns a VMAP document.
Useful for testing multiple ad breaks and more complex ad schedules.

A generic ads endpoint that supports both VAST and VMAP formats.
You can specify the format using a query parameter, making it easy to mock different types of ad responses with the same parameters.

Endpoint that shows which HTTP requests the client is allowed to make.
Useful for testing and debugging the client’s ability to interact with the ad server.

To learn more about the capabilities of the Test Adserver try out the endpoints on the Swagger page, or take a moment and read the documentation on Github