Loading remote configurations
This tutorial page shows some of the different options available to obtain a configuration that is stored remotely rather than embedded in the player page.
The topics that will be covered are:
-
Why use remote configuration
-
AMP’s Request Promise
-
XMLHttpRequest
-
Overriding Remote Configuration
Why use remote configuration
Let’s consider the next config.json file:
{
"plugins": {
"mrss": {
"resources": [
{"src": "#{paths.plugins}mrss/Mrss.js", "type": "text/javascript"}
]
},
"ima": {
"resources": [
{"src": "//imasdk.googleapis.com/js/sdkloader/ima3.js", "debug": "//imasdk.googleapis.com/js/sdkloader/ima3_debug.js", "type": "text/javascript"},
{"src": "#{paths.plugins}ima/Ima.min.js", "debug": "#{paths.plugins}ima/Ima.js", "type": "text/javascript"}
],
"adTagUrl": {
"params": {
"sz": "640x480",
"iu": "/124319096/external/ad_rule_samples",
"ciu_szs": "300x250",
"ad_rule": 1,
"impl": "s",
"gdfp_req": 1,
"env": "vp",
"output": "xml_vmap1",
"unviewed_position_start": 1,
"cust_params": {
"sample_ar": "premidpostpod"
},
"cmsid": 496,
"vid": "short_onecue",
"correlator": "#{now}"
}
},
"disableCompanionAds": false,
"ppid": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"vpaidMode": "enabled",
"disableFlashAds": true,
"companions": [{
"id": "companion",
"width": 300,
"height": 250
}]
}
}
}This is really similar to a real world configuration. As it can be seen in the previous example, as more plugins and other features are added, the complexity of the configrations object increases.
The main reason to use a remote configuration is to keep your HTML as clean and
tidy as posible. Having a remote configuration also gives the option to share the base configuration across several players and to update the player configuration without changing code in your website.
Loading a Remote AMP Configuration Using AMP’s Request Promise
AMP, as part of its utilities, exposes the requestJson function. This
function will retrieve a json file from a given url. As shown in the
example below, the returned json can be used directly as a config object
as long as the json file matches the akamai.amp.PlayerConfig
interface.
akamai.amp.AMP.requestJson("config.json")
.then(function (config) {
akamai.amp.AMP.create("amp", config);
})
.catch(function (error) {
console.log("Could not load player config", event.error);
});Loading a Remote AMP Configuration Using XMLHttpRequest
In some specific scenarios it might be usefull to have more control over
the request used to obtain the remote configuration and the way the
responses are handled for those requests. This can be done using
XMLHttpRequest. As an example, imagine that the config.json is behind
some basic authentication.
var xhr = new XMLHttpRequest();
xhr.open("GET", "config.json");
xhr.onload = function (event) {
var config = JSON.parse(xhr.responseText);
akamai.amp.AMP.create("amp", config);
};
xhr.onerror = function (event) {
console.log("Could not load player config", event.error);
};Overriding Remote Configuration
As mentioned before in this tutorial page, one of the mayor benefits of using remote configuration files is the option of sharing complex configuration across several players, this improves the maintainability of the code and quality of the final product. Nevertheless, in some scenarios is also necesary to be able to override the remote shared configuration. This can be achieved by modifying the obtained config object attributes. In the next example the stream is changed by setting an appropiate akamai.amp.Media object.
akamai.amp.AMP.requestJson("config.json")
.then(function (config) {
// override page specific values
config.media = {
src: "http://projects.mediadev.edgesuite.net/customers/akamai/video/VfE.mp4",
type: "video/mp4"
};
akamai.amp.AMP.create("amp", config);
})
.catch(function (error) {
console.log("Could not load player config", event.error);
});