How to change customData fields values?

Web Collector

There are two methods to either permanently or temporarily change customData values during a session: setCustomData and setCustomDataOnce / sendCustomDataEvent.

Both methods accept a subset of the available customData fields you want to change:

collector.setCustomData({
  customData1: "new-value",
  customData3: "new-value"
})

setCustomData

This method changes the value of a customData field for the remainder of a session. It can be called multiple times.

Note: The Bitmovin Analytics dashboard does not display dynamic updates to customData fields. Changes are only visible when you export your Analytics data.

The behavior depends on the current player state:

If the player is in paused or played state: An additional sample is sent immediately. This sample contains the old customData values and all measurements accumulated up to that point. All subsequent samples will use the new customData values.

If the player is in any other state: No additional sample is sent. The new customData values are stored internally and will be applied to all future samples.

setCustomDataOnce / sendCustomDataEvent

This method temporarily changes customData values for a single sample only.

When called, one additional sample is sent with state = customdatachanged and the new values for the selected customData fields. All duration measurements in that sample (e.g. played, paused, duration) are set to 0. The next regular sample will revert to the previously set customData values.

Android & iOS Collectors (v3+)

Starting with Analytics Collector v3 for Android and iOS, customData can be configured in two ways:

1. Source-Independent Custom Data (DefaultMetadata)

Set static custom data values when creating the collector via DefaultMetadata. These values cannot be changed after the collector is created and apply across all sources.

Typical use cases include the app version, a specific device type, or platform information beyond what is collected automatically.

2. Source-Specific Custom Data (SourceMetadata)

Set custom data for a specific source via SourceMetadata. When the player is playing that source, these values take precedence.

Merging is done on a per-field basis (customData1, customData2, …): if a field is null in SourceMetadata, the corresponding value from DefaultMetadata is used instead. SourceMetadata always has higher priority than DefaultMetadata.

Changing Custom Data at Runtime

Custom data in SourceMetadata can be updated at any time by calling setCustomData with the relevant source as the first parameter:

• When setCustomData is called, the current measurement sample is closed with the old custom data, and all subsequent samples in the current impression will use the new values.
• Alternatively, you can directly reassign the customData values inside SourceMetadata while playing. In this case, no additional sample is sent — the new values are picked up with the next event that triggers a sample.

Note: setCustomData is effectively an accessor to the customData property inside SourceMetadata, so its changes share the same lifecycle as that source's metadata.