Permutive Developer Hub

Welcome to the Permutive developer hub. You'll find comprehensive guides and documentation to help you start working with Permutive as quickly as possible, as well as support if you get stuck. Let's jump right in!

API Reference

Brightcove

Overview

Brightcove is a high-performance, cross-platform HTML5-first video player that loads quickly, delivers high-quality video across desktop and mobile platforms.

Permutive is able to integrate with Brightcove to enable video event collection, so you can better understand what video content your users are engaging with. All data collected can be used for analytics or segmentation.

Supported Platforms

This integration enables the following functionality:

Function
Web
AMP
FIA
iOS App
Android App

Event collection

X

X

Targeting

X

X

X

This integration includes support for event collection. Our platform support matrix shows which events we are able to collect:

Event Type
Description
Web
AMP
FIA
iOS App
Android App

VideoPlay

Tracks when a video is played.

X

X

VideoProgress

Tracks progress of a video play, as a percentage watched.

X

X

VideoEvent

Tracks additional events emitted by the player, such as when a user enters full screen mode.

X

X

VideoAdPlay

Tracks when a video ad is played.

X

X

VideoAdProgress

Tracks progress of a video ad play, as a percentage watched.

X

X

VideoAdEvent

Tracks additional events emitted by the player whilst an ad is being watched, such as when a user enters full screen mode.

X

X

VideoAdClick

Tracks when a user clicks on a video ad.

X

X

Setup

On Web, we have built a plugin that can be bundled into the Brightcove player. Once included in your player, our plugin will pick up all supported event types and send them into our API.

Prerequisites

  • Public API key - This can be found in the Permutive dashboard, in your project settings. Feel free to provision a new one, by clicking Add Key and choosing Public.
  • Brightcove Video Player - You should already have a Brightcove video player installed on your site. You should also have access to the Brightcove dashboard, where you can configure your player.

Enabling the Integration

You must enable this integration in the Permutive dashboard, if this has not already be done. In the Permutive dashboard, navigate to your project integrations page. Click Add Integration and select Brightcove Video Player.

Installing the Player Plugin

The Permutive plugin for Brightcove can be installed into your player using the Brightcove dashboard. The following steps must be performed for every player where you want Permutive tracking enabled:

  1. Open the player in Brightcove Cloud Studio
  2. Scroll down to Plugins and press Edit
  3. Click on JavaScript and paste our plugin URL:
    https://cdn.permutive.com/integrations/videojs-permutive-1.3.3.js
  4. Select the '+' to the right
  5. Click on Name, Options (JSON) and paste in the following configuration:
    {
       "apiKey": "<PUBLIC_API_KEY>",
       "platform": "<PLATFORM>",
       "namespace": "<NAMESPACE>" // AMP only
    }
    
    • Replace <PUBLIC_API_KEY> with your Permutive public API key.
    • Replace <PLATFORM> with either web, amp or fia, based on whether your player is to be deployed on Web, AMP or Instant Articles.
    • AMP Only: Replace <NAMEPSPACE> with your AMP namespace.
      Please contact us prior to beginning your AMP deployment and we will assign you an namespace, which is required for deployment. This field should be omitted for Web and FIA deployments, along with the preceding ,.
  6. Click Save

Having completed the above steps, plugin installation is now complete. You should start seeing video event data appear in the Permutive dashboard.

The Brightcove player may be cached on a CDN for a period of time, so we recommend waiting up to an hour for events to begin coming in.

Video Ad Targeting

It is possible to make use of Permutive segments in targeting video ads served in your Brightcove player via the DFP ad server.

To do this:

  1. Open the player in Brightcove Cloud Studio
  2. Go to Advertising
  3. Modify the URL in the Ad Tag section to include &cust_params=permutive%3D{permutive} in its query part

Be aware that cust_params may already be part of the URL, if you are already appending custom targeting data to ad requests. In this case just prepend the cust_params value with permutive%3D{permutive}&.

Targeting for pre-roll ads is only supported when using the "on play" Brightcove Request Ads setting. If "on load" is used, Permutive targeting will not be included on the ad request.