[WR-2026] Equativ Bid Adapter: add placementuuid param, deprecate site/page/format

modules/equativBidAdapter.d.ts

@@ -0,0 +1,37 @@
+export interface EquativBidderParams {
+  /**
+   * Equativ network id.
+   * Mandatory unless `ortb2.(site|app|dooh).publisher.id` is set.
+   */
+  networkId?: number;
+  /**
+   * Placement identifier used to source inventory.
+   * Preferred way to identify inventory. When provided, it takes precedence
+   * over the deprecated `siteId`, `pageId` and `formatId` parameters.
+   */
+  placementuuid?: string;
+  /**
+   * Equativ site id.
+   * @deprecated Use `placementuuid` instead. Kept only to support the
+   * inventory-structure ramp-up and will be removed in a future release.
+   */
+  siteId?: number;
+  /**
+   * Equativ page id.
+   * @deprecated Use `placementuuid` instead. Kept only to support the
+   * inventory-structure ramp-up and will be removed in a future release.
+   */
+  pageId?: number;
+  /**
+   * Equativ format id.
+   * @deprecated Use `placementuuid` instead. Kept only to support the
+   * inventory-structure ramp-up and will be removed in a future release.
+   */
+  formatId?: number;
+}
+
+declare module '../src/adUnits' {
+  interface BidderParams {
+    equativ: EquativBidderParams;
+  }
+}

modules/equativBidAdapter.js

@@ -194,7 +194,7 @@ export const converter = ortbConverter({
 
   imp(buildImp, bidRequest, context) {
     const imp = buildImp(bidRequest, context);
-    const { siteId, pageId, formatId } = bidRequest.params;
+    const { siteId, pageId, formatId, placementuuid } = bidRequest.params;
 
     delete imp.dt;
 
@@ -207,7 +207,12 @@ export const converter = ortbConverter({
       mergeDeep(imp, { rwdd: bidRequest.mediaTypes.video.ext.rewarded });
     }
 
-    const bidder = { ...(siteId && { siteId }), ...(pageId && { pageId }), ...(formatId && { formatId }) };
+    // `placementuuid` is the preferred way to identify inventory. When it is
+    // provided it takes precedence over the <deprecated> `siteId`, `pageId` and
+    // `formatId` </deprecated> parameters, which are kept only to support the ramp-up period.
+    const bidder = placementuuid
+      ? { placementuuid }
+      : { ...(siteId && { siteId }), ...(pageId && { pageId }), ...(formatId && { formatId }) };
     if (Object.keys(bidder).length) {
       mergeDeep(imp.ext, { bidder });
     }

modules/equativBidAdapter.md

@@ -28,13 +28,24 @@ var adUnits = [
             {
                 bidder: 'equativ',
                 params: {
-                    networkId: 13,  // mandatory if no ortb2.(site or app).publisher.id set
-                    siteId: 20743,  // optional
-                    pageId: 89653,  // optional
-                    formatId: 291,  // optional
+                    networkId: 13,           // mandatory if no ortb2.(site or app).publisher.id set
+                    placementuuid: 'abc-123', // optional, preferred way to identify inventory
+                    siteId: 20743,           // optional, DEPRECATED - use placementuuid instead
+                    pageId: 89653,           // optional, DEPRECATED - use placementuuid instead
+                    formatId: 291,           // optional, DEPRECATED - use placementuuid instead
                 }
             }
         ]
     }
 ];
-```
+```
+
+# Parameters
+
+| Name            | Scope    | Description                                                                                          | Type     |
+|-----------------|----------|------------------------------------------------------------------------------------------------------|----------|
+| `networkId`     | optional | Equativ network id. Mandatory unless `ortb2.(site\|app\|dooh).publisher.id` is set.                   | `number` |
+| `placementuuid` | optional | Placement identifier used to source inventory. Preferred way to identify inventory; takes precedence over `siteId`/`pageId`/`formatId` when both are provided. | `string` |
+| `siteId`        | optional | **Deprecated.** Equativ site id. Use `placementuuid` instead. Kept only to support the ramp-up.      | `number` |
+| `pageId`        | optional | **Deprecated.** Equativ page id. Use `placementuuid` instead. Kept only to support the ramp-up.      | `number` |
+| `formatId`      | optional | **Deprecated.** Equativ format id. Use `placementuuid` instead. Kept only to support the ramp-up.    | `number` |

test/spec/modules/equativBidAdapter_spec.js

@@ -292,6 +292,44 @@ describe('Equativ bid adapter tests', () => {
       expect(request.data.imp[0].ext.bidder).to.be.undefined;
     });
 
+    it('should add ext.bidder with placementuuid to imp object when placementuuid is defined', () => {
+      const bidRequests = [
+        { ...DEFAULT_BANNER_BID_REQUESTS[0], params: { placementuuid: 'abc-123' } },
+      ];
+      const bidderRequest = { ...DEFAULT_BANNER_BIDDER_REQUEST, bids: bidRequests };
+      const request = spec.buildRequests(bidRequests, bidderRequest)[0];
+      expect(request.data.imp[0].ext.bidder).to.deep.equal({
+        placementuuid: 'abc-123',
+      });
+    });
+
+    it('should let placementuuid take precedence over siteId, pageId, formatId when both are provided', () => {
+      const bidRequests = [
+        {
+          ...DEFAULT_BANNER_BID_REQUESTS[0],
+          params: { placementuuid: 'abc-123', siteId: 123, pageId: 456, formatId: 789 },
+        },
+      ];
+      const bidderRequest = { ...DEFAULT_BANNER_BIDDER_REQUEST, bids: bidRequests };
+      const request = spec.buildRequests(bidRequests, bidderRequest)[0];
+      expect(request.data.imp[0].ext.bidder).to.deep.equal({
+        placementuuid: 'abc-123',
+      });
+    });
+
+    it('should still add deprecated ext.bidder params when placementuuid is not provided', () => {
+      const bidRequests = [
+        { ...DEFAULT_BANNER_BID_REQUESTS[0], params: { siteId: 123, pageId: 456, formatId: 789 } },
+      ];
+      const bidderRequest = { ...DEFAULT_BANNER_BIDDER_REQUEST, bids: bidRequests };
+      const request = spec.buildRequests(bidRequests, bidderRequest)[0];
+      expect(request.data.imp[0].ext.bidder).to.deep.equal({
+        siteId: 123,
+        pageId: 456,
+        formatId: 789,
+      });
+    });
+
     it('should add site.publisher.id param', () => {
       const request = spec.buildRequests(
         DEFAULT_BANNER_BID_REQUESTS,