Getting Started

Table of contents

1. Integration
   1. Create an Instance of the Echo Client
   2. Application Type
      1. Changing the application type
2. Destination and Producer
3. Properties
4. Property Cleansing
   1. Property Keys
   2. Default cleansing
   3. Strict Cleansing
   4. Clean Counter Name
   5. Add/Remove persistent properties
5. Counter Names
   1. Counter Name Value
6. Application Events
   1. Page View
   2. User Action Events
7. HTTPS
   1. Echo in a web context
   2. Echo in a mobile context

Integration

Below is a quickstart guide to getting Echo up and running, through the use of examples.

For documentation on individual services see the links in the ‘What is Echo’ section above.

Please see the following platform specific pages for guidance on adding the Echo resources to your project:

• Android client notes
• iOS client notes
• Javascript client notes

Create an Instance of the Echo Client

  // Tell require where to find the echo module (where x.x.x is the latest version)
    require.config({ paths: {'echo' : 'https://mybbc-analytics.files.bbci.co.uk/echo-client-js/echo-x.x.x.min.js'} });

  require(['echo'], function(Echo){

   var Media = Echo.Media,             // Media class
              EchoClient = Echo.EchoClient,   // Echo Client class
              Enums = Echo.Enums,             // Enums
              ConfigKeys = Echo.ConfigKeys,   // Key names to use in config
              Environment = Echo.Environment; // Class to allow overriding default behaviour

   var conf = {};
   conf[ConfigKeys.DESTINATION] = Enums.Destinations.FOOD;

   var echo = new EchoClient(
                    "MyApp",                    // App Name
                    ApplicationType.WEB,        // App type
                    conf,                       // Optional config dictionary
                    env,                        // Optional Environment class
                    callback                    // Optional callback function
                  );

   // You can optionally set the version of your application:
   echo.setAppVersion('1.1.1');
  });
  

  import uk.co.bbc.echo.EchoClient;
  import uk.co.bbc.echo.EchoConfigKeys;
  import uk.co.bbc.echo.Media;
  import uk.co.bbc.echo.enumerations.MediaAvType;
  import uk.co.bbc.echo.enumerations.MediaForm;
  import uk.co.bbc.echo.enumerations.ApplicationType;
  import uk.co.bbc.echo.enumerations.MediaRetrievalType;
  import uk.co.bbc.echo.enumerations.MediaConsumptionMode;
  import uk.co.bbc.echo.enumerations.MediaScheduleMode;
  import uk.co.bbc.echo.enumerations.PIPsType;

  import android.app.Application;

  public class TestShellApplication extends Application {
   public void initialiseEcho(HashMap<String, String> config) {
    config.put(EchoConfigKeys.DESTINATION, Destination.FOOD.toString());

    EchoClient echo = new EchoClient(
                "MyApp",                    // App Name
                ApplicationType.MOBILE_APP, // App Type
                "echo.android.test",        // App start countername (no longer used for ATI)
                getApplicationContext(),    // The Android Context of your Application
                config,                     // config options HashMap
                bbcUser,                    // BBCUser instance
                this                        // Application instance of your Application
            );
        }
    }
  

  import Echo

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

   // Echo Config
   var config:Dictionary<EchoConfigKey, String> = [
            .destination: Destination.Food.toString()
    ]

   // BBCUser
   user = BBCUser(signedIn: true,
                       hashedID: hashedId,
                       tokenRefreshTimestamp: Date(timeIntervalSince1970: 1510156737)
    )

    // Initialize Echo
    do {
            echo = try EchoClient(appName: "EchoDemoApp",             // App name
                                  appType: .mobileApp,                // App type
                                  startCounterName: "bbc.start.page", // App start countername (no longer used for ATI)
                                  config: config,                     // Optional config dictionary
                                  bbcUser: user)                      // Optional BBCUser instance
        } catch {
            // Handle Echo config errors
        }

        return true
    }
  

Application Type

The type of application that will be reported (ApplicationType config option supplied in the creation of the Echo Client).

If you are unclear which of these values to use for your application contact the CCOG Measurement Technology team.

Changing the application type

Application Type can be changed during a single session after the creation of Echo Client.

    // Expects a value of type ApplicationType
    echo.setAppType(ApplicationType.MOBILE_APP);
  

    // Expects a value of type ApplicationType
    echo.setAppType(appType: .mobileApp)
  

Destination and Producer

The concepts of Destinations and Producers relate essentially to the product and the creator, respectively, of the content.

For more information on how to set these, and what to set them to, see the Destination section and the Producer section of the Reporting to ATI page.

Properties

Previously referred to as labels, you can set custom properties defined by your application. They are essentially key-value pairs that allow certain information to be recorded.

Properties set using Echo’s addProperties method (note that addLabels still works as an alias so there is no need to change your code) are persistent and therefore will apply to all subsequent events until they are removed using removeProperties (or removeLabels). Properties can also be set on specific events by passing them as a parameter to that method call; they will not then appear on subsequent events. See below for more on this.

Some properties are supported by ATI as “custom variables” and are reported as x1-x20. See the Site Variables section of the Reporting to ATI page for more information, and there are also confluence pages with more information on global custom variables and product-specific custom variables that may be of interest.

Other properties are supported but are retrieved in a different way that is outside of the scope of this document!

Property Cleansing

Echo applies some validation and cleansing to the two ‘key’ and ‘value’ components (eg key=value) of a property.

Property Keys

Valid characters are: 0-9a-z_

Echo performs the following:

• remove leading and trailing white space
• convert to lowercase
• replace any invalid characters with an underscore
• replace consecutive underscores with a single underscore
• remove any leading or trailing underscore

For example, given a property key of ! your property/key , Echo would convert this to your_property_key

Default cleansing

Default cleansing (may also be known as custom cleansing) is applied to any custom property that is set and to any property that falls outside one of the predefined categories (Strict, Countername and Event Master Brand).

All characters are allowed except pipes

Echo Performs the following

• remove leading and trailing white space
• convert any pipes to exclamation marks

Strict Cleansing

Strict cleansing is applied to the following properties only

• player_name
• bbc_site
• app_type
• app_name

Valid characters are: 0-9a-z-

Echo performs the following:

• convert to lowercase
• remove leading and trailing white space
• replace any invalid characters with a hyphen
• remove any leading or trailing hyphens

For example, given a property value of your-l@bel!-value, Echo would convert this to your-l-bel-value

Note: Event master brand is strictly cleansed, with the exception that underscores are used instead of hyphens

Clean Counter Name

Counter names (unique page or view names) are a special case and they are cleansed in the following way

Valid characters are: 0-9a-z.

Echo performs the following:

• convert to lowercase
• remove leading and trailing white space
• remove leading and trailing underscores
• replaces non a-z0-9 and non-dots, with underscore
• replaces sequences of multiple dots with a single one

Add/Remove persistent properties

The following code examples demonstrate how to add and remove persistent properties.

  echo.addProperty("property_1", "mypropertyvalue");
  echo.addProperties({"property_2": "mypropertyvalue2", "property_3": "mypropertyvalue3"});
  echo.removeProperties(["property_1", "property_3"]);
  

  echo.addProperty("property_1", "mypropertyvalue");

  HashMap<String, String> propertiesToAdd = new HashMap<String, String>();
  propertiesToAdd.put("property_2", "mypropertyvalue2");
  propertiesToAdd.put("property_3", "mypropertyvalue3");

  echo.addProperties(propertiesToAdd);

  HashSet<String> propertiesToRemove = new HashSet<String>();
  propertiesToRemove.add("property_1");
  propertiesToRemove.add("property_3");

  echo.removeProperties(propertiesToRemove);
  

  // Expects a dictionary
  echo.addProperties({"property_1": "mypropertyvalue1", "property_2": "mypropertyvalue2"})

   // Expects an array
   echo.removeProperties(["property_1", "property_2"])
  

Counter Names

Every “page” in a BBC application must have a counter name and no event can be sent until one has been set. There are 2 ways to set a counter name in Echo:

• viewEvent() - when you send a view event, you must specify a counter name as a view event implies that a new piece of content is being shown, hence a change in the counter name
• setCounterName() - This method should be called when a pageview has already been sent (by another instance of Echo on the same page for example), this then allows you to set the counter name without sending a view event

Counter Name Value

Valid characters are: 0-9a-z.

Echo performs the following:

• remove leading and trailing white space
• convert to lowercase
• replace any invalid characters with an underscore
• replace consecutive underscores with a single underscore
• append “.page” if not present at the end of the value

For example, given a counter name of “@ Some Page.Name/Item - “, Echo would convert this to “some_page.name_item.page”

Application Events

It is important to understand that accurately recorded view events are essential for correct reporting. Without them user analytics can not be properly calculated.

Page View

Every time a new piece of content is presented to the user your application should send a PageView event. In most circumstances, this should be sent before anything else. You must specify a countername for the page with this event. This countername is then associated with all subsequent events (until the next page view).

  // Send a page view event, with counter name and properties object
  echo.viewEvent("candy.kingdom.page", {my_test_property:"my_test_value"});
  

  // Send a page view event, with counter name and properties object
  HashMap<String, String> viewProperties = new HashMap<String, String>();
  viewProperties.put("my_test_property", "my_test_value");

  echo.viewEvent("candy.kingdom.page", viewProperties);
  

  // Send a page view event, with counter name and labels NSDictionary
  echo.viewEvent(counterName: "test.page", eventLabels: {"my_test_property": "my_test_value"})
  

User Action Events

An action (such as ‘click’, ‘submit’, ‘share’) MUST specify an action type and an action name. So in the below example, action type would be 'click' and action name would be 'SpecialButtonA'.

Echo’s userActionEvent method is still available, and will work without any changes, however, we recommend that you revise the properties you are setting, and follow the guidance here on what to set now, as there are restrictions on what will be shown in the reporting interface.

ATI’s “Publisher” ad-tracking feature is being used for this purpose. The property names to use are outlined below:

If you want to signify this event was prompted not by an explicit user action but by some background process or other application event, there is an additional property is_background which should be set to true. This determines whether they are considered to be “clicks” or “impressions” by ATI. This will default to false so that if you don’t specify, they will be considered “clicks”.

Example calls, and the resulting values sent to ATI, would therefore look like this:

  // Method signature
    echo.userActionEvent(actionType, actionName, eventProperties);

    // Send a user action event:
    echo.userActionEvent("click", "SpecialButtonA", {"container":"page", "personalisation":"personalisation values", "metadata":"metadata values", "source":"content ID", "result":"http://www.example.com"});

    // atc parameter sent:
    // "atc": "PUB-[page]-[ButtonA~click]-[personalisation values]-[metadata values]-[countername.page]-[user HID]-[content ID]-[http://www.example.com]"

    // Send a background event:
    echo.userActionEvent("impression", "ArticleA", {"is_background":"true", "container":"page", "personalisation":"personalisation values", "metadata":"metadata values", "source":"content ID", "result":"http://www.example.com"});

    // ati parameter sent:
    // "ati": "PUB-[page]-[ArticleA~impression]-[personalisation values]-[metadata values]-[countername.page]-[user HID]-[content ID]-[http://www.example.com]"
  

Note that if you are interested in click-through-rate, in order for that to be calculated, both the impression and the corresponding click need to have the same Container/Attribute values.

HTTPS

More information about configuring Echo with HTTP/HTTPS can be found in the advanced config section.

Echo in a web context

If you are using Echo on the web (for example in SMP) you shouldn’t need to worry about HTTPS; Echo will use the protocol of the page in which it is used. So if you’re on an HTTP page it will report over HTTP, and if you’re on an HTTPS page it will make all requests over HTTPS. This includes not only events sent to ATI or BARB, but also requests to ESS and any other connections to other services.

Echo JS can be forced to use HTTP by configuring the Config Option within Echo (ATI_FORCE_HTTP).

Echo in a mobile context

All recent versions of Echo iOS and Echo Android will use HTTPS by default.

If you’re developing a Windows Phone app using Echo JS, and you need Echo to report over HTTPS, you have a problem. Echo JS looks for the protocol of the containing web page. If there isn’t one, it will default to HTTP. If this is an issue for you then please alert the Analytics Services team by sending an email to the Analytics Services Team D-list, or asking in the #help-echo slack channel.