diff --git a/dev-docs/integrate-with-the-prebid-analytics-api.md b/dev-docs/integrate-with-the-prebid-analytics-api.md index b073000889..8ffd290317 100644 --- a/dev-docs/integrate-with-the-prebid-analytics-api.md +++ b/dev-docs/integrate-with-the-prebid-analytics-api.md @@ -37,6 +37,28 @@ For instructions on integrating an analytics provider, see the next section. ![Prebid Analytics Architecture Diagram]({{ site.baseurl }}/assets/images/prebid-analytics-architecture.png){: .pb-md-img :} +## Analytics Labels + +Prebid events can carry an object of **analytics labels** that annotate the payload with experiment, rollout, or troubleshooting context. Labels are available to every analytics adapter in two places: + +* as a top-level `labels` object that combines every active label +* as `args.analyticsLabels` inside the event payload so adapters that only inspect the args can still read them + +Publishers can declare their own labels with standard configuration: + +```javascript +pbjs.setConfig({ + analyticsLabels: { + experiment_1: 'group_a', + releaseTrain: 'B' + } +}); +``` + +Modules can also contribute labels by calling `setLabels` from `AnalyticsAdapter`. One example is the [Enrichment Lift Measurement Module](/dev-docs/modules/enrichmentLiftMeasurement.html), which attaches the active A/B test configuration so analytics adapters can report on each test run. All labels defined by publishers or modules are merged together before being delivered to analytics adapters. + +Analytics adapters that want to use this metadata simply read either `event.labels` or `event.args.analyticsLabels` in their `track` implementation. + ## Creating an Analytics Module Working with any Prebid project requires using Github. In general, we recommend the same basic workflow for any project: diff --git a/dev-docs/modules/enrichmentLiftMeasurement.md b/dev-docs/modules/enrichmentLiftMeasurement.md index f43df57495..f41e9f3828 100644 --- a/dev-docs/modules/enrichmentLiftMeasurement.md +++ b/dev-docs/modules/enrichmentLiftMeasurement.md @@ -56,7 +56,7 @@ pbjs.setConfig({ }); ``` -The following object will be attached to analytics labels based on the configuration above: +The following object will be attached to [analytics labels](/dev-docs/integrate-with-the-prebid-analytics-api.html#analytics-labels) based on the configuration above: ```javascript { @@ -65,3 +65,14 @@ The following object will be attached to analytics labels based on the configura { name: '33acrossIdSystem', percentage: 0.5, enabled: false } // May be true or false depending on random selection ] } +``` + +### Analytics Labels + +The module adds one analytics label whose key matches the configured `testRun` value. The value is an array that lists every User ID submodule participating in the experiment along with its configured percentage and whether it was enabled for the current page view. Analytics adapters can use that label to segment reporting by experiment group. + +- `name`: The User ID submodule name. +- `percentage`: The configured rollout percentage, which is useful for validating traffic splits. +- `enabled`: Indicates whether the submodule ran for the current user; this is the randomized value that identifies the treatment/control groups. + +See the [Analytics labels](/dev-docs/integrate-with-the-prebid-analytics-api.html#analytics-labels) section for guidance on how analytics adapters consume this metadata.