Delaying playback, modifying stream URLs and VAST adProvider

The Radioplayer web player offers an interface to modify the stream URLs and the VAST adProvider's tag property before playback. A popular use case is adding query parameters computed in other <script> tags.

Integrating into your web player

  1. Add the configuration parameters to the configuration object.

    1. playLocked: Enables play back locking
    2. numberOfUnlockers: How many unlocks are required for unlock to happen (defaults to 1 if unset)
    <div data-widget-radioplayer>
    <script type="application/json">
        {
            "...": "...",
            "playLocked": true,
            "numberOfUnlockers": 1
        }
    </script>
</div>

  2. Create a new JavaScript file based on the sample file modifying-urls.js. Adapt to your purposes as necessary.

  3. Add a <script> tag referencing your new file. It must appear a.) in the <head> of your index.html and b.) before the tags for the Radioplayer web player.
    After your change it should look like this:

    <!-- Must be before radioplayer.js! -->
<script
    type="application/javascript"
    src="modifying-urls.js"
></script>
<script type="module" src="/radioplayer.js"></script>
<script nomodule defer src="/radioplayer.legacy.js"></script>

  4. Test your console:

    1. Open it in a browser.
    2. Press play.
    3. Open the "Network" tab of your browser's developer tools
    4. Check if the HTTP request to your stream url contains the sample query param.
    5. Note that the sample file only modifies the first stream. If your web player is configured with multiple streams, you might not see a request to the modified stream URL.
    6. If your web player is configured with a VAST adProvider, a sample query param will be added to its tag url.

Guide for sample file

As showcased in the sample JavaScript file, playback locking and modifying playback configuration works like this:

  1. Your JS code registers an event handler (for event radioplayer_readyToReceiveEvents)
  2. The web player dispatches the event once it has loaded all available stream URLs and adProvider configurations.
  3. Your event handler is triggered.
  4. Your JS code
    1. assigns methods from global variable: StreamModifierUtils
    2. reads the original stream URLs and adProvider configuration from a global variable (radioplayer_playbackConfigurationFromConsole).
      This contains a PlaybackConfiguration
    3. modifies the stream URLs and VAST adProvider configuration using the example function.
    4. uses sendNewStreamsToConsole to inject the updated streams and adProvider configuration back into the Radioplayer console.
    5. uses unlockPlay to notify the Radioplayer console that the script has finished executing and that it is safe to play.
    6. if the user already clicked play, playback starts.

Alternative method of decorating the stream URL

An alternative method, which has been developed for publishers using Crossplan, can also be modified and used in conjunction with these methods. Following the instructions at Crossplan Integration, you will notice that rather than modifying the entire stream URL, you can call a method to pass in query parameters which will be decorated onto the stream before playback. This can be useful if you have one script which needs to make wholesale changes to the stream URL and additional scripts which might only need to append additional query parameters.

Note - If you do use this in conjunction with the other method detailed above, please do not forget to update the console configuration to ensure it is expecting the correct number of calls from the unlockPlay method by setting the numberOfUnlockers variable

Using playback locking without modifying stream URLs

Modifying stream URLs requires playback locking. However, playback locking can also be used on its own (without modifying stream URLs). If you only require playback locking, wait until the web player is ready to receive events (see above), then call the unlockPlay() function in the StreamModifierUtils

Usage in IFrame widget

Changing playback configuration and unlocking playback is also supported from within the IFrame widget.
The web player and the IFrame communicate via IFrameMessaging.

Integration steps

  1. Configure the web player properties playLocked, enableIframeMessaging and optionally numberOfUnlockers. 
    <div data-widget-radioplayer>
    <script type="application/json">
        {
            "...": "...",
            "playLocked": true,
            "numberOfUnlockers": 1,
            "widgets": ["IF"],
            "iframeSrc": "url-of-your-iframe.html",
            "enableIframeMessaging": true
        }
    </script>
</div>
  2. Create a new JavaScript file based on the IFrame sample file. Adapt to your purposes as necessary.
  3. Add the file via <script> to your IFrame HTML code.

Guide for IFrame sample file

As showcased in the sample IFrame sample file, playback locking and modifying playback configuration from within the IFrame works like this:

  1. Your JS code registers an event handler for events of type message. These are sent by the web player via window.postMessage().
  2. The web player repeatedly sends ReadyForUnlockPlayMessages once it has loaded all available stream URLs and adProvider configurations.
    As shown in the sample file: Please ensure that your custom code only executes when receiving the first message - if that is necessary for your use case.
  3. Your event handler is triggered.
  4. Your JS code in the IFrame
    1. reads the original stream URLs and adProvider configuration from the ReadyForUnlockPlayMessage's payload. This contains a PlaybackConfiguration.
    2. modifies the stream URLs and VAST adProvider configuration.
    3. creates a RequestPlaybackConfigurationUpdateMessage and sends it to the web player using window.postMessage().
    4. creates a RequestUnlockPlayMessage and sends it to the web player using window.postMessage().
    5. the web player updates its PlaybackConfiguration and unlocks playback.
    6. if the user already clicked play, playback starts.

Common pitfalls

  1. Modifying the AdsWizz, Triton or Google Tag Provider adProvider is not supported.
  2. The <script> tag of your JS code must appear a.) in the <head> of your index.html and b.) before the tags for the Radioplayer web player.
  3. Any URLs you modify must be valid URLs. Apply URL encoding if necessary.
  4. IFrame Messaging: The web player sends the ReadyForUnlockPlayMessage repeatedly, until playback is unlocked. Please ensure that your custom code only executes when receiving the first message - if that is necessary for your use case.

Technical details:

  1. The web player waits up to 7 seconds for the "unlock playback" event. After 7 seconds it automatically unlocks playback.
  2. If several <script>s modify the stream URLs, their order of execution must be managed by you. The web player does not offer any Tag Manager functionality.
  3. Data exchange between the web player and your JavaScript file is done via JS events (see sample file).