From 3d3b972f98f81da17ab2d9f862da836016f82226 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Agust=C3=ADn=20Esp=C3=ADldora=20Vial?= <42187995+agustinespildora@users.noreply.github.com> Date: Mon, 19 Aug 2024 10:18:18 -0400 Subject: [PATCH 01/23] feat: added topsort destination docs (#2) --- .../destinations/catalog/topsort/index.md | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 src/connections/destinations/catalog/topsort/index.md diff --git a/src/connections/destinations/catalog/topsort/index.md b/src/connections/destinations/catalog/topsort/index.md new file mode 100644 index 0000000000..cd56c79b0c --- /dev/null +++ b/src/connections/destinations/catalog/topsort/index.md @@ -0,0 +1,62 @@ +--- +title: Topsort Events Destination +id: 66ba237845b93b71bca2713e +beta: true +--- + + + +This is a destination for eCommerce sites that want to use Segment, or are already using it, to Track actions on their site. It helps you seamlessly integrate Topsort events for sponsored listings. + +[Topsort](https://www.topsort.com){:target="_blank"} is an AI-powered retail media platform enabling retailers and marketplaces to build their own high-performing ad networks, rivaling Google and Amazon. With its advanced auto-bidding algorithm and fast integration, Topsort provides an advertising solution that delivers exceptional returns on ad spend (ROAS) while respecting users privacy by being cookie-less. + +Events integration is one of the 3 steps to integrate with Topsort (see [Integration Overview](https://docs.topsort.com/reference/integration-overview){:target="_blank"} for more details). It allows marketplaces to have a full metrics report available through Topsort's Reporting API or directly in the [Topsort Manager Platform](https://app.topsort.com){:target="_blank"} dashboards. It also provides the necessary information for the Topsort team to display relevant ads, optimize budget consumption, attribute purchases and accomplish sellers conversion goals. + +This destination is maintained by Topsort. For any issues with the destination, [contact the Topsort Support team](mailto:support@topsort.com){:target="_blank"}. + + + +## Getting started + +### Intro to Topsort Events + +This destination will help you track the 3 main events Topsort needs to serve the most relevant ads and accomplish attribution for sponsored listings: `impressions`, `clicks` and `purchases`. Here is an explanation of what each one of these means to Topsort: + +1. **Impression**: Every time a user sees a promoted product in a listing page (PLP) or section. +2. **Click**: If the user then clicks or adds the promoted product to a cart, then a `click` should be triggered. +3. **Purchase**: Finally, when an order is completed and confirmed to be successful, a `purchase` event should be reported to Topsort. You can report a purchase whether it has promoted products or not. We will take care of filtering relevant promoted products inside the completed order given the information about promoted clicks. + +This destination has 3 default presets that map the Track events `'Product Viewed'`, `'Product Clicked'` and `'Order Completed'` to Topsort's `impression`, `click` and `purchase` events respectively. If you’re not familiar with the Segment Spec, take a look to understand what the [Track method](/docs/connections/spec/track/) does. The mappings in the Topsort destination are built based on the Segment [Ecommerce Spec](/docs/connections/spec/ecommerce/v2/). If you have different Segment Track events mapped to these action definitions then we can adapt this destination to your case. Once the destination is configured make sure to activate only the mappings relevant to your site, see point 5 of the [set up](#set-up-your-topsort-destination). + +You don't need to change anything about the way you report Track events to segment. The only extra field you need to provide, only for the `impression` and `click` events, is the `resolvedBidId` given in the winner promoted product (whether it is from the [Auctions API](https://docs.topsort.com/reference/createauctions){:target="_blank"} or the [proxy](https://docs.topsort.com/reference/listings-low-code){:target="_blank"} response). Please find below an example call to track a product listing page (PLP) click event with the `resolvedBidId` included: + +```js +analytics.track("Product Clicked", { + product_id: product.id, + name: product.name, + resolvedBidId: product.resolvedBidId +}); +``` + +### Set up your Topsort destination + +1. From the Segment web app, click **Catalog**, then click **Destinations**. +2. Search for "Topsort" in the Catalog, select it, and choose which of your sources to connect the destination to. +3. In the [Topsort Manager Platform](https://app.topsort.com){:target="_blank"}, go to [Settings > API Integration](https://app.topsort.com/new/es/marketplace/account-settings/api-integration){:target="_blank"} find or create your **Marketplace API Key** for auctions and events. +4. Go back to the Topsort destination on the segment app and enter the value for your **Marketplace API Key**. +5. Make sure to enable only the Track events relevant to your site and so that the events do not get duplicated with a single user action. For example: If you always trigger a `Product Clicked` event together with the `Product Added` event when a user makes a click in the "Add to cart" button, then you should enable only the `Product Clicked` event for the Topsort Destination. + +### Identify + +Topsort strongly recommends that you identify your logged-in users using Segment's [Identify method](/docs/connections/spec/identify/) and that you hash the user ID before sending it to Topsort. + +Please find an example Identify call below: + +```js +analytics.identify('361b1fdfbeaa9d64a13c033eb9f970dc6740f6bc', { + email: 'john.doe@example.com' +}); +``` + +Once a user is identified, each call to Segment's [Track method](/docs/connections/spec/track/) automatically records the user ID. +Users that are not logged in can be tracked using an [anonymousID](/docs/connections/spec/identify/#anonymous-id). From 8167d4627b0b830029cc0bc3c11c11adc260ef82 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Agust=C3=ADn=20Esp=C3=ADldora=20Vial?= <42187995+agustinespildora@users.noreply.github.com> Date: Tue, 20 Aug 2024 13:09:23 -0400 Subject: [PATCH 02/23] Remove comment Co-authored-by: forstisabella <92472883+forstisabella@users.noreply.github.com> --- src/connections/destinations/catalog/topsort/index.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/connections/destinations/catalog/topsort/index.md b/src/connections/destinations/catalog/topsort/index.md index cd56c79b0c..a31487d38c 100644 --- a/src/connections/destinations/catalog/topsort/index.md +++ b/src/connections/destinations/catalog/topsort/index.md @@ -4,10 +4,6 @@ id: 66ba237845b93b71bca2713e beta: true --- - - -This is a destination for eCommerce sites that want to use Segment, or are already using it, to Track actions on their site. It helps you seamlessly integrate Topsort events for sponsored listings. - [Topsort](https://www.topsort.com){:target="_blank"} is an AI-powered retail media platform enabling retailers and marketplaces to build their own high-performing ad networks, rivaling Google and Amazon. With its advanced auto-bidding algorithm and fast integration, Topsort provides an advertising solution that delivers exceptional returns on ad spend (ROAS) while respecting users privacy by being cookie-less. Events integration is one of the 3 steps to integrate with Topsort (see [Integration Overview](https://docs.topsort.com/reference/integration-overview){:target="_blank"} for more details). It allows marketplaces to have a full metrics report available through Topsort's Reporting API or directly in the [Topsort Manager Platform](https://app.topsort.com){:target="_blank"} dashboards. It also provides the necessary information for the Topsort team to display relevant ads, optimize budget consumption, attribute purchases and accomplish sellers conversion goals. From 815e9b576877b13dd082d7fe4fc07af96157e9f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Agust=C3=ADn=20Esp=C3=ADldora=20Vial?= <42187995+agustinespildora@users.noreply.github.com> Date: Tue, 20 Aug 2024 13:09:59 -0400 Subject: [PATCH 03/23] Syntax and spelling Co-authored-by: forstisabella <92472883+forstisabella@users.noreply.github.com> --- src/connections/destinations/catalog/topsort/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/connections/destinations/catalog/topsort/index.md b/src/connections/destinations/catalog/topsort/index.md index a31487d38c..f4e62a92e2 100644 --- a/src/connections/destinations/catalog/topsort/index.md +++ b/src/connections/destinations/catalog/topsort/index.md @@ -6,7 +6,7 @@ beta: true [Topsort](https://www.topsort.com){:target="_blank"} is an AI-powered retail media platform enabling retailers and marketplaces to build their own high-performing ad networks, rivaling Google and Amazon. With its advanced auto-bidding algorithm and fast integration, Topsort provides an advertising solution that delivers exceptional returns on ad spend (ROAS) while respecting users privacy by being cookie-less. -Events integration is one of the 3 steps to integrate with Topsort (see [Integration Overview](https://docs.topsort.com/reference/integration-overview){:target="_blank"} for more details). It allows marketplaces to have a full metrics report available through Topsort's Reporting API or directly in the [Topsort Manager Platform](https://app.topsort.com){:target="_blank"} dashboards. It also provides the necessary information for the Topsort team to display relevant ads, optimize budget consumption, attribute purchases and accomplish sellers conversion goals. +Setting up an events integration is one of the 3 steps to integrate with Topsort (see [Integration Overview](https://docs.topsort.com/reference/integration-overview){:target="_blank"} for more details). It allows marketplaces to have a full metrics report available through Topsort's Reporting API or directly in the [Topsort Manager Platform](https://app.topsort.com){:target="_blank"} dashboards. It also provides the necessary information for the Topsort team to display relevant ads, optimize budget consumption, attribute purchases and accomplish sellers' conversion goals. This destination is maintained by Topsort. For any issues with the destination, [contact the Topsort Support team](mailto:support@topsort.com){:target="_blank"}. From c9f4bf420e09d099b9bf3e10ca31cefc17158ea2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Agust=C3=ADn=20Esp=C3=ADldora=20Vial?= <42187995+agustinespildora@users.noreply.github.com> Date: Tue, 20 Aug 2024 13:10:23 -0400 Subject: [PATCH 04/23] Added description afterwards Co-authored-by: forstisabella <92472883+forstisabella@users.noreply.github.com> --- src/connections/destinations/catalog/topsort/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/connections/destinations/catalog/topsort/index.md b/src/connections/destinations/catalog/topsort/index.md index f4e62a92e2..ba13cbb609 100644 --- a/src/connections/destinations/catalog/topsort/index.md +++ b/src/connections/destinations/catalog/topsort/index.md @@ -6,6 +6,7 @@ beta: true [Topsort](https://www.topsort.com){:target="_blank"} is an AI-powered retail media platform enabling retailers and marketplaces to build their own high-performing ad networks, rivaling Google and Amazon. With its advanced auto-bidding algorithm and fast integration, Topsort provides an advertising solution that delivers exceptional returns on ad spend (ROAS) while respecting users privacy by being cookie-less. +This is a destination for eCommerce sites that want to use Segment or are already using it to Track actions on their site. It helps you seamlessly integrate Topsort events for sponsored listings. Setting up an events integration is one of the 3 steps to integrate with Topsort (see [Integration Overview](https://docs.topsort.com/reference/integration-overview){:target="_blank"} for more details). It allows marketplaces to have a full metrics report available through Topsort's Reporting API or directly in the [Topsort Manager Platform](https://app.topsort.com){:target="_blank"} dashboards. It also provides the necessary information for the Topsort team to display relevant ads, optimize budget consumption, attribute purchases and accomplish sellers' conversion goals. This destination is maintained by Topsort. For any issues with the destination, [contact the Topsort Support team](mailto:support@topsort.com){:target="_blank"}. From 058de973a6b3d48d5d7d4e36ae7cfea673c39fba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Agust=C3=ADn=20Esp=C3=ADldora=20Vial?= <42187995+agustinespildora@users.noreply.github.com> Date: Tue, 20 Aug 2024 13:10:37 -0400 Subject: [PATCH 05/23] delete comment Co-authored-by: forstisabella <92472883+forstisabella@users.noreply.github.com> --- src/connections/destinations/catalog/topsort/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/connections/destinations/catalog/topsort/index.md b/src/connections/destinations/catalog/topsort/index.md index ba13cbb609..24031754a8 100644 --- a/src/connections/destinations/catalog/topsort/index.md +++ b/src/connections/destinations/catalog/topsort/index.md @@ -11,7 +11,6 @@ Setting up an events integration is one of the 3 steps to integrate with Topsort This destination is maintained by Topsort. For any issues with the destination, [contact the Topsort Support team](mailto:support@topsort.com){:target="_blank"}. - ## Getting started From 639fb6c4b640d642862ae3845048c37046a7b6f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Agust=C3=ADn=20Esp=C3=ADldora=20Vial?= <42187995+agustinespildora@users.noreply.github.com> Date: Tue, 20 Aug 2024 13:10:55 -0400 Subject: [PATCH 06/23] Syntax and spelling Co-authored-by: forstisabella <92472883+forstisabella@users.noreply.github.com> --- src/connections/destinations/catalog/topsort/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/connections/destinations/catalog/topsort/index.md b/src/connections/destinations/catalog/topsort/index.md index 24031754a8..ca4cd79a8c 100644 --- a/src/connections/destinations/catalog/topsort/index.md +++ b/src/connections/destinations/catalog/topsort/index.md @@ -16,7 +16,7 @@ This destination is maintained by Topsort. For any issues with the destination, ### Intro to Topsort Events -This destination will help you track the 3 main events Topsort needs to serve the most relevant ads and accomplish attribution for sponsored listings: `impressions`, `clicks` and `purchases`. Here is an explanation of what each one of these means to Topsort: +This destination helps you track the 3 main events Topsort needs to serve the most relevant ads and accomplish attribution for sponsored listings: `impressions`, `clicks` and `purchases`. Here is an explanation of what each one of these means to Topsort: 1. **Impression**: Every time a user sees a promoted product in a listing page (PLP) or section. 2. **Click**: If the user then clicks or adds the promoted product to a cart, then a `click` should be triggered. From 5c98cb996949652b248eec269753c0aac45dc5c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Agust=C3=ADn=20Esp=C3=ADldora=20Vial?= <42187995+agustinespildora@users.noreply.github.com> Date: Tue, 20 Aug 2024 13:11:08 -0400 Subject: [PATCH 07/23] Syntax and spelling Co-authored-by: forstisabella <92472883+forstisabella@users.noreply.github.com> --- src/connections/destinations/catalog/topsort/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/connections/destinations/catalog/topsort/index.md b/src/connections/destinations/catalog/topsort/index.md index ca4cd79a8c..d96fcbbe96 100644 --- a/src/connections/destinations/catalog/topsort/index.md +++ b/src/connections/destinations/catalog/topsort/index.md @@ -24,7 +24,7 @@ This destination helps you track the 3 main events Topsort needs to serve the mo This destination has 3 default presets that map the Track events `'Product Viewed'`, `'Product Clicked'` and `'Order Completed'` to Topsort's `impression`, `click` and `purchase` events respectively. If you’re not familiar with the Segment Spec, take a look to understand what the [Track method](/docs/connections/spec/track/) does. The mappings in the Topsort destination are built based on the Segment [Ecommerce Spec](/docs/connections/spec/ecommerce/v2/). If you have different Segment Track events mapped to these action definitions then we can adapt this destination to your case. Once the destination is configured make sure to activate only the mappings relevant to your site, see point 5 of the [set up](#set-up-your-topsort-destination). -You don't need to change anything about the way you report Track events to segment. The only extra field you need to provide, only for the `impression` and `click` events, is the `resolvedBidId` given in the winner promoted product (whether it is from the [Auctions API](https://docs.topsort.com/reference/createauctions){:target="_blank"} or the [proxy](https://docs.topsort.com/reference/listings-low-code){:target="_blank"} response). Please find below an example call to track a product listing page (PLP) click event with the `resolvedBidId` included: +You don't need to change anything about the way you report Track events to Segment. The only extra field you need to provide, only for the `impression` and `click` events, is the `resolvedBidId` given in the winner promoted product (whether it is from the [Auctions API](https://docs.topsort.com/reference/createauctions){:target="_blank"} or the [proxy](https://docs.topsort.com/reference/listings-low-code){:target="_blank"} response). Please find below an example call to track a product listing page (PLP) click event with the `resolvedBidId` included: ```js analytics.track("Product Clicked", { From a48c2f868cc78c6979797235130efa3e7fcdafa1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Agust=C3=ADn=20Esp=C3=ADldora=20Vial?= <42187995+agustinespildora@users.noreply.github.com> Date: Tue, 20 Aug 2024 13:11:27 -0400 Subject: [PATCH 08/23] Syntax and spelling Co-authored-by: forstisabella <92472883+forstisabella@users.noreply.github.com> --- src/connections/destinations/catalog/topsort/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/connections/destinations/catalog/topsort/index.md b/src/connections/destinations/catalog/topsort/index.md index d96fcbbe96..bc038c4230 100644 --- a/src/connections/destinations/catalog/topsort/index.md +++ b/src/connections/destinations/catalog/topsort/index.md @@ -38,7 +38,7 @@ analytics.track("Product Clicked", { 1. From the Segment web app, click **Catalog**, then click **Destinations**. 2. Search for "Topsort" in the Catalog, select it, and choose which of your sources to connect the destination to. -3. In the [Topsort Manager Platform](https://app.topsort.com){:target="_blank"}, go to [Settings > API Integration](https://app.topsort.com/new/es/marketplace/account-settings/api-integration){:target="_blank"} find or create your **Marketplace API Key** for auctions and events. +3. In the [Topsort Manager Platform](https://app.topsort.com){:target="_blank"}, go to [Settings > API Integration](https://app.topsort.com/new/es/marketplace/account-settings/api-integration){:target="_blank"} to find or create your **Marketplace API Key** for auctions and events. 4. Go back to the Topsort destination on the segment app and enter the value for your **Marketplace API Key**. 5. Make sure to enable only the Track events relevant to your site and so that the events do not get duplicated with a single user action. For example: If you always trigger a `Product Clicked` event together with the `Product Added` event when a user makes a click in the "Add to cart" button, then you should enable only the `Product Clicked` event for the Topsort Destination. From 2aa03d9e617d0e1833961d0e18cc2f6758030360 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Agust=C3=ADn=20Esp=C3=ADldora=20Vial?= <42187995+agustinespildora@users.noreply.github.com> Date: Tue, 20 Aug 2024 13:11:38 -0400 Subject: [PATCH 09/23] Syntax and spelling Co-authored-by: forstisabella <92472883+forstisabella@users.noreply.github.com> --- src/connections/destinations/catalog/topsort/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/connections/destinations/catalog/topsort/index.md b/src/connections/destinations/catalog/topsort/index.md index bc038c4230..f018c9301c 100644 --- a/src/connections/destinations/catalog/topsort/index.md +++ b/src/connections/destinations/catalog/topsort/index.md @@ -39,7 +39,7 @@ analytics.track("Product Clicked", { 1. From the Segment web app, click **Catalog**, then click **Destinations**. 2. Search for "Topsort" in the Catalog, select it, and choose which of your sources to connect the destination to. 3. In the [Topsort Manager Platform](https://app.topsort.com){:target="_blank"}, go to [Settings > API Integration](https://app.topsort.com/new/es/marketplace/account-settings/api-integration){:target="_blank"} to find or create your **Marketplace API Key** for auctions and events. -4. Go back to the Topsort destination on the segment app and enter the value for your **Marketplace API Key**. +4. Return to the Topsort destination in the Segment app and enter the value for your **Marketplace API Key**. 5. Make sure to enable only the Track events relevant to your site and so that the events do not get duplicated with a single user action. For example: If you always trigger a `Product Clicked` event together with the `Product Added` event when a user makes a click in the "Add to cart" button, then you should enable only the `Product Clicked` event for the Topsort Destination. ### Identify From 99be1b6c1dea6d52244a60943da0d2c6848b24d3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Agust=C3=ADn=20Esp=C3=ADldora=20Vial?= <42187995+agustinespildora@users.noreply.github.com> Date: Tue, 20 Aug 2024 13:12:14 -0400 Subject: [PATCH 10/23] Syntax and spelling Co-authored-by: forstisabella <92472883+forstisabella@users.noreply.github.com> --- src/connections/destinations/catalog/topsort/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/connections/destinations/catalog/topsort/index.md b/src/connections/destinations/catalog/topsort/index.md index f018c9301c..11fcf10a2b 100644 --- a/src/connections/destinations/catalog/topsort/index.md +++ b/src/connections/destinations/catalog/topsort/index.md @@ -40,7 +40,7 @@ analytics.track("Product Clicked", { 2. Search for "Topsort" in the Catalog, select it, and choose which of your sources to connect the destination to. 3. In the [Topsort Manager Platform](https://app.topsort.com){:target="_blank"}, go to [Settings > API Integration](https://app.topsort.com/new/es/marketplace/account-settings/api-integration){:target="_blank"} to find or create your **Marketplace API Key** for auctions and events. 4. Return to the Topsort destination in the Segment app and enter the value for your **Marketplace API Key**. -5. Make sure to enable only the Track events relevant to your site and so that the events do not get duplicated with a single user action. For example: If you always trigger a `Product Clicked` event together with the `Product Added` event when a user makes a click in the "Add to cart" button, then you should enable only the `Product Clicked` event for the Topsort Destination. +5. Enable only the Track events relevant to your site and so that the events do not get duplicated with a single user action. For example, if you always trigger a `Product Clicked` event together with the `Product Added` event when a user makes a click in the "Add to cart" button, then you should enable only the `Product Clicked` event for the Topsort Destination. ### Identify From 47086c8f18fd31b717107ee3a6422417e5d91a24 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Agust=C3=ADn=20Esp=C3=ADldora=20Vial?= <42187995+agustinespildora@users.noreply.github.com> Date: Tue, 20 Aug 2024 13:12:25 -0400 Subject: [PATCH 11/23] Syntax and spelling Co-authored-by: forstisabella <92472883+forstisabella@users.noreply.github.com> --- src/connections/destinations/catalog/topsort/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/connections/destinations/catalog/topsort/index.md b/src/connections/destinations/catalog/topsort/index.md index 11fcf10a2b..bae84e7342 100644 --- a/src/connections/destinations/catalog/topsort/index.md +++ b/src/connections/destinations/catalog/topsort/index.md @@ -44,7 +44,7 @@ analytics.track("Product Clicked", { ### Identify -Topsort strongly recommends that you identify your logged-in users using Segment's [Identify method](/docs/connections/spec/identify/) and that you hash the user ID before sending it to Topsort. +Topsort recommends that you identify your logged-in users using Segment's [Identify method](/docs/connections/spec/identify/) and that you hash the user ID before sending it to Topsort. Please find an example Identify call below: From b41412faf40f7f67d237899e3ffc4c85066076dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Agust=C3=ADn=20Esp=C3=ADldora=20Vial?= <42187995+agustinespildora@users.noreply.github.com> Date: Wed, 21 Aug 2024 14:00:45 -0400 Subject: [PATCH 12/23] add snippet to populate action tables Co-authored-by: Thomas Gilbert <64277654+tcgilbert@users.noreply.github.com> --- src/connections/destinations/catalog/topsort/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/connections/destinations/catalog/topsort/index.md b/src/connections/destinations/catalog/topsort/index.md index bae84e7342..490b0c2b27 100644 --- a/src/connections/destinations/catalog/topsort/index.md +++ b/src/connections/destinations/catalog/topsort/index.md @@ -41,7 +41,7 @@ analytics.track("Product Clicked", { 3. In the [Topsort Manager Platform](https://app.topsort.com){:target="_blank"}, go to [Settings > API Integration](https://app.topsort.com/new/es/marketplace/account-settings/api-integration){:target="_blank"} to find or create your **Marketplace API Key** for auctions and events. 4. Return to the Topsort destination in the Segment app and enter the value for your **Marketplace API Key**. 5. Enable only the Track events relevant to your site and so that the events do not get duplicated with a single user action. For example, if you always trigger a `Product Clicked` event together with the `Product Added` event when a user makes a click in the "Add to cart" button, then you should enable only the `Product Clicked` event for the Topsort Destination. - +{% include components/actions-fields.html %} ### Identify Topsort recommends that you identify your logged-in users using Segment's [Identify method](/docs/connections/spec/identify/) and that you hash the user ID before sending it to Topsort. From 4a9df4d0aafedda2aad6e3e20d6fac3cb1fa8109 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Agust=C3=ADn=20Esp=C3=ADldora=20Vial?= <42187995+agustinespildora@users.noreply.github.com> Date: Wed, 21 Aug 2024 14:01:30 -0400 Subject: [PATCH 13/23] spelling and redaction Co-authored-by: forstisabella <92472883+forstisabella@users.noreply.github.com> --- src/connections/destinations/catalog/topsort/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/connections/destinations/catalog/topsort/index.md b/src/connections/destinations/catalog/topsort/index.md index 490b0c2b27..812c850cbb 100644 --- a/src/connections/destinations/catalog/topsort/index.md +++ b/src/connections/destinations/catalog/topsort/index.md @@ -18,9 +18,9 @@ This destination is maintained by Topsort. For any issues with the destination, This destination helps you track the 3 main events Topsort needs to serve the most relevant ads and accomplish attribution for sponsored listings: `impressions`, `clicks` and `purchases`. Here is an explanation of what each one of these means to Topsort: -1. **Impression**: Every time a user sees a promoted product in a listing page (PLP) or section. -2. **Click**: If the user then clicks or adds the promoted product to a cart, then a `click` should be triggered. -3. **Purchase**: Finally, when an order is completed and confirmed to be successful, a `purchase` event should be reported to Topsort. You can report a purchase whether it has promoted products or not. We will take care of filtering relevant promoted products inside the completed order given the information about promoted clicks. +- **Impression**: Every time a user sees a promoted product in a listing page (PLP) or section, you should trigger an `impressions` event. +- **Click**: If the user then clicks or adds the promoted product to a cart, you should trigger a `click` event. +- **Purchase**: When an order is completed and confirmed to be successful, report a `purchase` event to Topsort. You can report a purchase whether it has promoted products or not. Topsort takes care of filtering relevant promoted products inside the completed order given the information about promoted clicks. This destination has 3 default presets that map the Track events `'Product Viewed'`, `'Product Clicked'` and `'Order Completed'` to Topsort's `impression`, `click` and `purchase` events respectively. If you’re not familiar with the Segment Spec, take a look to understand what the [Track method](/docs/connections/spec/track/) does. The mappings in the Topsort destination are built based on the Segment [Ecommerce Spec](/docs/connections/spec/ecommerce/v2/). If you have different Segment Track events mapped to these action definitions then we can adapt this destination to your case. Once the destination is configured make sure to activate only the mappings relevant to your site, see point 5 of the [set up](#set-up-your-topsort-destination). From 9adb4f6c29673b237b3e0f1d9cb9ad79ab2b9a12 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Agust=C3=ADn=20Esp=C3=ADldora=20Vial?= <42187995+agustinespildora@users.noreply.github.com> Date: Wed, 21 Aug 2024 14:02:04 -0400 Subject: [PATCH 14/23] spelling and redaction Co-authored-by: forstisabella <92472883+forstisabella@users.noreply.github.com> --- src/connections/destinations/catalog/topsort/index.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/connections/destinations/catalog/topsort/index.md b/src/connections/destinations/catalog/topsort/index.md index 812c850cbb..15778c3a66 100644 --- a/src/connections/destinations/catalog/topsort/index.md +++ b/src/connections/destinations/catalog/topsort/index.md @@ -22,7 +22,9 @@ This destination helps you track the 3 main events Topsort needs to serve the mo - **Click**: If the user then clicks or adds the promoted product to a cart, you should trigger a `click` event. - **Purchase**: When an order is completed and confirmed to be successful, report a `purchase` event to Topsort. You can report a purchase whether it has promoted products or not. Topsort takes care of filtering relevant promoted products inside the completed order given the information about promoted clicks. -This destination has 3 default presets that map the Track events `'Product Viewed'`, `'Product Clicked'` and `'Order Completed'` to Topsort's `impression`, `click` and `purchase` events respectively. If you’re not familiar with the Segment Spec, take a look to understand what the [Track method](/docs/connections/spec/track/) does. The mappings in the Topsort destination are built based on the Segment [Ecommerce Spec](/docs/connections/spec/ecommerce/v2/). If you have different Segment Track events mapped to these action definitions then we can adapt this destination to your case. Once the destination is configured make sure to activate only the mappings relevant to your site, see point 5 of the [set up](#set-up-your-topsort-destination). +This destination has 3 default presets that map the Track events `'Product Viewed'`, `'Product Clicked'` and `'Order Completed'` to Topsort's `impression`, `click` and `purchase` events, respectively. If you’re not familiar with the Segment Spec, take a look to understand what the [Track method](/docs/connections/spec/track/) does. + +The mappings in the Topsort destination are built based on the Segment [Ecommerce Spec](/docs/connections/spec/ecommerce/v2/). If you have different Segment Track events mapped to these action definitions, then Topsport can adapt this destination to your case. Once the destination is configured, activate only the mappings relevant to your site. See point 5 of the [set up](#set-up-your-topsort-destination) for more details. You don't need to change anything about the way you report Track events to Segment. The only extra field you need to provide, only for the `impression` and `click` events, is the `resolvedBidId` given in the winner promoted product (whether it is from the [Auctions API](https://docs.topsort.com/reference/createauctions){:target="_blank"} or the [proxy](https://docs.topsort.com/reference/listings-low-code){:target="_blank"} response). Please find below an example call to track a product listing page (PLP) click event with the `resolvedBidId` included: From 93aee71f8596b9d9690cdcaa418f4a3560b5a9a3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Agust=C3=ADn=20Esp=C3=ADldora=20Vial?= <42187995+agustinespildora@users.noreply.github.com> Date: Wed, 21 Aug 2024 16:52:23 -0400 Subject: [PATCH 15/23] feat: added topsort destination docs (#3) --- src/connections/destinations/catalog/topsort/index.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/connections/destinations/catalog/topsort/index.md b/src/connections/destinations/catalog/topsort/index.md index 15778c3a66..eb153af306 100644 --- a/src/connections/destinations/catalog/topsort/index.md +++ b/src/connections/destinations/catalog/topsort/index.md @@ -44,9 +44,10 @@ analytics.track("Product Clicked", { 4. Return to the Topsort destination in the Segment app and enter the value for your **Marketplace API Key**. 5. Enable only the Track events relevant to your site and so that the events do not get duplicated with a single user action. For example, if you always trigger a `Product Clicked` event together with the `Product Added` event when a user makes a click in the "Add to cart" button, then you should enable only the `Product Clicked` event for the Topsort Destination. {% include components/actions-fields.html %} + ### Identify -Topsort recommends that you identify your logged-in users using Segment's [Identify method](/docs/connections/spec/identify/) and that you hash the user ID before sending it to Topsort. +For Segment's browser and mobile libraries Topsort recommends that you identify your logged-in users using Segment's [Identify method](/docs/connections/spec/identify/). Please find an example Identify call below: @@ -58,3 +59,5 @@ analytics.identify('361b1fdfbeaa9d64a13c033eb9f970dc6740f6bc', { Once a user is identified, each call to Segment's [Track method](/docs/connections/spec/track/) automatically records the user ID. Users that are not logged in can be tracked using an [anonymousID](/docs/connections/spec/identify/#anonymous-id). + +If you use a server side source please provide one of both options, anonymousId or userId. From f84a5295de358ced2c64e80eb6ed3314f41c8abe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Agust=C3=ADn=20Esp=C3=ADldora=20Vial?= <42187995+agustinespildora@users.noreply.github.com> Date: Wed, 21 Aug 2024 18:59:59 -0400 Subject: [PATCH 16/23] spelling and redaction fix Co-authored-by: forstisabella <92472883+forstisabella@users.noreply.github.com> --- src/connections/destinations/catalog/topsort/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/connections/destinations/catalog/topsort/index.md b/src/connections/destinations/catalog/topsort/index.md index eb153af306..901343fe19 100644 --- a/src/connections/destinations/catalog/topsort/index.md +++ b/src/connections/destinations/catalog/topsort/index.md @@ -60,4 +60,4 @@ analytics.identify('361b1fdfbeaa9d64a13c033eb9f970dc6740f6bc', { Once a user is identified, each call to Segment's [Track method](/docs/connections/spec/track/) automatically records the user ID. Users that are not logged in can be tracked using an [anonymousID](/docs/connections/spec/identify/#anonymous-id). -If you use a server side source please provide one of both options, anonymousId or userId. +If you use a server-side source please provide one or more identifiers: `anonymousId` or `userId`. From d603aef4aedb0433b40ccd137fee16d55d3ee895 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Agust=C3=ADn=20Esp=C3=ADldora=20Vial?= <42187995+agustinespildora@users.noreply.github.com> Date: Wed, 21 Aug 2024 19:00:17 -0400 Subject: [PATCH 17/23] spelling and redaction fix Co-authored-by: forstisabella <92472883+forstisabella@users.noreply.github.com> --- src/connections/destinations/catalog/topsort/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/connections/destinations/catalog/topsort/index.md b/src/connections/destinations/catalog/topsort/index.md index 901343fe19..9a2eb04437 100644 --- a/src/connections/destinations/catalog/topsort/index.md +++ b/src/connections/destinations/catalog/topsort/index.md @@ -43,6 +43,7 @@ analytics.track("Product Clicked", { 3. In the [Topsort Manager Platform](https://app.topsort.com){:target="_blank"}, go to [Settings > API Integration](https://app.topsort.com/new/es/marketplace/account-settings/api-integration){:target="_blank"} to find or create your **Marketplace API Key** for auctions and events. 4. Return to the Topsort destination in the Segment app and enter the value for your **Marketplace API Key**. 5. Enable only the Track events relevant to your site and so that the events do not get duplicated with a single user action. For example, if you always trigger a `Product Clicked` event together with the `Product Added` event when a user makes a click in the "Add to cart" button, then you should enable only the `Product Clicked` event for the Topsort Destination. + {% include components/actions-fields.html %} ### Identify From 00b71349ed73e02cc677d671e889b2aee3596ad0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Agust=C3=ADn=20Esp=C3=ADldora=20Vial?= <42187995+agustinespildora@users.noreply.github.com> Date: Wed, 21 Aug 2024 19:00:45 -0400 Subject: [PATCH 18/23] spelling and redaction fix Co-authored-by: forstisabella <92472883+forstisabella@users.noreply.github.com> --- src/connections/destinations/catalog/topsort/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/connections/destinations/catalog/topsort/index.md b/src/connections/destinations/catalog/topsort/index.md index 9a2eb04437..ed1f1e26db 100644 --- a/src/connections/destinations/catalog/topsort/index.md +++ b/src/connections/destinations/catalog/topsort/index.md @@ -24,7 +24,7 @@ This destination helps you track the 3 main events Topsort needs to serve the mo This destination has 3 default presets that map the Track events `'Product Viewed'`, `'Product Clicked'` and `'Order Completed'` to Topsort's `impression`, `click` and `purchase` events, respectively. If you’re not familiar with the Segment Spec, take a look to understand what the [Track method](/docs/connections/spec/track/) does. -The mappings in the Topsort destination are built based on the Segment [Ecommerce Spec](/docs/connections/spec/ecommerce/v2/). If you have different Segment Track events mapped to these action definitions, then Topsport can adapt this destination to your case. Once the destination is configured, activate only the mappings relevant to your site. See point 5 of the [set up](#set-up-your-topsort-destination) for more details. +The mappings in the Topsort destination are built based on the Segment [Ecommerce Spec](/docs/connections/spec/ecommerce/v2/). If you have different Segment Track events mapped to these action definitions, then Topsort can adapt this destination to your case. Once the destination is configured, activate only the mappings relevant to your site. See point 5 of the [set up](#set-up-your-topsort-destination) for more details. You don't need to change anything about the way you report Track events to Segment. The only extra field you need to provide, only for the `impression` and `click` events, is the `resolvedBidId` given in the winner promoted product (whether it is from the [Auctions API](https://docs.topsort.com/reference/createauctions){:target="_blank"} or the [proxy](https://docs.topsort.com/reference/listings-low-code){:target="_blank"} response). Please find below an example call to track a product listing page (PLP) click event with the `resolvedBidId` included: From 62242c24d31ef428cfa07717f61bf471fd961084 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Agust=C3=ADn=20Esp=C3=ADldora=20Vial?= <42187995+agustinespildora@users.noreply.github.com> Date: Fri, 23 Aug 2024 09:01:39 -0400 Subject: [PATCH 19/23] move section Co-authored-by: Thomas Gilbert <64277654+tcgilbert@users.noreply.github.com> --- src/connections/destinations/catalog/topsort/index.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/src/connections/destinations/catalog/topsort/index.md b/src/connections/destinations/catalog/topsort/index.md index ed1f1e26db..6b59831288 100644 --- a/src/connections/destinations/catalog/topsort/index.md +++ b/src/connections/destinations/catalog/topsort/index.md @@ -26,15 +26,6 @@ This destination has 3 default presets that map the Track events `'Product Viewe The mappings in the Topsort destination are built based on the Segment [Ecommerce Spec](/docs/connections/spec/ecommerce/v2/). If you have different Segment Track events mapped to these action definitions, then Topsort can adapt this destination to your case. Once the destination is configured, activate only the mappings relevant to your site. See point 5 of the [set up](#set-up-your-topsort-destination) for more details. -You don't need to change anything about the way you report Track events to Segment. The only extra field you need to provide, only for the `impression` and `click` events, is the `resolvedBidId` given in the winner promoted product (whether it is from the [Auctions API](https://docs.topsort.com/reference/createauctions){:target="_blank"} or the [proxy](https://docs.topsort.com/reference/listings-low-code){:target="_blank"} response). Please find below an example call to track a product listing page (PLP) click event with the `resolvedBidId` included: - -```js -analytics.track("Product Clicked", { - product_id: product.id, - name: product.name, - resolvedBidId: product.resolvedBidId -}); -``` ### Set up your Topsort destination From 8c25b290426c2c5e1247180205e05616630c74ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Agust=C3=ADn=20Esp=C3=ADldora=20Vial?= <42187995+agustinespildora@users.noreply.github.com> Date: Fri, 23 Aug 2024 09:02:04 -0400 Subject: [PATCH 20/23] remove automated status Co-authored-by: Thomas Gilbert <64277654+tcgilbert@users.noreply.github.com> --- src/connections/destinations/catalog/topsort/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/connections/destinations/catalog/topsort/index.md b/src/connections/destinations/catalog/topsort/index.md index 6b59831288..0c83dc3db0 100644 --- a/src/connections/destinations/catalog/topsort/index.md +++ b/src/connections/destinations/catalog/topsort/index.md @@ -1,7 +1,6 @@ --- title: Topsort Events Destination id: 66ba237845b93b71bca2713e -beta: true --- [Topsort](https://www.topsort.com){:target="_blank"} is an AI-powered retail media platform enabling retailers and marketplaces to build their own high-performing ad networks, rivaling Google and Amazon. With its advanced auto-bidding algorithm and fast integration, Topsort provides an advertising solution that delivers exceptional returns on ad spend (ROAS) while respecting users privacy by being cookie-less. From 71da8aa2d0c41b618d23f5ba0ca3d60eccfa0524 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Agust=C3=ADn=20Esp=C3=ADldora=20Vial?= <42187995+agustinespildora@users.noreply.github.com> Date: Fri, 23 Aug 2024 09:02:18 -0400 Subject: [PATCH 21/23] move section Co-authored-by: Thomas Gilbert <64277654+tcgilbert@users.noreply.github.com> --- src/connections/destinations/catalog/topsort/index.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/connections/destinations/catalog/topsort/index.md b/src/connections/destinations/catalog/topsort/index.md index 0c83dc3db0..bf47267bd2 100644 --- a/src/connections/destinations/catalog/topsort/index.md +++ b/src/connections/destinations/catalog/topsort/index.md @@ -35,7 +35,16 @@ The mappings in the Topsort destination are built based on the Segment [Ecommerc 5. Enable only the Track events relevant to your site and so that the events do not get duplicated with a single user action. For example, if you always trigger a `Product Clicked` event together with the `Product Added` event when a user makes a click in the "Add to cart" button, then you should enable only the `Product Clicked` event for the Topsort Destination. {% include components/actions-fields.html %} +### Track +You don't need to change anything about the way you report Track events to Segment. The only extra field you need to provide, only for the `impression` and `click` events, is the `resolvedBidId` given in the winner promoted product (whether it is from the [Auctions API](https://docs.topsort.com/reference/createauctions){:target="_blank"} or the [proxy](https://docs.topsort.com/reference/listings-low-code){:target="_blank"} response). Please find below an example call to track a product listing page (PLP) click event with the `resolvedBidId` included: + +```js +analytics.track("Product Clicked", { + product_id: product.id, + name: product.name, + resolvedBidId: product.resolvedBidId +}); ### Identify For Segment's browser and mobile libraries Topsort recommends that you identify your logged-in users using Segment's [Identify method](/docs/connections/spec/identify/). From 55077161d2045d994aa70c36fbb2392f3d61ea61 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Agust=C3=ADn=20Esp=C3=ADldora=20Vial?= <42187995+agustinespildora@users.noreply.github.com> Date: Fri, 23 Aug 2024 09:14:53 -0400 Subject: [PATCH 22/23] changed folder name to destination slug (#5) changed folder name and fix code block --- .../destinations/catalog/{topsort => actions-topsort}/index.md | 2 ++ 1 file changed, 2 insertions(+) rename src/connections/destinations/catalog/{topsort => actions-topsort}/index.md (99%) diff --git a/src/connections/destinations/catalog/topsort/index.md b/src/connections/destinations/catalog/actions-topsort/index.md similarity index 99% rename from src/connections/destinations/catalog/topsort/index.md rename to src/connections/destinations/catalog/actions-topsort/index.md index bf47267bd2..a557381d12 100644 --- a/src/connections/destinations/catalog/topsort/index.md +++ b/src/connections/destinations/catalog/actions-topsort/index.md @@ -45,6 +45,8 @@ analytics.track("Product Clicked", { name: product.name, resolvedBidId: product.resolvedBidId }); +``` + ### Identify For Segment's browser and mobile libraries Topsort recommends that you identify your logged-in users using Segment's [Identify method](/docs/connections/spec/identify/). From 85a0e38ebf8266475c4384e42ea3a60ad22c7f52 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Agust=C3=ADn=20Esp=C3=ADldora=20Vial?= <42187995+agustinespildora@users.noreply.github.com> Date: Fri, 23 Aug 2024 09:21:45 -0400 Subject: [PATCH 23/23] lint fix (#6) fix lint --- .../destinations/catalog/actions-topsort/index.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/connections/destinations/catalog/actions-topsort/index.md b/src/connections/destinations/catalog/actions-topsort/index.md index a557381d12..ba2f81f42b 100644 --- a/src/connections/destinations/catalog/actions-topsort/index.md +++ b/src/connections/destinations/catalog/actions-topsort/index.md @@ -10,7 +10,6 @@ Setting up an events integration is one of the 3 steps to integrate with Topsort This destination is maintained by Topsort. For any issues with the destination, [contact the Topsort Support team](mailto:support@topsort.com){:target="_blank"}. - ## Getting started ### Intro to Topsort Events @@ -21,11 +20,10 @@ This destination helps you track the 3 main events Topsort needs to serve the mo - **Click**: If the user then clicks or adds the promoted product to a cart, you should trigger a `click` event. - **Purchase**: When an order is completed and confirmed to be successful, report a `purchase` event to Topsort. You can report a purchase whether it has promoted products or not. Topsort takes care of filtering relevant promoted products inside the completed order given the information about promoted clicks. -This destination has 3 default presets that map the Track events `'Product Viewed'`, `'Product Clicked'` and `'Order Completed'` to Topsort's `impression`, `click` and `purchase` events, respectively. If you’re not familiar with the Segment Spec, take a look to understand what the [Track method](/docs/connections/spec/track/) does. +This destination has 3 default presets that map the Track events `'Product Viewed'`, `'Product Clicked'` and `'Order Completed'` to Topsort's `impression`, `click` and `purchase` events, respectively. If you’re not familiar with the Segment Spec, take a look to understand what the [Track method](/docs/connections/spec/track/) does. The mappings in the Topsort destination are built based on the Segment [Ecommerce Spec](/docs/connections/spec/ecommerce/v2/). If you have different Segment Track events mapped to these action definitions, then Topsort can adapt this destination to your case. Once the destination is configured, activate only the mappings relevant to your site. See point 5 of the [set up](#set-up-your-topsort-destination) for more details. - ### Set up your Topsort destination 1. From the Segment web app, click **Catalog**, then click **Destinations**. @@ -35,6 +33,7 @@ The mappings in the Topsort destination are built based on the Segment [Ecommerc 5. Enable only the Track events relevant to your site and so that the events do not get duplicated with a single user action. For example, if you always trigger a `Product Clicked` event together with the `Product Added` event when a user makes a click in the "Add to cart" button, then you should enable only the `Product Clicked` event for the Topsort Destination. {% include components/actions-fields.html %} + ### Track You don't need to change anything about the way you report Track events to Segment. The only extra field you need to provide, only for the `impression` and `click` events, is the `resolvedBidId` given in the winner promoted product (whether it is from the [Auctions API](https://docs.topsort.com/reference/createauctions){:target="_blank"} or the [proxy](https://docs.topsort.com/reference/listings-low-code){:target="_blank"} response). Please find below an example call to track a product listing page (PLP) click event with the `resolvedBidId` included: