Table of content

Pass in custom ad values in your VAST tag using the Dailymotion Player


Get started with customConfig

Understand customConfig

customConfig is a Player parameter which can be used to pass custom information to a loaded Player in order to apply different business rules.

Here are a few use cases which can be managed using 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 via the SDK.

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 Account 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 Account 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 attribute
Player Library ScriptPass values when using the createPlayer() method
Player iFramePass value using query string customConfig[keys]
Android SDKPass values when using the createPlayer() method
iOS SDKPass values when using the createPlayer() methodGoogle tags: ✓
Other tags:
Update ad values with the SDKsUpdate the ad values using the setCustomConfig() method
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 Account 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 any of your key or value contains special characters, 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 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 wrong 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

// Replace {Player_ID} with your own Player ID
<script src="https://geo.dailymotion.com/player/{Player_ID}.js"
// Replace x84sh87 with your own Video ID
data-video="x84sh87" 
data-params="customConfig[key1]=value1&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 keyvalues with the values sport&basketball
  • the key dynamiciu with the value USERID/12345
// Replace {Player_ID} with your own Player ID
<script src="https://geo.dailymotion.com/player/{Player_ID}.js"
// Replace x84sh87 with your own Video ID
data-video="x84sh87" 
data-params="customConfig[keyvalues]=sport%26basketball&customConfig[dynamiciu]=USERID%252F12345">
</script>

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 Library Script with the following format:

// Replace {Player_ID} with your own Player ID
<script src="https://geo.dailymotion.com/libs/player/{Player_ID}.js"></script>
<div id="player1"></div>
 
<script>
// Create a Player using the API
dailymotion.createPlayer('player1', {
// Replace x84sh87 with your own Video ID
  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 contain 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 keyvalues has the value sport and basketball
  • The key dynamiciu has the value USERID/12345
// Replace {Player_ID} with your own Player ID
<script src="https://geo.dailymotion.com/libs/player/{Player_ID}.js"></script>
<div id="player1"></div>
 
<script>
// Create a Player using the API
dailymotion.createPlayer('player1', {
// Replace x84sh87 with your own Video ID
  video: 'x84sh87',
  params: {
    customConfig: {
        keyvalues: 'sport,basketball',
        dynamiciu: 'USERID/12345'
    }
  }
});
</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 wrong 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:

// Replace {Player_ID} with your own Player ID
// Replace x84sh87 with your own Video ID

<iframe frameborder="0" width="640" height="360" 
src="https://geo.dailymotion.com/player/{Player ID}.html?video=x84sh87&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 keyvalues with the values sport&basketball
  • the key dynamiciu with the value USERID/12345
// Replace {Player_ID} with your own Player ID
// Replace x84sh87 with your own Video ID

<iframe frameborder="0" width="640" height="360" 
src="https://geo.dailymotion.com/player/{Player_ID}.html?video=x84sh87&customConfig[keyvalues]=sport%26basketball&customConfig[dynamiciu]=USERID%252F12345"
allowfullscreen 
allow="autoplay; fullscreen"> 
</iframe>

Implement CustomConfig with Android SDK

CMP implementation to ensure monetization:

Publishers in GDPR countries are required to implement a TCF2 registered CMP (Consent Management Platform) in their native app to ensure monetization. A compliant CMP must be used to use IAB TCF2 for the creation and storage of the transparency & consent string. As Dailymotion fully supports the IAB TCF2 standard, our native SDKs and our Player can access this string received from the CMP in-app.

It’s important that the consent string is available before the Player is loading. For information on how to use a CMP in-app see here.

The Android SDK doesn’t require any encoding, your ad values can be sent directly using the customConfig parameter. The Player parameters are then passed on Player initialization with the createPlayer() method.

Your ad integration will have the following format:

val playerParameters = PlayerParameters(
    mute = false,
    customConfig = mapOf(
        "keyvalues" to "category=sport&section=video",
        "dynamiciu" to "USERID/12345",
    ),
)

Dailymotion.createPlayer(
    context = context,
    playerId = "MY_PLAYER_ID", // replace by desired player id
    videoId = "A_VIDEO_ID", // replace by desired video id
    playlistId = "A_PLAYLIST_ID", // replace by desired playlist id
    playerParameters = playerParameter,
    playerSetupListener = object : Dailymotion.PlayerSetupListener {
        override fun onPlayerSetupSuccess(player: PlayerView) {
            // Add PlayerView to view hierarchy
        }

        override fun onPlayerSetupFailed(error: PlayerError) {
            // PlayerView setup failed
        }
    }
)

Implement CustomConfig with iOS SDK

CMP implementation to ensure monetization:

Publishers in GDPR countries are required to implement a TCF2 registered CMP (Consent Management Platform) in their native app to ensure monetization. A compliant CMP must be used to use IAB TCF2 for the creation and storage of the transparency & consent string. As Dailymotion fully supports the IAB TCF2 standard, our native SDKs and our Player can access this string received from the CMP in-app.

It’s important that the consent string is available before the Player is loading. For information on how to use a CMP in-app see here.

Different pre-defined keys and values can be added and defined separately. Pass the defined keys into the customConfig parameter with the createPlayer() method:

var playerParameters = DMPlayerParameters()
playerParameters.customConfig = ["keyvalues":"category=sport&section=video", "dynamiciu":"USERID/12345"]

// Replace {Player_ID} with your own Player ID
// Replace x84sh87 with your own Video ID      
Dailymotion.createPlayer(playerId: "{Player_ID}", videoId: "x84sh87", playerParameters:  playerParameters) {playerView, error in
  //Handle init
}

Update your values dynamically with the setCustomConfig() method

You can use the method setCustomConfig() to dynamically update the advertising parameter value based on the Player event you would like to listen to.

Player Library

Update one value

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

Here, we will set the key keyvalues with the value sport when the Player is loaded, and once the first video is playing, we will set the value basketball (for the next ad calls).

// Replace {Player_ID} with your own Player ID
<script src="https://geo.dailymotion.com/libs/player/{Player_ID}.js"></script>

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

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

<script>// Create a Player using the API 
dailymotion
  .createPlayer('player1', {
// Replace x84sh87 with your own Video ID   
    video: 'x84sh87',
    params: {
      customConfig: {
        keyvalues: 'sport',
        dynamiciu: 'USERID/12345'
      }
    }
  })
// 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({ keyvalues: 'basketball' })
    })
  });
</script>

Update several values

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

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

  • The key keyvalues has to change depending on the video
  • The key subscribed won’t change as the user will remain the same
  • The key dynamiciu will change depending on the video
// Replace {Player_ID} with your own Player ID
<script src="https://geo.dailymotion.com/libs/player/{Player_ID}.js"></script>

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

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

<script>// Create a Player using the API 
dailymotion
  .createPlayer('player1', {
// Replace x84sh87 with your own Video ID
    video: 'x84sh87',
    params: {
      customConfig: {
        keyvalues: 'music',
        dynamiciu: 'USERID/12345',
        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({dynamiciu: 'USERID/98765', keyvalues: 'sport'})
    })
  });
</script>

Android SDK

val customConfig = mapOf(
    "keyvalues" to "category=sport&section=video",
    "dynamiciu" to "USERID/12345",
)
playerView.setCustomConfig(customConfig = customConfig)

iOS SDK

// Replace {Player_ID} with your own Player ID
// Replace x84sh87 with your own Video ID

Dailymotion.createPlayer(playerId: "{Player_ID}", videoId: "x84sh87", playerParameters:  DMPlayerParameters()) {playerView, error in
    if let playerView = playerView {
      let customConfigDict = ["keyvalues":"sport", "dynamiciu":"USERID%2F12345"]
      playerView.setCustomConfig(config: customConfigDict)
    }
}