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.

Keys and values requirements

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

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

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)
    }
}