Nexx360 Analytics Adapter: add analytics adapter

libraries/nexx360Utils/index.ts

@@ -8,6 +8,7 @@
 import { StorageManager } from '../../src/storageManager.js';
 import { BidRequest, ORTBImp, ORTBRequest, ORTBResponse } from '../../src/prebid.public.js';
 import { AdapterResponse, ServerResponse } from '../../src/adapters/bidderFactory.js';
+import { Nexx360ServerAuction } from './types.js';
 
 const OUTSTREAM_RENDERER_URL = 'https://acdn.adnxs.com/video/outstream/ANOutstreamVideo.js';
 
@@ -79,8 +80,8 @@
   width: number,
   height: number
 ) => (bidResponse: VideoBidResponse) => {
   bidResponse.renderer.push(() => {
     (window as any).ANOutstreamVideo.renderAd({
       sizes: [width, height],
       targetId: divId,
       adResponse: bidResponse.vastXml,
@@ -108,8 +109,8 @@
   { requestId, vastXml, divId, width, height }: CreateRenderPayload
 ): Renderer | undefined => {
   if (!vastXml) {
     logInfo('No VAST in bidResponse');
     return;
   }
   const installPayload = {
     id: requestId,
@@ -201,7 +202,7 @@
       response.renderer = renderer;
       response.divId = bid.ext.divId;
     } else {
       logInfo('Could not create renderer for outstream bid');
     }
   };
 
@@ -213,17 +214,44 @@
   return response as BidResponse;
 }
 
+// --- Server auction data extraction ---
+
+/**
+ * Bid response carrying the server-side auction data from the response `ext`,
+ * for consumption by the Nexx360 analytics adapter on the `bidResponse` event.
+ */
+export type Nexx360BidResponse = BidResponse & { serverAuctionData?: Nexx360ServerAuction };
+
+function getServerAuction(responseBody: any): Nexx360ServerAuction | null {
+  const serverAuction = deepAccess(responseBody, 'ext.serverAuction');
+  if (serverAuction && typeof serverAuction === 'object' && serverAuction.auctionId) {
+    return serverAuction as Nexx360ServerAuction;
+  }
+  return null;
+}
+
 export const interpretResponse = (serverResponse: ServerResponse): AdapterResponse => {
   if (!serverResponse.body) return [];
   const respBody = serverResponse.body as ORTBResponse;
-  if (!respBody.seatbid || respBody.seatbid.length === 0) return [];
 
-  const responses: BidResponse[] = [];
+  if (!respBody.seatbid || respBody.seatbid.length === 0) {
+    return [];
+  }
+
+  // Attach server-auction data to every bid response (rather than holding it in
+  // module state) so it reaches the analytics adapter with the bid that produced
+  // it, and cannot leak into an unrelated auction if a bid is rejected by core.
+  const serverAuctionData = getServerAuction(respBody);
+
+  const responses: Nexx360BidResponse[] = [];
   for (let i = 0; i < respBody.seatbid.length; i++) {
     const seatbid = respBody.seatbid[i];
     for (let j = 0; j < seatbid.bid.length; j++) {
       const bid = seatbid.bid[j];
-      const response:BidResponse = createResponse(bid, respBody);
+      const response:Nexx360BidResponse = createResponse(bid, respBody);
+      if (serverAuctionData) {
+        response.serverAuctionData = serverAuctionData;
+      }
       responses.push(response);
     }
   }

libraries/nexx360Utils/types.ts

@@ -0,0 +1,48 @@
+/** Per-SSP bid attempt for a specific impression */
+export interface Nexx360SSPBid {
+  ssp: string;
+  status: 'bid' | 'noBid' | 'timeout' | 'error';
+  responseTimeMs?: number;
+  cpm?: number;
+  currency?: string;
+  size?: string;
+  dealId?: string;
+  bidId?: string;
+  error?: string;
+}
+
+/** Auction summary for a single impression */
+export interface Nexx360ImpressionAuction {
+  impId: string;
+  adUnitCode: string;
+  bids: Nexx360SSPBid[];
+  totalSsps: number;
+  bidsReceived: number;
+  timeouts: number;
+  errors: number;
+  auctionTimeMs: number;
+  winner?: {
+    ssp: string;
+    cpm: number;
+    currency: string;
+  };
+}
+
+/** Server-side auction data attached to Nexx360 OpenRTB response ext */
+export interface Nexx360ServerAuction {
+  auctionId: string;
+  timestamp: number;
+  impressions: Nexx360ImpressionAuction[];
+  totalImpressions: number;
+  totalSspsCalled: number;
+  totalBidsReceived: number;
+  totalTimeouts: number;
+  totalErrors: number;
+  auctionTimeMs: number;
+}
+
+/** Top-level Nexx360 response extension */
+export interface Nexx360ResponseExt {
+  cookies?: unknown[];
+  serverAuction?: Nexx360ServerAuction;
+}

metadata/modules.json

@@ -6482,6 +6482,11 @@
       "componentName": "mobkoi",
       "gvlid": null
     },
+    {
+      "componentType": "analytics",
+      "componentName": "nexx360",
+      "gvlid": null
+    },
     {
       "componentType": "analytics",
       "componentName": "nobid",

metadata/modules/nexx360AnalyticsAdapter.json

@@ -0,0 +1,12 @@
+{
+  "NOTICE": "do not edit - this file is autogenerated by `gulp update-metadata`",
+  "disclosures": {},
+  "purposes": {},
+  "components": [
+    {
+      "componentType": "analytics",
+      "componentName": "nexx360",
+      "gvlid": null
+    }
+  ]
+}

modules/nexx360AnalyticsAdapter.md

@@ -0,0 +1,80 @@
+# Overview
+
+Module Name: Nexx360 Analytics Adapter
+Module Type: Analytics Adapter
+Maintainer: tech@nexx360.io
+
+# Description
+
+The Nexx360 Analytics Adapter collects Prebid.js auction data and sends it to the Nexx360 analytics platform for monitoring and reporting. It tracks auction lifecycle events, bid requests, bid responses, wins, timeouts, and ad render events.
+
+# Registration
+
+The Nexx360 Analytics adapter requires a publisher ID from Nexx360. Please contact Nexx360 to obtain your publisher credentials.
+
+```javascript
+pbjs.enableAnalytics({
+  provider: 'nexx360',
+  options: {
+    publisherId: 'your-publisher-id',
+    endpoint: 'https://monitoring.nexx360.io'
+  }
+});
+```
+
+Sampling is applied server-side (by the Nexx360 collector), so the adapter sends
+all events and exposes no sampling option.
+
+# Analytics Options
+
+{: .table .table-bordered .table-striped }
+| Name | Scope | Description | Example | Type |
+|------|-------|-------------|---------|------|
+| publisherId | required | Your Nexx360 publisher identifier | `"pub-12345"` | string |
+| endpoint | optional | Analytics endpoint URL (defaults to `https://monitoring.nexx360.io`) | `"https://monitoring.nexx360.io"` | string |
+| abTestLabel | optional | A/B test variant label, attached to every event for slicing analytics by test arm | `"variantA"` | string |
+
+# Events Tracked
+
+The adapter tracks the following Prebid.js events:
+
+- **auctionInit** - When an auction starts
+- **bidRequested** - When bid requests are sent to bidders
+- **bidResponse** - When bid responses are received
+- **bidWon** - When a bid wins the auction
+- **bidTimeout** - When bidders timeout
+- **adRenderSucceeded** - When an ad renders successfully
+- **adRenderFailed** - When an ad fails to render
+
+# Example Configuration
+
+## Basic Setup
+
+```javascript
+pbjs.enableAnalytics({
+  provider: 'nexx360',
+  options: {
+    publisherId: 'your-publisher-id'
+  }
+});
+```
+
+## Production Setup
+
+```javascript
+pbjs.enableAnalytics({
+  provider: 'nexx360',
+  options: {
+    publisherId: 'your-publisher-id',
+    endpoint: 'https://monitoring.nexx360.io'
+  }
+});
+```
+
+# Build
+
+To include this analytics adapter in your Prebid.js build:
+
+```bash
+gulp build --modules=nexx360AnalyticsAdapter,...
+```