Content Security Policy (CSP)

Content Security Policy (CSP) is an HTTP response header that tells the browser which resources (scripts, media, frames, images, and more) are allowed to load on a given page. It is a widely used security measure to prevent attacks such as Cross-Site Scripting (XSS) and data injection.

When a CSP is too restrictive, or does not account for the domains used by third-party embeds, the browser will silently block those resources. For embedded video players, this typically means the player does not load, video playback fails, or the player appears but features such as ads or subtitles do not work.

1.0 | Recognizing a CSP issue

When a browser blocks a resource due to CSP, it logs a violation message in the browser’s developer console (DevTools → Console tab). These messages follow the pattern:

Refused to load the script '[url]' because it violates the 
following Content Security Policy directive: [directive]

or

Refused to frame '[url]' because it violates the 
following Content Security Policy directive: "frame-src ..."

To check for CSP violations:

1. Open the page where the Blue Billywig player is embedded.
2. Open the browser’s developer tools.
3. Go to the Console tab.
4. Look for red error messages mentioning Content Security Policy or CSP.

Each message will tell you which directive is blocking which resource, which makes it straightforward to identify what needs to be added to your CSP configuration.

2.0 | Required CSP directives for Blue Billywig

The directives you need to update depend on your embed type. The following overview explains what each directive controls and what Blue Billywig content it covers.

2.1 | frame-src

Controls which URLs can be loaded in <iframe> elements. Blue Billywig’s standard embed uses an iframe, so your frame-src must include your publication’s domain.

Content-Security-Policy: 
   frame-src https://[your-publication].bluebillywig.com;

2.2 | script-src

Controls which JavaScript sources are permitted. If you are using the JavaScript or Launchpad embed method, the player scripts are loaded from your publication’s domain and potentially from CDN endpoints.

Content-Security-Policy: 
   script-src https://[your-publication].bluebillywig.com;

2.3 | media-src

Controls which URLs can be used as sources for <video> and <audio> elements. Video files and streams are typically served from Blue Billywig’s CDN infrastructure. If video fails to play even though the player loads, media-src is often the missing directive.

Content-Security-Policy: 
   media-src https://*.bluebillywig.com https://[your-cdn-domain];

2.4 | img-src

Controls which image sources are permitted. Thumbnails, poster images, and player UI icons are served from Blue Billywig’s CDN.

Content-Security-Policy: 
   img-src https://*.bluebillywig.com;

2.5 | connect-src

Controls which URLs the browser is allowed to connect to via fetch, XMLHttpRequest, and WebSocket. The player makes API calls to Blue Billywig’s services during initialization and playback.

Content-Security-Policy: 
   connect-src https://*.bluebillywig.com;

2.6 | Combined example (iframe embed)

Below is a starting-point template for a standard iframe embed. Replace [your-publication] with your actual publication name and extend each directive with any other domains your site already uses.

Content-Security-Policy:
  frame-src https://[your-publication].bluebillywig.com;
  script-src 'self' https://[your-publication].bluebillywig.com;
  media-src https://*.bluebillywig.com;
  img-src 'self' https://*.bluebillywig.com;
  connect-src 'self' https://*.bluebillywig.com;

3.0 | JavaScript / Launchpad embed

JavaScript / Launchpad embedded content involves more specific values to reconfigure your CSP response header, which makes it challenging to present a general template.

Unlike the iframe embed (which loads content in a self-contained frame), the JavaScript embed dynamically loads additional scripts, styles, and resources at runtime. This means the full list of required CSP sources can be broader and may also depend on features such as advertising or analytics that load their own external resources.

4.0 | Testing your CSP configuration

Blue Billywig provides a dedicated test page to validate your CSP settings with a Blue Billywig embed:

https://www.bluebillywig.tv/csp-test/index.php

Load this page in a browser where your CSP header is active, open the console, and check whether any CSP violations are reported. This helps you confirm whether your configuration allows the player to load correctly before testing on your production site.

If you want to evaluate your CSP without breaking your live site, consider using the Content-Security-Policy-Report-Only header first. This header causes the browser to log violations to the console without actually blocking any resources, making it safe to test and fine-tune your policy incrementally.