Advanced Embedding

1.0 | Embed-Code Parameters

Most playout settings can be overridden by embed-code parameters. Moreover, a selected subset of settings can be made exclusively by using an embed-code parameter. They are:

dfp_adunit_l1Stringlevel-1 ad unit
dfp_adunit_l2Stringlevel-2 ad unit
dfp_adunit_l3Stringlevel-3 ad unit
dfp_adunit_l4Stringlevel-4 ad unit
dfp_adunit_l5Stringlevel-5 ad unit

1.1 | Embed-Code Parameters for Commercial Targeting

Often when targeting commercials, custom macros are needed. Since v5.35, the player implements this facility, substituting %%<key>%% with the value part of the macro_<key>=<value> embed-code parameter.

An example: If we have an ad tag url
booked in the preroll position of the default playout, then embedding the player with
results in the player requesting a preroll ad from

2.0 | Embedding

It is possible to place the player embed script at the bottom of the page and let place the player after a specific element on the page. For further information please refer to the Playout setting "Placement options".

To embed your video inline on Facebook, og-tags need to be added besides the player embed code on your website.

As of version 5.38, a dedicated embed code is available for YouTube hosted video. Upon request, designated playouts can be enabled for use with this embed code, which looks like: https://<publication><playout>/y/<youtubeId>.html. Mind the "/y/" where you would expect "/c/"

2.1 | Just-In-Time Embedding

You can also directly embed our Player API from http://[your publicationname]

Once the Player API is loaded it will register itself in the javascript variable “bluebillywig” on the document window and allow you to embed your media with pure javascript.


<script src=""></script>

<div id="myPlayerDiv"></div>


// Embed the player in the element "myPlayerDiv". Other playout settings (like width, height, autoPlay) can also be overruled by including them in the object passed as a second parameter:

var myPlayer = new bluebillywig.Player( "", {

        target : document.getElementById("myPlayerDiv"),

        autoPlay : "false"


// call the play method on the newly created player:;


Getters, such as getPlayoutData(), will not work before the player has triggered its ‘ready’ event. Other methods, such as play() and on() will, but are queued until the player is ready. Hence, you can — and should — use the on() method to bind to the ‘ready’ event and go from there.

2.2 | Embedding in-app

For embedding our player inside a native app (in-app) you’re advised to use our dedicated player SDK’s. If for some reason you can’t, and your iOS app uses a WkWebView, you can of course use a standard js embed code. There are some caveats, though. In the iOS app’s source code, you should include:

// target is higher than iOS 9.3.1
self.wkWebViewConfiguration.mediaTypesRequiringUserActionForPlayback = WKAudiovisualMediaTypeNone;
self.wkWebViewConfiguration.requiresUserActionForMediaPlayback = NO;

And ideally, implement a navigation policy:

class WKWebViewController: UIViewController, WKUIDelegate, WKNavigationDelegate {
// Creates the WKWebView
let webConfiguration = WKWebViewConfiguration()
webConfiguration.allowsInlineMediaPlayback = true
webConfiguration.mediaPlaybackRequiresUserAction = false
wkWebView = WKWebView(frame: .zero, configuration: webConfiguration)
wkWebView!.navigationDelegate = self
wkWebView!.uiDelegate = self
func webView(_ webView: WKWebView, createWebViewWith configuration: WKWebViewConfiguration, for navigationAction: WKNavigationAction, windowFeatures: WKWindowFeatures) -> WKWebView? {
    // Capture (clickthroughs) and redirect
    return nil

Once you have this in place, you should either use a dedicated playout for in-app, enabling ‘Force “can autoplay”‘, or embed with ?forceCanAutoPlay=true appended to the embed url.

In your Android app, it should also be possible to use a standard js embed code. Add cleartextTrafficPermitted=“true” to the app manifest file.

Was this article helpful?

Related Articles