PBS client aTags (#5454)

* PBS client aTags * lint * lint * Update prebid-server/developers/module-atags.md Co-authored-by: Muki Seiler <[email protected]> * Update prebid-server/developers/module-atags.md Co-authored-by: Muki Seiler <[email protected]> * Update prebid-server/developers/module-atags.md Co-authored-by: Muki Seiler <[email protected]> --------- Co-authored-by: Muki Seiler <[email protected]>
prebid · Jun 27, 2024 · b6190b9 · b6190b9
1 parent f774207
commit b6190b9
Show file tree

Hide file tree

Showing 3 changed files with 151 additions and 14 deletions.
diff --git a/prebid-server/developers/module-atags.md b/prebid-server/developers/module-atags.md
@@ -8,29 +8,30 @@ sidebar_entry: /prebid-server/developers/add-a-module.html
 # Prebid Server - Module Analytics Tags Conventions
 {: .no_toc}
 
-* TOC
+- TOC
 {:toc }
 
 ## Overview
 
-Analytics Tags (aka ‘ATags’) are a log mechanism provided by PBS-core to allow modules
+Analytics Tags (aka ‘aTags’) are a log mechanism provided by PBS-core to allow modules
 to inform analytics adapters about what happened in the request.
 Use of the Analytics Tag structure is completely optional. It's meant
 to be used when there are application or reporting reasons for sharing module results.
 See the [Prebid Server module overview](/prebid-server/developers/add-a-module.html) for background information.
 
 This document defines a convention aimed at allowing module developers to create
-consistent ATags that can be easily read by analytics adapters.
+consistent aTags that can be easily read by analytics adapters.
 
-![Prebid Server ATags](/assets/images/prebid-server/module-atags.png){:class="pb-xlg-img"}
+![Prebid Server aTags](/assets/images/prebid-server/module-atags.png){:class="pb-xlg-img"}
 
-1. Modules may return a data structure containing ATags to PBS-Core.
-2. PBS-Core adds any ATags to the 'invocation context' data structure.
+1. Modules may return a data structure containing aTags to PBS-Core.
+2. PBS-Core adds any aTags to the 'invocation context' data structure.
 3. Analytics modules have access to the invocation context.
 
 ## Analytics Tag Conventions
 
-The general idea is that ATags are a list of module-specific "activities" that have these attributes:
+The general idea is that aTags are a list of module-specific "activities" that have these attributes:
+
 - activity name: should be unique within the context of this module. e.g. 'enrich-request'
 - an overall status
 - an array of specific results within the activity
@@ -41,7 +42,7 @@ The general idea is that ATags are a list of module-specific "activities" that h
 
 Here's an example from the [ORTB2 Blocking module](/prebid-server/pbs-modules/ortb2-blocking.html):
 
-```
+```json
 [{
    // scenario: response from bidderA blocked on badv for imp=1
    activities: [{
@@ -71,7 +72,7 @@ Here's an example from the [ORTB2 Blocking module](/prebid-server/pbs-modules/or
 The following table contains the field conventions.
 
 {: .table .table-bordered .table-striped }
-| ATag Attr | Required? | Description | Type |
+| aTag Attr | Required? | Description | Type |
 |---+---+---+---|
 | activities | yes | One or more activities carried out by the module. | array of objects |
 | activities .name | yes | Name of the activity. Must be documented and unique within the module. | string |
@@ -86,10 +87,9 @@ The following table contains the field conventions.
 | activities. results. appliedto. request | no | The service examined the entire openrtb request object. This is in case the module updated something not adunit-specific. | boolean |
 | activities. results. appliedto. response | no | The service examined the entire openrtb response object. This is in case the module updated something not adunit-specific. | boolean |
 
-
 ## Designing Analytics Tags
 
-ATags are for reporting. Start by considering what the module's doing that consumers might want to display. Each processing stage the module operates in may be
+aTags are for reporting. Start by considering what the module's doing that consumers might want to display. Each processing stage the module operates in may be
 reported as a separate activity, or perhaps everything the module does is lumped
 as one activity.
 
@@ -106,7 +106,7 @@ to report on what percentage of responses from each bidder were being thrown
 away due to blocking rules. This could have been done by defining a separate 'activity' for each of the 4 types of enforcement, but it was decided
 to just have one kind of activity ('enforce-blocking') and get the specific
 details as part of the 'value'. There was no requirement to report on the 
-outbound part of what the module does, so no ATags are created for that part
+outbound part of what the module does, so no aTags are created for that part
 of the functionality.
 
 Once you know what reports are desired, figure out which activity 'results'
@@ -123,6 +123,7 @@ Be sure to detail the results in your module documentation so that analytics ada
 aware of what they can look for.
 
 Let them know:
+
 - which activities your module supports
 - what kind of results to expect
 - whether the results objects have module-specific `values`
@@ -142,7 +143,8 @@ In short, to get analytics tags, you'll need to parse this data structure:
 
 Here's an example of the data structured as JSON, though the details
 of the actual object will differ in PBS-Java and PBS-Go.
-```
+
+```json
           "stages": [
             {
               "stage": "raw-auction-request",
@@ -227,6 +229,117 @@ of the actual object will differ in PBS-Java and PBS-Go.
 
 See the implementation guide for your platform for specific syntax.
 
+## Sending aTags to the client-side
+
+{: .alert.alert-info :}
+PBS-Java only
+
+The use cases for server-side and client-side analytics are different:
+
+- Server-side analytics are the only game in town when it comes to App, AMP, DOOH, etc.
+- However, when Prebid.js is in use and bidders are split between client-side and server-side, it would be far better if auctions were only logged once.
+
+This feature allows all relevant data passed to the client from Prebid Server so that client-side analytics can be the one to log the results.
+To allow the sharing of these details, there are two conditions:
+
+1. Server-side account configuration must allow sharing of these details by setting `analytics.allow-client-details: true`
+1. The ORTB request must contain `ext.prebid.analytics.options.enableclientdetails: true`
+
+If both are true, then any and all PBS analytics tags will be copied to the response field ext.prebid.analytics.tags.
+
+### Client aTag example
+
+The "pb-ortb-blocking" module at the "processed auction" stage adds the following Analytics Tags (from the ORTB2 blocking module)
+
+```json
+[{
+  "activities": [{
+    "name": "enforce-blocking",
+    "status": "success",
+    "results": [{
+        "status": "success-block",
+        "values": {
+                  "attributes": ["badv"],
+                  "adomain": ["bad.com"]
+        },
+        "appliedto": {
+          "bidder": "bidderA",
+           "impids": ["1"]
+        }
+    },{
+        "status": "success-allow",
+        "appliedto": {
+          "bidder": "bidderA",
+          "impids": ["2","3","4"]
+        }
+    }]
+ }]
+
+Also, the "vendorA-brand-safety" module at the "all processed bid responses" stage adds these aTags:
+
+```json
+[{
+   "activities": [{
+    "name": "brand-safety",
+    "status": "success",
+    "results": [{
+        "status": "success-allow",
+        "appliedto": {
+          "bidder": "bidderA",
+          "impids": ["1,","2","3","4"]
+        }
+    }]
+ }]
+```
+
+The resulting response with the request ext.prebid.analytics.options.enableclientdetails: true and config analytics.options.enableclientdetails:true would be:
+
+```json5
+// this is actually a nested object - but aggregated for readablility
+"ext.prebid.analytics.tags": [{
+  "stage": "processed-auction-request",
+  "module": "pb-ortb-blocking",
+  "analyticstags": [{
+     "activities": [{
+      "name": "enforce-blocking",
+      "status": "success",
+      "results": [{
+        "status": "success-block",
+        "values": {
+                  "attributes": ["badv"],
+                  "adomain": ["bad.com"]
+        },
+        "appliedto": {
+          "bidder": "bidderA",
+           "impids": ["1"]
+        }
+    },{
+        "status": "success-allow",
+        "appliedto": {
+          "bidder": "bidderA",
+          "impids": ["2","3","4"]
+        }
+    }]
+ }]
+},{
+  "stage": "all-processed-bid-responses",
+  "module": "vendorA-brand-safety",
+  "analyticstags": [{
+   "activities": [{
+    "name": "brand-safety",
+    "status": "success",
+    "results": [{
+        "status": "success-allow",
+        "appliedto": {
+          "bidder": "bidderA",
+          "impids": ["1,","2","3","4"]
+        }
+    }]
+}]
+```
+
+It's up to the client-side analytics adapters to be able to parse the module-specific contents of the aTags.
+
 ## Further Reading
 
 - [PBS Module Overview](/prebid-server/developers/add-a-module.html)

diff --git a/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.md b/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.md
@@ -1492,7 +1492,9 @@ PBS-core creates this block before sending to bid adapters. They receive additio
 }
 ```
 
-##### Analytics Extension
+##### Analytics Extensions
+
+###### Analytics adapter flags
 
 Some analytics adapters may support special flags that can be passed on ext.prebid.analytics. e.g.
 
@@ -1506,6 +1508,26 @@ ext.prebid: {
 }
 ```
 
+###### Sending analytics tags to the client-side
+
+{: .alert.alert-info :}
+PBS-Java only
+
+[Analytics Tags](/prebid-server/developers/module-atags.html) (aka "aTags") are an advanced feature that some [modules](/prebid-server/pbs-modules/) and
+features utilize to communicate auction details to server-side analytics adapters.
+
+When there are Prebid.js-based analytics adapters in use, server-side details can be sent to them with aTags. This allows the client-side analytics systems
+to see what's happening within Prebid Server - all analytics tags created by all modules will be sent to the client.
+
+To allow the sharing of these details, there are two conditions:
+
+1. Server-side account configuration must allow sharing of these details by setting `analytics.allow-client-details: true`
+1. The ORTB request must contain `ext.prebid.analytics.options.enableclientdetails: true`
+
+If both are true, then any and all PBS analytics tags will be copied to the response field ext.prebid.analytics.tags.
+
+See the [Analytics Tags](/prebid-server/developers/module-atags.html) page for more information.
+
 ##### Preferred Media Type
 
 {: .alert.alert-info :}
@@ -1791,6 +1813,7 @@ The Prebid SDK version comes from:
 | ext<wbr>.prebid<wbr>.floors | PBS floors data | object | no |
 | ext<wbr>.prebid<wbr>.returnallbidstatus | If true, PBS returns [ext.seatnonbid](#seat-non-bid) with details about bidders that didn't bid. | boolean | no |
 | ext<wbr>.prebid<wbr>.analytics | Arguments that can be passed through to individual analytics adapters | object | no |
+| ext<wbr>.prebid<wbr>.analytics<wbr>.options.<wbr>enableclientdetails | Requests that [aTags](/prebid-server/developers/module-atags.html) be sent to the client-side for analytics. | boolean | no |
 | imp<wbr>.ext<wbr>.ae | If 1, signals bid adapters that Fledge auction config is accepted on the response. (ae stands for auction environment) | integer | yes |
 | app<wbr>.ext<wbr>.prebid<wbr>.source | The client that created this ORTB. Normally "prebid-mobile" | string | yes |
 | app<wbr>.ext<wbr>.prebid<wbr>.version | The version of the client that created this ORTB. e.g. "1.1" | string | yes |

diff --git a/prebid-server/features/pbs-feature-idx.md b/prebid-server/features/pbs-feature-idx.md
@@ -83,6 +83,7 @@ title: Prebid Server | Features
 | Events | Events BidID Generation | Some bidders don't generate unique enough BidIDs to join with auction events. This feature allows the host company to inject a PBS-generated BidID alongside the bidder-generated ID. | <img alt="check" src="/assets/images/icons/icon-check-green.png" width="30"> | <img alt="check" src="/assets/images/icons/icon-check-green.png" width="30"> |
 | Auction | [MultiBid](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#multibid) | Allow named bidders to supply more than one response. | <img alt="check" src="/assets/images/icons/icon-check-green.png" width="30"> | <img alt="check" src="/assets/images/icons/icon-check-green.png" width="30"> |
 | Analytics | Analytics module support | Allows developers to plug in a [custom analytics adapter](/prebid-server/developers/pbs-build-an-analytics-adapter.html). | <img alt="check" src="/assets/images/icons/icon-check-green.png" width="30"> | <img alt="check" src="/assets/images/icons/icon-check-green.png" width="30"> |
+| Analytics | Client-side analytics support | Share [analytics tags](/prebid-server/developers/module-atags.html) with client-side analytics adapters. | | <img alt="check" src="/assets/images/icons/icon-check-green.png" width="30"> |
 | Bid Response Validation | Validate secure markup | PBS can configurably reject bid responses that don't supply a secure creative when in a secure context. | <img alt="check" src="/assets/images/icons/icon-check-green.png" width="30"> | <img alt="check" src="/assets/images/icons/icon-check-green.png" width="30"> |
 | Bid Response Validation | Validate bid sizes | PBS can configurably reject bid responses with sizes that are bigger than the request dimensions. | <img alt="check" src="/assets/images/icons/icon-check-green.png" width="30"> | <img alt="check" src="/assets/images/icons/icon-check-green.png" width="30"> |
 | [Bidder Info Endpoints](/prebid-server/endpoints/info/pbs-endpoint-info.html) | Core | Provides details on which bidders and parameters exist in this Prebid Server. | <img alt="check" src="/assets/images/icons/icon-check-green.png" width="30"> | <img alt="check" src="/assets/images/icons/icon-check-green.png" width="30"> |