⚠️ Deprecation Notice ⚠️

This documentation is now deprecated along with the Forge-based Barlesque and ORB stack.

If you are working on a new BBC product you should almost certainly be using the new Navigation API (aka Orbit).

These pages will be left here for the lifetime of the Forge platform and are left for reference for legacy products, but no guarantee is made of their accuracy nor will any of the documented products be worked on.

Welcome

Using Cookies at the BBC

Cookies fall into four categories: performance (where the cookie directs a change in page behaviour without reference to the users's wishes e.g. ckpf_mandolin, used by the Mandolin MVT system); personalisation (where the cookie directs a change in page behaviour with reference to the users's wishes, e.g. ckps_language which is set when the user makes a language choice) ; advertising (used specifically in targeting advertising to a user, e.g. ckad_worldwide_optin); and strictly necessary (a rare category for cookies without which performance and UX would be degraded, e.g. ckns_policy which records the user's cookie preferences). As you will see from the examples, on the BBC site cookie names follow a simple convention to declare the category they are in.

The bbc_cookies JS library is supplied client-side to make it easy for you to set and read cookies in JavaScript in accordance with a user's preferences. To ensure that your product is compliant with EU cookie law: (1) follow the naming convention shown above so that your cookie is categorised correctly; and (2) always set and read cookies using the supplied bbc_cookies API rather than directly.

More detailed documentation is below, and should be read and followed.

Categories

From the 25th of May 2012, user-agents will be able to control cookies by opting out of any of these three categories of cookies.

  • Performance
  • Personalisation
  • Advertising

User Preferences

When a user-agent that has no cookie preference stored, visits the site a prompt will appear offering the user a chance to set their cookie preferences. If the user clicks "continue" or ignores the prompt and goes to another page, they will be opted into all cookie categories by default and will not see the prompt again.

The preferences of the user are stored as a policy that is followed by the BBCcookies library when enforcing EU regulations. Developers can read this policy or discover if their cookies are allowed or not by using the BBCcookies API.

Cookie Jars

In order to determine if a user-agent has opted out or into a specific cookie, it is necessary to determine which category of cookies that cookie falls into
– which cookie jar contains that cookie.

There are 5 possible jars:

Default Values (where yes means the user accepts those cookies):

  • Performance: yes
  • Personalisation: yes
  • Advertising: yes
  • Necessary: yes
  • Unknown: no

This is accomplished with a simple naming convention. By this convention your cookie must have a prefix that identifies its cookie jar. The following cookie prefixes are available:

  • Personalisation/Functional: ckps_
  • Performance/Analytics: ckpf_
  • Advertising: ckad_

For example:

ckps_homepage_region //personalisation cookie
ckad_worldwide_optin  //advertising cookie

Using BBCcookies API

Getting a cookie

To get document.cookie, while being sure the enforced policy is checked:

var cookies = bbccookies.get() ;

Setting a cookie

To set a cookie, while being sure the enforced policy is checked, use the example below. The function bbccookies.set() returns the value of document.cookie or null if the cookie is not allowed to be set:

var cookies = bbccookies.set( 'quizResult=pass;expires=expires=Thu, 12 Jul 2018 00:00:01 GMT') ;

Checking if a cookies are enabled

To check if a cookies are enabled by the client, the function bbccookies.cookiesEnabled returns a boolean based on whether cookies can be set:

var enabled = bbccookies.cookiesEnabled() ;

Checking if a cookie is allowed

To check if a cookie is allowed under the current policy. The function bbccookies.isAllowed returns a boolean based on whether the cookie will be allowed or not:

var allowed = bbccookies.isAllowed('myCookieName') ;

Getting the user-agent policy

To get an individual user-agent policy for a specific category ('ads', 'personalisation', 'performance'):

var policy = bbccookies.readPolicy(); //This is a read-only value
var adsPolicy = policy.ads; //also policy.personalisation, policy.performance

As a current business requirement, the policies are controlled on an opt-out basis rather than an opt-in. This means that the policy values are '111' by default.

If the user has decided to disable cookies, we do not alter any values as we assume policies are no longer required. With this in mind, we recommend wrapping the readPolicy() function inside a cookiesEnabled() to ensure you are getting the right information.

if (bbccookies.cookiesEnabled()) {
    if (bbccookies.readPolicy('ads')) {
        do_something();
    }
} else {
    do_something_else_without_policies();
}

API

Visit the API documentation to see information useful for writing code to interface with our library.

FAQ

Q: What happens if cookies or Javascript are disabled in the user's browser?
A: If the user's browser has cookies disabled or Javascript disabled, no prompt is shown, no cookies are deleted and no preference is set.