From 0afde569e3b15c61726a05d295814db61b9dc475 Mon Sep 17 00:00:00 2001 From: Rodrigo Alonso Date: Wed, 5 Oct 2022 22:44:39 -0300 Subject: [PATCH 01/13] chore(v2/events): add entity field --- topsort-api-v2.yml | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index 7a0f9e8..7f0a5a4 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -571,6 +571,23 @@ components: The search string provided by the user in the page where this event occurred, if applicable. This search string must match the searchQuery field that was provided in the auction request (if provided). minLength: 1 + Entity: + type: object + description: The entity associated with the promotable over which the interaction occurred. + required: + - id + - type + additionalProperties: false + properties: + id: + type: string + description: The marketplace's ID of the entity associated with the interaction. + minLength: 1 + type: + enum: + - product + - vendor + description: The type of entity associated with the interaction. EventsRequest: type: object additionalProperties: false @@ -630,7 +647,9 @@ components: Impression: type: object description: > - An impression means an ad has become visible to the consumer. + An impression means a promotable has become visible to the consumer. + For promoted entities, include the `resolvedBidId` field from the `/v2/auctions` response. + For unpromoted entities, include the `entity` field to describe what was seen. In case you cannot send an impression when the product becomes visible, send us an impression event when the product was rendered in the HTML or, if that's also not possible, when your API returns the results. It is important to select the most specific event so that your vendors have more accurate CTR metrics, which will allow them to better predict their campaigns. required: @@ -643,6 +662,8 @@ components: type: string description: If the impression is over an ad promotion, this is the `resolvedBidId` field received from the `/auctions` request. example: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= + entity: + $ref: '#/components/schemas/Entity' placement: $ref: '#/components/schemas/Placement' occurredAt: @@ -665,7 +686,9 @@ components: example: eb874c98-bf4d-40a9-ae6d-fcf4cecb535c Click: description: > - A click is sent to Topsort when the consumer has clicked on an ad. + A click is sent to Topsort when the consumer has clicked on a promotable. + For promoted entities, include the `resolvedBidId` field from the `/v2/auctions` response. + For unpromoted entities, include the `entity` field to describe what was clicked. Topsort charges the vendor and pays the marketplace for clicks on ads in promoted placements on the marketplace app. type: object required: @@ -678,6 +701,8 @@ components: type: string description: If the click is over an ad promotion, this is the `resolvedBidId` field received from the `/auctions` request. example: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= + entity: + $ref: '#/components/schemas/Entity' placement: $ref: '#/components/schemas/Placement' occurredAt: From 12736d4f2aaac43f6adefcf95990e6b40e5af886 Mon Sep 17 00:00:00 2001 From: Rodrigo Alonso Date: Wed, 5 Oct 2022 22:52:24 -0300 Subject: [PATCH 02/13] chore: add entities descriptions to arrays --- topsort-api-v2.yml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index 7f0a5a4..eb181e5 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -594,18 +594,32 @@ components: properties: impressions: type: array + description: > + An impression means a promotable has become visible to the consumer. + For promoted entities, include the `resolvedBidId` field from the `/v2/auctions` response. + For unpromoted entities, include the `entity` field to describe what was seen. + In case you cannot send an impression when the product becomes visible, send us an impression event when the product was rendered in the HTML or, if that's also not possible, when your API returns the results. + It is important to select the most specific event so that your vendors have more accurate CTR metrics, which will allow them to better predict their campaigns. items: $ref: '#/components/schemas/Impression' minItems: 1 maxItems: 50 clicks: type: array + description: > + A click is sent to Topsort when the consumer has clicked on a promotable. + For promoted entities, include the `resolvedBidId` field from the `/v2/auctions` response. + For unpromoted entities, include the `entity` field to describe what was clicked. + Topsort charges the vendor and pays the marketplace for clicks on ads in promoted placements on the marketplace app. items: $ref: '#/components/schemas/Click' minItems: 1 maxItems: 50 purchases: type: array + description: > + A purchase is sent to Topsort once a marketplace customer places an order. + These events are used to measure the effectiveness of an ad campaign. items: $ref: '#/components/schemas/Purchase' minItems: 1 From 12e58f5129db1e3a9cfd0ecce3e0a2a4b92e672c Mon Sep 17 00:00:00 2001 From: Rodrigo Alonso Date: Wed, 5 Oct 2022 22:53:34 -0300 Subject: [PATCH 03/13] chore: spacing --- topsort-api-v2.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index eb181e5..2aae61e 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -596,8 +596,10 @@ components: type: array description: > An impression means a promotable has become visible to the consumer. + For promoted entities, include the `resolvedBidId` field from the `/v2/auctions` response. For unpromoted entities, include the `entity` field to describe what was seen. + In case you cannot send an impression when the product becomes visible, send us an impression event when the product was rendered in the HTML or, if that's also not possible, when your API returns the results. It is important to select the most specific event so that your vendors have more accurate CTR metrics, which will allow them to better predict their campaigns. items: @@ -608,8 +610,10 @@ components: type: array description: > A click is sent to Topsort when the consumer has clicked on a promotable. + For promoted entities, include the `resolvedBidId` field from the `/v2/auctions` response. For unpromoted entities, include the `entity` field to describe what was clicked. + Topsort charges the vendor and pays the marketplace for clicks on ads in promoted placements on the marketplace app. items: $ref: '#/components/schemas/Click' @@ -619,6 +623,7 @@ components: type: array description: > A purchase is sent to Topsort once a marketplace customer places an order. + These events are used to measure the effectiveness of an ad campaign. items: $ref: '#/components/schemas/Purchase' From 2a10420422e825597b7230592de34fd64e812f21 Mon Sep 17 00:00:00 2001 From: Rodrigo Alonso Date: Wed, 5 Oct 2022 22:54:54 -0300 Subject: [PATCH 04/13] chore: spacing --- topsort-api-v2.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index 2aae61e..d62f533 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -597,9 +597,11 @@ components: description: > An impression means a promotable has become visible to the consumer. + For promoted entities, include the `resolvedBidId` field from the `/v2/auctions` response. For unpromoted entities, include the `entity` field to describe what was seen. + In case you cannot send an impression when the product becomes visible, send us an impression event when the product was rendered in the HTML or, if that's also not possible, when your API returns the results. It is important to select the most specific event so that your vendors have more accurate CTR metrics, which will allow them to better predict their campaigns. items: @@ -611,9 +613,11 @@ components: description: > A click is sent to Topsort when the consumer has clicked on a promotable. + For promoted entities, include the `resolvedBidId` field from the `/v2/auctions` response. For unpromoted entities, include the `entity` field to describe what was clicked. + Topsort charges the vendor and pays the marketplace for clicks on ads in promoted placements on the marketplace app. items: $ref: '#/components/schemas/Click' @@ -624,6 +628,7 @@ components: description: > A purchase is sent to Topsort once a marketplace customer places an order. + These events are used to measure the effectiveness of an ad campaign. items: $ref: '#/components/schemas/Purchase' From 84162caa095db231d8fa03e889bcb6a479251427 Mon Sep 17 00:00:00 2001 From: Rodrigo Alonso Date: Wed, 5 Oct 2022 23:01:31 -0300 Subject: [PATCH 05/13] chore: some markdown --- topsort-api-v2.yml | 35 ++++++++--------------------------- 1 file changed, 8 insertions(+), 27 deletions(-) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index d62f533..f9b8388 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -185,9 +185,14 @@ paths: requestBody: description: > Use the `/events` endpoint to notify Topsort about significant consumer interactions on the marketplace app: - impressions — ad promotions become visible to the consumer; - clicks — the consumer clicks on an ad promotion; - and purchases — the consumer buys some products. + + - **Impressions** — an impression means a promotable has become visible to the consumer. + - **Clicks** — a click is sent to Topsort when the consumer has clicked on a promotable. + - **Purchases** — a purchase is sent to Topsort once a consumer places an order. + + + For promoted entities, include the `resolvedBidId` field from the `/v2/auctions` response. + For unpromoted entities, include the `entity` field to describe what was interacted with. content: application/json: schema: @@ -594,42 +599,18 @@ components: properties: impressions: type: array - description: > - An impression means a promotable has become visible to the consumer. - - - For promoted entities, include the `resolvedBidId` field from the `/v2/auctions` response. - For unpromoted entities, include the `entity` field to describe what was seen. - - - In case you cannot send an impression when the product becomes visible, send us an impression event when the product was rendered in the HTML or, if that's also not possible, when your API returns the results. - It is important to select the most specific event so that your vendors have more accurate CTR metrics, which will allow them to better predict their campaigns. items: $ref: '#/components/schemas/Impression' minItems: 1 maxItems: 50 clicks: type: array - description: > - A click is sent to Topsort when the consumer has clicked on a promotable. - - - For promoted entities, include the `resolvedBidId` field from the `/v2/auctions` response. - For unpromoted entities, include the `entity` field to describe what was clicked. - - - Topsort charges the vendor and pays the marketplace for clicks on ads in promoted placements on the marketplace app. items: $ref: '#/components/schemas/Click' minItems: 1 maxItems: 50 purchases: type: array - description: > - A purchase is sent to Topsort once a marketplace customer places an order. - - - These events are used to measure the effectiveness of an ad campaign. items: $ref: '#/components/schemas/Purchase' minItems: 1 From d09ceef4f6bd352a01e9338680c5e980a17ffba3 Mon Sep 17 00:00:00 2001 From: Rodrigo Alonso Date: Wed, 5 Oct 2022 23:03:37 -0300 Subject: [PATCH 06/13] chore: string literal formatting --- topsort-api-v2.yml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index f9b8388..97bce4d 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -183,14 +183,12 @@ paths: summary: Report events operationId: reportEvents requestBody: - description: > + description: | # Pipe preserves newlines Use the `/events` endpoint to notify Topsort about significant consumer interactions on the marketplace app: - - **Impressions** — an impression means a promotable has become visible to the consumer. - **Clicks** — a click is sent to Topsort when the consumer has clicked on a promotable. - **Purchases** — a purchase is sent to Topsort once a consumer places an order. - For promoted entities, include the `resolvedBidId` field from the `/v2/auctions` response. For unpromoted entities, include the `entity` field to describe what was interacted with. content: From 3cb7e9e84f4ec0fb9409d2bf27827b9576e838e6 Mon Sep 17 00:00:00 2001 From: Rodrigo Alonso Date: Wed, 5 Oct 2022 23:05:20 -0300 Subject: [PATCH 07/13] chore: replace "promoted entities" with "promoted interactions" --- topsort-api-v2.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index 97bce4d..267f9b5 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -189,8 +189,8 @@ paths: - **Clicks** — a click is sent to Topsort when the consumer has clicked on a promotable. - **Purchases** — a purchase is sent to Topsort once a consumer places an order. - For promoted entities, include the `resolvedBidId` field from the `/v2/auctions` response. - For unpromoted entities, include the `entity` field to describe what was interacted with. + For promoted interactions, include the `resolvedBidId` field from the `/v2/auctions` response. + For unpromoted interactions, include the `entity` field to describe what was interacted with. content: application/json: schema: From bf99cb9082d16226b244ba2f20bdec3a5297d2a4 Mon Sep 17 00:00:00 2001 From: Rodrigo Alonso Date: Wed, 5 Oct 2022 23:08:24 -0300 Subject: [PATCH 08/13] fix: type for enum --- topsort-api-v2.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index 267f9b5..4251429 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -587,10 +587,11 @@ components: description: The marketplace's ID of the entity associated with the interaction. minLength: 1 type: + type: string + description: The type of entity associated with the interaction. enum: - product - vendor - description: The type of entity associated with the interaction. EventsRequest: type: object additionalProperties: false From bc17d0bf0a28d2bd68e9441ca260cacf7ff99016 Mon Sep 17 00:00:00 2001 From: Rodrigo Alonso Date: Wed, 5 Oct 2022 23:11:14 -0300 Subject: [PATCH 09/13] fix: formatting --- topsort-api-v2.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index 4251429..2c50742 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -530,8 +530,9 @@ components: properties: path: type: string - description: > + description: | URL path of the page triggering the event. + For web apps, this can be obtained in JS using `window.location.pathname`. For mobile apps, use the deep link for the current view, if available. From 27b0344057151fc608afa1c1402d67183c8f493c Mon Sep 17 00:00:00 2001 From: Rodrigo Alonso Date: Wed, 5 Oct 2022 23:14:35 -0300 Subject: [PATCH 10/13] fix: fix placement.productId descriptiob --- topsort-api-v2.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index 2c50742..eb74f26 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -560,8 +560,8 @@ components: productId: type: string description: > - The ID of the product associated to this event. - This field is used to disambiguate between products from the same PDP. + The ID of the product associated to the page in which this event occurred, if applicable. + This ID must match the ID provided through the catalog service. minLength: 1 categoryId: type: string From ab9bf13a9620dacef0fc9352c739caad53cd6b6a Mon Sep 17 00:00:00 2001 From: Rodrigo Alonso Date: Wed, 5 Oct 2022 23:18:56 -0300 Subject: [PATCH 11/13] chore: update tag description --- topsort-api-v2.yml | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index eb74f26..03e1eb5 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -26,10 +26,9 @@ tags: - name: Auctions description: An auction determines which products should be promoted based on the vendors' bids. - name: Events (Beta) - description: > - **The specification details, particularly around unpromoted events and placement data, will change in the short term.** - **Please use [Events V1](https://openapi.topsort.com/api/v1#operation/reportEvent) for now if you need a stable API to report events.** - + description: | + **The specification details, particularly around placement data, may change in the short term.** + **If this is not acceptable for your integration, please use [Events V1](https://openapi.topsort.com/api/v1#operation/reportEvent) as an alternative.** Significant consumer interactions on the marketplace app. - name: Models From bb18aed715451ff62ac8a2903821889915f25b71 Mon Sep 17 00:00:00 2001 From: Rodrigo Alonso Date: Fri, 7 Oct 2022 10:17:52 -0300 Subject: [PATCH 12/13] chore: update description for impressions --- topsort-api-v2.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index 16a134e..8bb5f98 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -182,9 +182,9 @@ paths: summary: Report events operationId: reportEvents requestBody: - description: | # Pipe preserves newlines + description: | Use the `/events` endpoint to notify Topsort about significant consumer interactions on the marketplace app: - - **Impressions** — an impression means a promotable has become visible to the consumer. + - **Impressions** — a set of impressions means such promotables have become visible to the consumer. - **Clicks** — a click is sent to Topsort when the consumer has clicked on a promotable. - **Purchases** — a purchase is sent to Topsort once a consumer places an order. From bb01d01ae8084056a19d3ab3a6d8de8188bdcce2 Mon Sep 17 00:00:00 2001 From: Rodrigo Alonso Date: Fri, 7 Oct 2022 10:25:27 -0300 Subject: [PATCH 13/13] chore: describe what happens for promoted events --- topsort-api-v2.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index 8bb5f98..b894325 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -588,7 +588,9 @@ components: minLength: 1 Entity: type: object - description: The entity associated with the promotable over which the interaction occurred. + description: > + The entity associated with the promotable over which the interaction occurred. + It will be ignored if `resolvedBidId` is not blank. required: - id - type