SpotServer API
Azure Spot Server API
The Azure Spot Server API allows you to take advantage of the dynamic ad injection services available through our web players and mobile apps. The API functions through sending specific text strings in the metadata embedded in the audio you send to the Azure ExStream servers.
Actions
There are two main calls you must make for the dynamic ad insertion to work; ‘Cue’ and ‘Trigger’. The cue action must be called before the trigger action. Although they theoretically could be triggered directly after each other, it is recommended to leave at least 5 seconds between the cue and trigger calls.
1. Spot Set Cue
The Cue command tells the Azure Ad Server to dynamically create a spot break based on the Delivery Rules you created in your Azure Ad Campaigns. It also specifies how long the web and app players should break away to dynamically inserted content.
To invoke this function, send the metadata below:
SPOTSET – action=cue&length={length}
{length} = length of spot set in seconds. i.e. a 2 minute break would be 120. Required.
2. Spot Set Break
The break command tells the web and app players to break away from your linear stream and begin playing the dynamic spot set that was grabbed by the player upon the cue command.
To invoke this function, send the metadata below:
SPOTSET – action=break
3. Spot Set Join (Optional)
The join command tells the web and app players to join back to your linear stream. Note that this command will only be processed if the spotset is currently playing ({length} > 0).
SPOTSET – action=join
Formatting
Most automation systems can be set to send metadata in {artist} – {title} format. As this is the format ExStream requires, we will assume you are sending your metadata in the {artist} – {title} format.
1. Control Cut Formatting
You must create a Cue cut for each spot set length you wish to trigger. For example, let’s create a cut that will trigger a 2-minute long spot set.
In the Artist field of the cut, enter: SPOTSET
In the Title field of the cut, enter: action=cue&length=120
This would create a cut that cues a 2-minute long spot set.
You only need to create one global break cut.
In the Artist field of the cut, enter: SPOTSET
In the Title field of the cut, enter: action=break
You only need to create one global join cut.
In the Artist field of the cut, enter: SPOTSET
In the Title field of the cut, enter: action=join
Other Notes
When creating dynamic spot breaks, it is recommended to still provide some sort of audio on your linear stream. If web and app campaigns are lighter than your terrestrial campaigns, the Azure Spot Server may not deliver a full break’s worth of spots (although this can be configured to always deliver full breaks in the Campaign Configurator.
For most stations, the linear content consists of the terrestrial spot break. For multi-endpoint clusters, or networks providing different linear spot content for multiple endpoints, an additional linear endpoint should be set up to feed the ExStream encoder with filler content.