Table of content

Get started with customConfig

Understand customConfig

The customConfig parameter is a player parameter which can be use to pass a custom information to a loaded player to apply different business rules.

Here are a few use cases which can be managed through the customConfig parameter:

  • If you have reporting or targeting needs, and you need to provide additional information to the player (for instance: category of a website, player position), you can use this parameter to send us your custom keys and values.
  • If you would like to disable the ads for a specific audience or content type, you can use this parameter to send us a custom key which will disable the ads.
  • If you’re using a dynamic ad unit system, and you can use this parameter to pass these informations through our player

In this guide, you will learn how customConfig works and how to send your keys and their values depending on your integration.

Implement customConfig

The parameter is passed in on player initialization and can be updated dynamically by the Player API.

Starting implementing customConfig can be easily configured through a few steps:

  1. Define the keys you would like to provide and the business logics you would like to implement
  2. Discuss with your Content Manager your needs and the keys you would like to use based on your implementation
  3. Share your VAST tag and your custom keys and values to your Content manager
  4. Pass your custom keys and values through the customConfig parameter

URL encoding

Based on the integration method selected, you might have to URL encode the values you would like to provide through customConfig.

When the keys and values are sent as a query parameter, at least a single URL encoding is required.

TYPEINFOENCODING REQUIRED
Player Embed ScriptPass keys and values using the customConfig[keys] parameter in the data-params attributeYES
Player iFramePass value using query string “customConfig[keys]”YES
Player Library ScriptPass values when using the createPlayer() methodNO
Update with the Player APIUpdating the ad values using the setCustomConfig() methodNO

URL encoding & special characters: Please keep in mind that the values may require a 2nd URL encoding if they contain special characters to prevent any issues during the URL parsing.

Keys and values requirements

Keys limitationOur system can pass up to 20 keys to your VAST tag.

If you need to pass more than 20 keys and values to yout VAST, please contact your Content Manager to discuss your needs.
Character limitsSome browsers may block the HTTP call if you’re sending a large amount of keys and values.

To prevent that, we recommend you to provide less than 2000 total characters for all your keys and values.
Keys and values as objectsWe invite you to use the recommended method below depending on your integration.

Don’t pass your keys and values as an object, otherwise our system won’t be able to interpret them.
Special characters in your keys and valuesIf your key or your value contains special character, we invite you to URL encode them to make sure they can be properly managed during the URL parsing.
Values typeWe only accept values with the following type: string, boolean, integer, float
Keys formatYour keys must be written in camelCase. If your keys are using underscores, they won’t be interpreted by our system.

For example : premiumSubscription will work, premium_subscription won’t.

Implement CustomConfig with Player library script

Integration principles

The Player Library Script doesn’t require any encoding and your values can be sent directly using the customConfig parameter.

You can pass your keys and values into the player script with the following format:

<script src="https://geo.dailymotion.com/libs/player/x938as.js"></script>
<div id="player1"></div>
 
<script>
// Create a player using the API
dailymotion.createPlayer('player1', {
  video: 'x84sh87',
  params: {
    customConfig: {
        YourFirstParam: 'value',
        YourSecondParam: 'value'
    }
  }
});
</script>

If your key has a unique value, directly pass the value via the customConfig parameter.

If your key has multiples values, pass all your values and separate them with a comma via the CustomConfig parameter

In case your keys and values contains special characters, we invite you to perform a single URL encoding. This will prevent keys and values to be ignored during the URL parsing which could be interpreted by the HTTP protocol.

Integration example

In the example below, we will pass 2 different keys with their values to the player:

  • The key contentCategory which has the value sport and basketball
  • The key user which has the value USERID/12345
<script src="https://geo.dailymotion.com/libs/player/x938as.js"></script>
<div id="player1"></div>
 
<script>
// Create a player using the API
dailymotion.createPlayer('player1', {
  video: 'x84sh87',
  params: {
    customConfig: {
        contentCategory: 'sport,basketball',
        user: 'USERID%2F12345',
        premium
    }
  }
});
</script>

Implement CustomConfig with Player embed script

Integration principles

Step 1 – Encode your values

In this configuration, you’ll have to perform a single URL encoding on your keys and values before using customConfig.

In case your keys and values contains special characters, we invite you to perform a 2nd URL encoding. This will prevent keys and values to be ignored during the URL parsing which could be interpreted by the HTTP protocol.

Step 2 – Pass your keys and values with data-params

When your values are encoded, all you have to do is to pass them using the customConfig[keys] parameter in the data-params attribute

<script src="https://geo.dailymotion.com/player/x938as.js"
data-video="x84sh87" 
data-params="customConfig[key]=value&customConfig[key2]=value2">
</script>

Integration example

In the example below, we’re using CustomConfig to pass 2 different keys (and their associated values if any) to the player :

  • the key contentCategory with the values sport&basketball
  • the key user with the value USERID/12345
<script src="https://geo.dailymotion.com/player/x938as.js"
data-video="x84sh87" 
data-params="customConfig[content]=sport%26basketball&customConfig[id]=USERID%252F12345">
</script>

Implement CustomConfig with Player iframe

Integration principles

Step 1 – Single encode your values

In this configuration, you’ll have to perform a single URL encoding on your keys and values before using customConfig.

In case your keys and values contains special characters, we invite you to perform a 2nd URL encoding. This will prevent keys and values to be ignored during the URL parsing which could be interpreted by the HTTP protocol.

Step 2 – Pass your keys and values as query parameters

When using the Player iframe, your keys and values should be integrated at the end of the video URL, as a query parameter.

// Embed a player using the iFrame

<iframe frameborder="0" width="640" height="360" 
src="https://geo.dailymotion.com/player.html?video=x7fbfjy&customConfig[yourFirstKey]=yourfirstvalue&customConfig[aSecondKey]=yourvalues"
allowfullscreen 
allow="autoplay; fullscreen"> 
</iframe>

Integration example

In the example below, we’re using CustomConfig to pass 2 different keys (and their associated values if any) to the player :

  • the key contentCategory with the values sport&basketball
  • the key user with the value USERID/12345
// Embed a player using the iFrame

<iframe frameborder="0" width="640" height="360" 
src="https://geo.dailymotion.com/player.html?video=x7fbfjy&customConfig[content]=sport%26basketball&customConfig[id]=USERID%252F12345&customConfig[premium]"
allowfullscreen 
allow="autoplay; fullscreen"> 
</iframe>

Update your values dynamically with the setCustomConfig() method

When using the Player Library, you can use the method setCustomConfig() to dynamically update the advertising parameter value based on the player event you would like to listen.

Update one value with setCustomConfig

In this example, you’re using a key which requires a different value depending on the video played.

Here, we will set the key firstVideo with the value true when the player is loaded, and once the first video is playing, we will set the value false (for the next ad calls).

<script src="https://geo.dailymotion.com/libs/player/x34532.js"></script>

<h1>Dynamically update one value with setCustomConfig</h1>

<div id="player1"></div>

<script>// Create a player using the API 
dailymotion
  .createPlayer('player1', {
    video: 'x3rdtfy',
    params: {
      customConfig: {
        ppid: '1234',
        firstVideo: 'true'
      }
    }
  })
// Use the player event to trigger an action when the player loads the next content
  .then((player) => {
    player.on(dailymotion.events.VIDEO_PLAYING, () => {
// Use the method to dynamically send a new value 
       player.setCustomConfig({ firstVideo: 'false' })
    })
  });
</script>

Update several values with setCustomConfig

Based on the example above, this time you’ll need to update several key when a new video is loading.

Let’s take 3 keys and values which have to be passed to the player:

  • The key category which has to change depending on the video
  • The key subscription which won’t change as the user will remain the same
  • The key firstVideo which will change depending on the video
<script src="https://geo.dailymotion.com/libs/player/x34532.js"></script>

<h1>Dynamically update one value with setCustomConfig</h1>

<div id="player1"></div>

<script>// Create a player using the API 
dailymotion
  .createPlayer('player1', {
    video: 'x3rdtfy',
    params: {
      customConfig: {
        category: 'music',
        firstVideo: 'true',
        subscribed: 'true'
      }
    }
  })
// Use the player event to trigger an action when the player loads the next content
  .then((player) => {
    player.on(dailymotion.events.VIDEO_PLAYING, () => {
// Use the method to dynamically send a new value 
       player.setCustomConfig({ firstVideo: 'false', category: 'sport'})
    })
  });
</script>