Redirect Notice

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:

{
  "pid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "plugins": {
    "mediaanalytics": {
      "resources": [
        {"src": "#{paths.plugins}mediaanalytics/Mediaanalytics.js", "type": "text/javascript"},
        {"src": "//79423.analytics.edgekey.net/ma_library/javascript/javascript_malibrary.js", "type": "text/javascript"}
      ],
      "plugin": {
        "swf": "//79423.analytics.edgesuite.net/csma/plugin/csma.swf"
      },
      "config": "//ma188-r.analytics.edgesuite.net/config/beacon-2114.xml",
      "iplookup": false,
      "dimensions": {
        "title": "#{media.title}",
        "playerId": "AMP"
      }
    },
    "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", "async": true},
        {"src": "#{paths.plugins}ima/Ima.min.js", "debug": "#{paths.plugins}ima/Ima.js", "type": "text/javascript", "async": true}
      ],
      "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. So, 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.setRequestHeader('Authorization', 'Basic TXlVc2VyO015UGFzc3dvcmQ=' );
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);
  });