comscore-connector-web
The Comscore connector provides a Comscore integration for THEOplayer.
Installation
npm install @theoplayer/comscore-connector-web
This connector depends on the JavaScript ComScore SDK, which should be loaded and available in the global scope before the connector. Get it from your ComScore dashboard or talk to a ComScore representative. This connector was developed and tested with versions 7.2.0.200214 and 7.6.1.210506
<script src="/path/to/comscore.js">
Usage
Configuring the connector
Create the connector by providing the THEOplayer
instance, a ComscoreConfiguration (which contains your publisher id, also referred to as the c2 value) and the ComscoreMetadata of the first source being set to the player. You can change the metadata dynamically throughout the lifecycle of the connector.
import { ComscoreConnector } from '../../dist/comscore-connector.esm.js';
const comscoreConfig = {
publisherId: '<your publisher id>',
applicationName: 'Test App',
userConsent: '1',
platformApi: ns_.analytics.PlatformAPIs.WebBrowser,
debug: true
};
const comscoreMetadata = {
mediaType: 'longFormOnDemand',
uniqueId: 'testuniqueId',
length: 634566, // in milliseconds
stationTitle: 'THEOTV',
programTitle: 'Big Buck Bunny',
episodeTitle: 'Intro',
genreName: 'Animation',
classifyAsAudioStream: false,
customLabels: {
testcustomlabel: 'testcustomvalue'
}
};
const comscoreConnector = new ComscoreConnector(player, comscoreConfig, comscoreMetadata);
Optional ComscoreConfiguration properties
usagePropertiesAutoUpdateMode
When omitted this wil default to foregroundOnly.
skeleton
Pass an interface object with target platform specific implementations for the necessary Platform APIs. E.g.
analytics.PlatformApi.setPlatformApi(analytics.PlatformApi.PlatformApis.Skeleton, {
onDataFetch: function (onSuccessCallback, onErrorCallback) {
// Execute a function with platform-specific code to retrieve up-to-date information.
runPlatformSpecificCodeToRetrieveValues(onSuccessCallback, onErrorCallback);
}
// Other overridden PlatformAPI methods, as needed.
});
For more information, please consult the Skeleton PlatformAPI Implementation Guide
Note that if the skeleton property is defined, the connector will always use setPlatformAPI(ns_.analytics.PlatformAPIs.Skeleton)
.
platformApi
Pass a valid value from ns_.analytics.PlatformAPIs
. When omitted, the connector will report setPlatformAPI(ns_.analytics.PlatformAPIs.html5)
.
adIdProcessor
Pass a function with the following signature if you require custom ad id handling: (ad: Ad) => string
. When omitted, the connector will use (ad) => ad.id
. Consult THEOplayer's types for more info about the Ad
interface.
debug
A flag to enable verbose logging.
Passing metadata dynamically
The connector allows updating the current asset's metadata at any time. Do it when setting a new source to the player.
comscoreConnector.updateMetadata(newMetadata);
ComscoreMetadata fields
Based on the ComscoreMetadata
type, you can tell which fields are mandatory and which aren't. Note that this is purely for the integration to work correctly. Depending on the Comscore solution you are using, different fields are required/optional. The mandatory fields in the ComscoreMetadata
type are the ones that are mandatory for all three Comscore solutions:
- Video Metrix (V)
- Cross Platform Product Suite (X)
- Cross Media Audience Measurement (C)
Property | Required | Optional |
---|---|---|
mediaType | All | |
uniqueId | All | |
length | All | |
c3? | V | |
c4? | V | |
c6? | V | |
stationTitle | All | |
stationCode? | All | |
networkAffiliate? | All | |
publisherName? | X C | V |
programTitle | All | |
programId? | V C | |
episodeTitle | All | |
episodeId? | X C | |
episodeSeasonNumber? | X C | |
episodeNumber? | X C | |
genreName | All | |
genreId? | All | |
carryTvAdvertisementLoad? | X | |
classifyAsCompleteEpisode? | X | |
dateOfProduction? | C | |
timeOfProduction? | C | |
dateOfTvAiring? | X C | |
timeOfTvAiring? | X C | |
dateOfDigitalAiring? | X C | |
timeOfDigitalAiring? | X C | |
feedType? | X | |
classifyAsAudioStream | Al | |
deliveryMode? | All | |
deliverySubscriptionType? | All | |
deliveryComposition? | All | |
deliveryAdvertisementCapability? | All | |
mediaFormat? | All | |
distributionModel? | All | |
playlistTitle? | C | |
totalSegments? | V C | |
clipUrl? | V C | |
videoDimension? | C | |
customLabels? | All |
Documentation
The integration guidelines from ComScore can be found on their Unified Digital Measurements page in the Tagging section.