From d394b1c791ce7395195920b14fd95bbda2650f01 Mon Sep 17 00:00:00 2001 From: tomaslara-topsort Date: Tue, 28 Jul 2026 18:31:56 -0400 Subject: [PATCH 1/3] feat: add render event to /v2/events MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document the `rendered` event (IAB "render" — an ad placed in the DOM), reported via /v2/events alongside impressions, clicks and purchases: - add a `renders` array to EventsRequest (max 50) and a new `Render` schema - order render before impression to follow the funnel; add a request example --- topsort-api-v2.yml | 64 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 63 insertions(+), 1 deletion(-) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index b4bde63..62e723c 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -422,6 +422,8 @@ paths: description: > Use the `/events` endpoint to report user interactions and activity in on a marketplace: + - **Renders** — an ad was placed in the DOM. + - **Impressions** — a user viewed an asset. - **Clicks** — a user clicked on an asset. @@ -450,7 +452,7 @@ paths: Room](https://docs.topsort.com/knowledge-base/analytics/data-room/). operationId: reportEvents requestBody: - description: Event data including impressions, clicks, purchases, and page views. + description: Event data including renders, impressions, clicks, purchases, and page views. content: application/json: schema: @@ -2295,6 +2297,14 @@ components: additionalProperties: false minProperties: 1 properties: + renders: + title: Renders + description: An array of render events + type: array + minItems: 0 + maxItems: 50 + items: + $ref: "#/components/schemas/Render" impressions: title: Impressions description: An array of impression events @@ -2328,6 +2338,20 @@ components: items: $ref: "#/components/schemas/PageView" examples: + - renders: + - id: 3f2b9c14-7a1d-4e2b-9c3a-1b2c3d4e5f60 + occurredAt: "2019-01-01T12:59:58-05:00" + opaqueUserId: 71303ce0-de89-496d-8270-6434589615e8 + resolvedBidId: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= + placement: + path: /categories/dairy + position: 1 + page: 1 + pageSize: 15 + categoryIds: + - 9BLIe + deviceType: mobile + channel: onsite - impressions: - id: eb874c98-bf4d-40a9-ae6d-fcf4cecb535c occurredAt: "2019-01-01T12:59:59-05:00" @@ -2388,6 +2412,44 @@ components: value: dairy deviceType: mobile channel: onsite + Render: + title: Render + type: object + description: > + A render means an ad was placed in the DOM (IAB "rendered"), regardless of whether it + became viewable. Renders are for sponsored ads only, so `resolvedBidId` is required. + required: + - resolvedBidId + - occurredAt + - opaqueUserId + - id + additionalProperties: false + properties: + resolvedBidId: + $ref: "#/components/schemas/ResolvedBidID" + description: > + The `resolvedBidId` received from the `/v2/auctions` response. + placement: + $ref: "#/components/schemas/Placement" + occurredAt: + $ref: "#/components/schemas/occurredAt" + opaqueUserId: + $ref: "#/components/schemas/OpaqueUserID" + id: + $ref: "#/components/schemas/EventIdentifier" + page: + $ref: "#/components/schemas/Page" + deviceType: + $ref: "#/components/schemas/DeviceType" + channel: + type: string + description: Optional. The channel where the event occurred. + enum: + - onsite + - offsite + - instore + examples: + - onsite Impression: title: Impression type: object From f732bd65892c2c18c3c27dbe7e7b8eabc4daad5f Mon Sep 17 00:00:00 2001 From: tomaslara-topsort Date: Tue, 28 Jul 2026 18:49:18 -0400 Subject: [PATCH 2/3] fix: satisfy prettier and redocly strict lint MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - format the render additions with prettier - drop redundant `minimum: 0` from the qualityScores items schema (exclusiveMinimum: 0 already implies > 0). Unrelated to the render event — a pre-existing recommended-strict violation (no-mixed-number-range-constraints) that blocks the whole-file strict lint, fixed here to unblock this PR. --- topsort-api-v2.yml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index 62e723c..42e5fe9 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -1770,7 +1770,6 @@ components: type: number maximum: 1 exclusiveMinimum: 0 - minimum: 0 examples: - 0.75 format: double @@ -2416,8 +2415,8 @@ components: title: Render type: object description: > - A render means an ad was placed in the DOM (IAB "rendered"), regardless of whether it - became viewable. Renders are for sponsored ads only, so `resolvedBidId` is required. + A render means an ad was placed in the DOM (IAB "rendered"). Renders are for sponsored ads + only, so `resolvedBidId` is required. required: - resolvedBidId - occurredAt From 68eaa78c10bbae02f34121b4e5a661d7122e0540 Mon Sep 17 00:00:00 2001 From: tomaslara-topsort Date: Tue, 28 Jul 2026 19:10:03 -0400 Subject: [PATCH 3/3] fix: avoid DOM references for clarity --- topsort-api-v2.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index 42e5fe9..23dc370 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -422,7 +422,7 @@ paths: description: > Use the `/events` endpoint to report user interactions and activity in on a marketplace: - - **Renders** — an ad was placed in the DOM. + - **Renders** — an ad was rendered in the page. - **Impressions** — a user viewed an asset. @@ -2415,8 +2415,8 @@ components: title: Render type: object description: > - A render means an ad was placed in the DOM (IAB "rendered"). Renders are for sponsored ads - only, so `resolvedBidId` is required. + A render means an ad was inserted into the page (IAB "rendered"). Renders are for sponsored + ads only, so `resolvedBidId` is required. required: - resolvedBidId - occurredAt