Live AV Enrichment and ESS

Echo uses a combination of schedule data and timestamps from players to determine which individual programmes are being consumed and then automatically report on them. Echo uses the Echo Schedule Service (ESS) API to obtain schedule data for live media items.

Table of contents

1. Overview
2. Enabling ESS enrichment
3. Enrichment effects
4. ESS errors

Overview

The ESS API returns schedule data for a service or version identifier eg http://ess.api.bbci.co.uk/schedules?serviceId=bbc_one_london. Data is sourced from the Nitro API. A typical ESS reponse will cover a time period of approximately (now - 4 hours) to (now + 24 hours).

Echo will:

• make a single attempt to request data from the ESS API whenever you have ESS enabled and pass a live media object, with a serviceId, versionId or vpid to EchoClient.setMedia().
• attempt enrichment as soon as it has recieved a response from the ESS API and a non-zero timestamp from the player delegate.

Enrichment may not always succeed:

• some unexpected error eg http request timeout, unexpected status code
• data in the ESS schedule does not match up with the provided timestamp

Echo does not support fail-over (retry) attempts. Also see ESS errors

Enabling ESS enrichment

By default enrichment is disabled.

To use enrichment you need to do the following:

• set the USE_ESS config option to true
• provide a live timestamp through a PlayerDelegate
• provide a Media item with ‘live’ consumption mode
• provide a service ID, version ID or vpID to Echo’s Media object (vpID should be used when the type of ID you have is not known - if you are setting a vpID, don’t set the service or version ID)

  // Enable ESS enrichment in Echo config
  var conf = {};
  conf[ConfigKeys.USE_ESS] = true;

  var echo = new EchoClient('echo.test.page',   // App Name
    Enums.ApplicationType.WEB,              // App type
    conf);

  // pass in a reference to you player delegate implementation
  echo.setPlayerDelegate(playerDelegate);
  

  // Product delegate implementation
  import uk.co.bbc.echo.EchoConfigKeys;

  // In your app
  public class TestShellApplication extends Application {

   public long initApplication() {

   HashMap<String, String> config = new HashMap<String, String>();
   config.put(EchoConfigKeys.USE_ESS, true);

   EchoClient echo = new EchoClient(
            "MyApp",                    // App Name
            ApplicationType.MOBILE_APP, // App type
            "echo.android.test",        // App Countername
            getApplicationContext(),    // The Android Context of your Application
            config,                     // config options HashMap
            bbcUser,                    // BBCUser instance
            this                        // Application instance of your Application
    );

    // pass in a reference to you player delegate implementation
    echo.setPlayerDelegate(playerDelegate);
    }
  }
  

  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

   //Echo Config
   var config:Dictionary<EchoConfigKey, String> = [
        .echoTrace: "echo_demo_ios",
        .useESS: true
        // other config values here
    ]


   // Initialize Echo
   do {
      echo = try EchoClient(appName: "EchoDemoApp",
                              appType: .mobileApp,
                              startCounterName: "bbc.start.page",
                              config: config,
                              bbcUser: user)
   } catch {
      // Handle Echo config error
   }

   return true
   }
  

Enrichment effects

When enrichment is successful, you will see a stop event, followed by a play event with the new metadata included. This will include the content ID, duration, and potentially extra media theme properties.

For example, playing a stream on the Sounds website will result in an initial play with the following values (for more information on these values see here):

{
  p: brand=~series=~episode=~clip=~name=Steve Lamacq~type=~pList=bbc_6music::retType=stream~init=~adEna=0::mpN=smphtml5~mpV=2.24.0~tMod=~mlN=echo_js~mlV=12.3.0::bbc_6music
  m1: 0
}

And then it will stop and play again with the following:

{
  p: brand=~series=~episode=m00058k6~clip=~name=~type=~pList=bbc_6music::retType=stream~init=~adEna=0::mpN=smphtml5~mpV=2.24.0~tMod=~mlN=echo_js~mlV=12.3.0::m00058k5
  m1: 7200
}

Note the more specific information that is now available. In addition the duration of the programme will be sent instead of a zero value.

ESS errors

Unknown issues can arise when Echo attempts to enrich a live stream. Echo should gracefully handle the error failing silently. If you have debug mode turned on then Echo will also print the error to the console.

ess_error property

Echo will pass an ‘ess_error’ property describing the error. The value can be one of:

There is a 10 second timeout on the network request to the ESS service.

Note that due to limitations of ATI, this is no longer possible. Errors will be reported in future when ATI makes more custom variables available.