Creating Custom Integrations with the Audience Module

Product(s)
Video Cloud
Role(s)
Studio User
Topic(s)
Audience/Marketing Automation

This topic explains how to configure the Audience module for a custom integration.

The Audience module allows Video Cloud to synchronize viewing data from Audience-enabled Brightcove Players to popular marketing automation platforms. The Audience module can also be configured with a custom integration. With a custom integration, viewing data is saved locally in Video Cloud and the Audience API is used to programmatically extract the data.

The Audience module integration consists of two main components:

  • A Brightcove Player plug-in to enable tracking of video views data
  • Custom development that uses the Audience API to retrieve the viewing data

Requirements

To use the Audience module you must:

  • Have a Professional or Enterprise Video Cloud account
  • Have the Audience module enabled for your account by submitting the required information in the initial splash screen that appears when you open the Audience module
  • Click through the service agreement the first time you use the module
  • In order for leads to be collected, a lead form has to be configured and assigned to a player
  • Use the Advanced (in-page) embed code when publishing your player; Standard (iframe) embed code will not work as the plugin will be running inside of an iframe and therefore will be unable to access the parent page URL parameters

Setting up the connection

Follow these steps to configure a custom integration.

  1. Open the Audience module and click Data Connections in the left navigation.
  2. Click Add New Connection.
  3. Select Custom as the integration.

    Note: The integrations that are available are based upon your Video Cloud subscription.

  4. (Optional) Enter a Connection Name.
    select custom
  5. Click Connect.

The custom connection is now set up and ready to use.

Configuring the integration

Once the connection has been made, you can configure the integration.

connected options
  1. By default, the Connection Status will be Enabled. The Connection Status determines if Video Cloud video engagement data is saved.
    • Enabled - Data is collected and will be saved
    • Disabled - No data is collected (integration is disabled)
  2. Select a data retention policy. The data retention policy determines how long the viewing data and lead form data (if using an Audience lead form) will be retained in your Video Cloud account.

    Note: If you select No retention, NO data will be saved. When you use the API to download data, there won’t be any.

    data retention options

Creating an Audience-enabled player

Video engagement data will only be saved when you are using an Audience-enabled video player. For information on creating an Audience-enabled Brightcove Player, see Creating an Audience-enabled Player.

Passing a tracking ID

The Audience module supports the ability to pass a tracking ID (bctrackingid) value. The Tracking ID might be used to track a campaign ID for example. The bctrackingid can be appended to the URL that displays the Audience-enabled player. For example:

  http://www.myurl.com/video.html?bctrackingid=12345

Identifying viewers

When using a custom integration, you are responsible for identifying viewers. The Audience plugin needs two key pieces of information:

Description URL Parameter Embed Parameter Value
Is the viewer known (needed for lead form) bcknownuser data-bc-known-user 0 or 1
What’s the GUID (needed for view event tracking) bccustomguid data-bc-custom-guid string
 

These values can be passed in via URL parameters or through the player embed code. For viewer tracking to occur, the user id should be passed as a URL parameter on the page that is displaying the video. The known user parameter is required for lead forms (if you'd like the lead form to conditionally display for unknown viewers) and profile creation (known users will have a profile created).

Note: In order for the player/plugin to read the URL parameters, the Advanced (in-page) embed code should be used. The Standard (iframe) embed code will not work as the plugin will be running inside of an iframe and therefore is unable to access the parent page URL which has the parameter.

It’s also possible to pass the GUID to the Audience player using a JavaScript value that’s available in the page. Using the player config, it’s possible to tell Audience what the name of the JavaScript variable is and Audience will then attempt to read that variable using it as the custom GUID. To do this, edit the Audience player and configure the plugin options for the Audience plugin.

select custom

In the above example, the player config is telling Audience that there’s a JavaScript object in the page called samlAttributes and it has a property called nameID. Audience will attempt to read that and use its value for the custom GUID.

Viewing video data

There are several options available for viewing video data when using a custom integration:

  • Viewer Activities (Events) - Provided as part of the Audience module, this option can be used to view video data inside the Audience module. For information, see Viewing Player Events in the Audience Module.
  • Viewer Profiles - Provided as part of the Audience module, this option can be used to view video data based upon a user profile value inside the Audience module. For information, see Viewing Viewer Profile Information.
  • Export Data - Provided as part of the Audience module, this option can be used to export video view and lead data. For information, see Exporting Data from the Audience Module.
  • Audience API - The Audience API can be used to programmatically retrieve video view and lead data. For information, see Overview: Audience API.