Echo JS Config Notes

Table of contents

1. General web tracking advice
2. Distribution and integration
   1. Static Releases
   2. Require JS and Orbit
   3. Webpack and browserify
   4. Direct from Git (No-NPM)
3. Overriding default property value on non-standard environments
4. Echo and Reverb/Orbit
5. Custom network function
6. JS Offline
7. Asynchronous processing

General web tracking advice

If you want to add analytics tracking to a website that makes use of the Orbit navigation you should look into using Reverb instead. Reverb is the successor to iStats and it is both more suited to web page tracking and simpler to use than Echo. If you are unable to use Reverb then Echo JS remains an option.

Distribution and integration

As of version 9.0.0 Echo JS is published using the UMD pattern. This means it can be loaded as an AMD module, Common JS module or as a global variable without a module loader.

Releases of Echo prior to version 9.0.0 were published as an AMD module only.

Static Releases

Each new JavaScript release is published as a static asset with CDN fronting.

You will need to use the correct URL pattern for the version you require.

(change the version number in the example to whatever the latest version is - you can find that by looking at the releases in the Github repo)

Require JS and Orbit

If you are using Echo within an Orbit page as an AMD module using the global ‘require’ you will need to add a path to Echo to the require config.

Please ensure you specify an Echo version in your path key e.g ‘echo-8.1.0’. It is possible that there is other code running in the page will using a different version of Echo. If both dependents define a path for ‘echo’ it could cause errors for one of them as they will recieve an unexpected version of the libary.

  // Add a key containing a version to the require paths config
  require.config({
    paths: {
        'echo-x.x.x' : 'https://mybbc-analytics.files.bbci.co.uk/echo-client-js/echo-x.x.x.min.js'
    }
  });

  require(['echo-x.x.x'], function(Echo){
    var echoClient = new Echo.EchoClient('MyApp', Echo.Enums.ApplicationType.WEB);
  });
  

Webpack and browserify

As of version 9.0.0 you can utilise Echo JS as an npm package which can be easily integrated into projects using tools such as webpack or browserify. Simply add a devDependency on Echo to your package.json and install via npm.

  # package.json
  {
   "name": "your-project",
   "devDependencies": {
    "echo-client-js": "git@github.com:bbc/echo-client-js.git"
   }
  }
  

And then require echo-client-js in your application javascript.

  var Echo = require('echo-client-js');
  var echoClient = new Echo.EchoClient('MyApp', Echo.Enums.ApplicationType.WEB);
  

Direct from Git (No-NPM)

Echo JS can be installed direct from GitHub using the syntax below (specify the version number required, see here for latest)

  npm install 'github:bbc/echo-client-js#semver:^X.X.X'
  // or
  npm install 'https://github.com/bbc/echo-client-js#semver:^X.X.X'
  

If you need to provide your GitHub Access Token for authentication then you can add the following as a dependency in your package.json

"dependencies": {
    "@bbc/echo-client-js": "git+https://[ACCESS TOKEN]:x-oauth-basic@github.com/bbc/echo-client-js.git",
    ...
}

Overriding default property value on non-standard environments

When using Echo in a non-standard JavaScript environment (i.e. not a typical JS web environment), an instance of the Environment class can be used to provide echo with values that it would otherwise expect to be available:

  /**
  * Create environment object so we can overwrite the
  * default (web) values
  */
  var env = new Environment()
    .setPlatformName(navigator.platform)
    .setPlatform('html', '5') //Runtime Environment and version
    .setDeviceName('device_name')
    .setScreenResolution('100x50')
    .setLanguage('en_GB')
    .setURL('http://mypage.now')
    .setReferrer('http://mylastpage.then')
    .setCharSet('UTF-8')
    .setTitle('My Page Title');

  /* Pass environment to EchoClient */
  var echo = new EchoClient('myapp',  // App Name
    Enums.ApplicationType.WEB,      // App type
    conf,
    env);
  

If you don’t need a custom environment, you can simply pass null.

Echo and Reverb/Orbit

If you are using Echo in an environment where Reverb is also present (eg as part of a media player on an Orbit web page), you should not send page views in Echo as Reverb will handle that for you. However, due to how ATI’s media package works, a page context needs to be provided for that to work. To do this, a producer and a counter name need to be provided before the media object, which will provide the same information without actually sending a duplicate page view.

Echo will grab this information from Orbit’s page object automatically, so it is quite likely this will be done for you, but if for any reason you need to override this you can provide these values explicitly to Echo using setProducer and setCounterName.

In a WebCore environment, we expect that the same page interface will be present so Echo can still get this information but this remains to be seen in practice. We’ll provide an update with more information about WebCore environments in due course…

Custom network function

By default, events to ATI will be delivered via a GET request in the form of an Image in the DOM. If you need to pass in a custom function for performing requests, one can be set on the Environment instance, this will then be used for all requests. Note: the function has no requirement to return the response from a GET request

  /**
  * Injecting custom HTTP GET/POST function
  */
  env.setHttpGet(function(url, onSuccess, onError) {
    var img = new Image();
    img.src = url;
    if(onSuccess){
        img.onload = onSuccess;
    }
    if(onError){
        img.onerror = onError;
    }
   });
  

JS Offline

Previously we released a separate version of Echo JS, which additionally included Comscore’s “OTT” offline caching functionality, for use in the iPlayer desktop app (which uses Electron/Chromium).

ATI’s core library includes this functionality so this is no longer necessary. If you need offline caching functionality, just use the standard version of Echo JS.

By default, Echo JS is configured with the 'never' cache option, meaning it is disabled. To enable caching in the JS client, set the 'ECHO_CACHE_MODE' config to 'offline' (events will be cached when there is no connection, and then transmitted automatically when the connection is restored), or 'all' (all events will be cached and will not be sent until the cache is explicitly flushed).

  conf[ConfigKeys.ECHO_CACHE_MODE] = "all";

  // Instantiate EchoClient
  var echo = new EchoClient('MyApp', Enums.ApplicationType.WEB, conf);

  // Events will be cached and not sent

  // flush the cache to send events
  echo.flushCache();
  

Asynchronous processing

It is possible with asychronous processing that you might call methods on Echo JS before it is ready to carry them out. This can result in some unexpected effects such as variables not being set correctly or even page views not being registered. Some limited mitigation for this is provided, in the shape of a callback function that can be supplied to the constructor. When Echo and its dependencies are finished setting up the callback will be fired and you can proceed safe in the knowledge that everything should work as expected.

  function callback() {
    // some code
  }

  var echoClient = new Echo.EchoClient('MyApp', Enums.ApplicationType.DESKTOP_APP, config, env, callback);