API documentation
      Back to home
      1. Help Center
      2. API documentation

      Integrating with A Million Ads

      Integrating with A Million Ads is simple as we follow standard HTTP, REST and VAST standards.

      VAST is wide spread amongst most ad tech providers and governs the kind of request that we take and the format of the response. The key method of interaction is via the VAST tag.

      The VAST Tag

      We provide the tag within our Studio ad designer tool when a script is ready to be published.

      Here is a sample tag that can be inserted in to the creative flight on an ad server / SSP / DSP (usually in the VAST redirect box):

      GET https://ads-eu.amillionads.com/go/wR3Ckk?source=ama&data.segment=${segment}&data.age=${ageband} Link

      This tag can be a HTTPS GET or POST.

      The unique code (wR3Ckk) is the reference to the script - in this case, it is a simple 15 second test message.

      The source is set to ama - this lets our system know who is requesting the ad, what format the data is being passed to us in and in what format we will return the response. This is all set up in a pre-defined config file called a parser.

      Data can be passed to trigger different elements in the script. This can be done as key=value in the query string, JSON formatted in the data field in the query string, or as XML or JSON in the POST body. In this example, the key value pairs data.segment and data.age are in the query string and the values are example macro codes that might trigger the DSP to populate some date into the tag on each request.

      The response output can be VAST (IAB standard XML), JSON, or even a 303 redirect to the file itself.  This tag responds with a VAST document containing the URL of the media asset (audio file encoded as required e.g. OGG), any impression, start and complete tags, third party trackers, and any associated companion image and companion click (not all are in this particular response).

      Companion images and clicks are supported and they can change dynamically in tandem with the audio - that is all set up in the Studio ad designer tool. We can also insert any number of tracking tags into the VAST response and, again, can fire different trackers for different creatives.

      Given the nature of dynamic creative, the response to each request for this tag could be different.

      Pre-Requisites

      For DSPs and ad servers to support dynamic functionality, several features are required:

      • VAST redirect support i.e. firing our tag, and then following the directions of the VAST response that we provide, most importantly where to find the media asset.

      • Client header information needs to be passed to us with each request. At minimum this is IP address, Device ID (on mobile) and User Agent of the listener's device. Normally this is passed (or proxied) in the HTTP headers, although can be appended to the tag using DSP-specific macros.

      • No caching of responses or tags. As this is a dynamic tag, all of the components of the response could be different for each request, so caching does not work.

      We know a test is working when the requests and impressions are spread across a region, indicating that real users are generating them.

      We know a test is working when the requests and impressions are spread across a region, indicating that real users are generating them.

      Testing

      When we integrate with a new DSP, SSP or ad server we run a series of tests to check that dynamic audio is fully operational:

      1. Environment: you call our dynamic creative server from a test stream and we respond with an audio ad that tells you everything we know about you and the call: time, location, device type, number of impressions. This primarily checks the the User's IP and User Agent are being correctly passed in the request header, and that impression pings are being fired.

      2. Parameter passing: you pass us a set of parameters that are available at your end via macros. Again in a test stream and we mirror them back to you in the audio e.g. Segment, Gender, Genre. This checks that macros can be created and populated in the tag.

      3. Scale: we create some filler audio that you place in remnant/unsold inventory on a live stream so that we can test that calls work at scale and that our numbers line up.

      We have different tags for each of these tests and can work with you at each stage to ratify the test and debug as appropriate. It is possible to roll all of the tests into one, depending on timing and how confident we are feeling - we've done a few of these now so we know pretty quickly when it is working and where the usual pitfalls are.