ad-platform

VTEX

If you use VTEX as your e-commerce platform, you can integrate Topsort directly into your VTEX store to offer ad placements to your vendors. In this section, we will cover the steps to integrate Topsort with VTEX using the VTEX IO Toolbelt. This integration is composed by the following apps:

Catalog Integration
Auctions Integration (Sponsored Listings)
Events Integration

These apps work together to synchronize your catalog with Topsort, display sponsored products in search results, and track user interactions for reporting and optimization. Please note that the VTEX IO apps don’t support automatic updates.

Before you begin, ensure you have the following:

A VTEX account with administrative access.
The VTEX IO Toolbelt installed and configured.
A Topsort account with a Marketplace API Key and an Advanced API Key. You can create these in your Topsort dashboard under Settings > API Integration (check the section API Token and Devlogs for more details).

Open your terminal and log in to your VTEX account:

vtex login {YOUR_ACCOUNT_NAME}

Setting up Your API Key

We created the Topsort Services Settings app inside VTEX (topsortpartnercl.services), which provides an endpoint with the pre-configured API Key in an encrypted way. To setup topsortpartnercl.services you need to follow these steps:

Install topsortpartnercl.services using:
Terminal window
```
vtex install topsortpartnercl.services
```
Set the API-Key for topsortpartnercl.services:
- Go to the admin of your VTEX Workspace.
- Go to App > App Management and find the services app:
- Click on settings and add the API Key, then click on Save.

You can verify the installation by going to {{workspace__url}}/_v/ts/settings and checking out if the endpoint returns an encrypted hash. Other apps will access this endpoint to authorize to Topsort when making a request.

Importing Catalog into Topsort

You can integrate your VTEX catalog with Topsort using XML feed templates. This approach works by creating an XML template that defines your product data structure and generates a feed URL that Topsort can periodically fetch.

Prerequisites:

Access to your VTEX Admin panel
Administrative permissions to create and manage XML templates
Your Topsort Advanced API Key (contact your Topsort representative if you don’t have this)

Setup Steps:

Create XML Template in VTEX Admin
- Navigate to Store Settings > Channels > XML Integration in your VTEX Admin
- Create a new XML template that includes required product fields:
  - Product ID (required)
  - Product title/name (required)
  - Brand (required)
  - Image URL (required)
  - Price (required)
  - Description
  - Category path
  - Department
  - Category
  - Subcategory
  - SKU reference code
  - EAN/barcode
  - Product URL
Configure Essential Settings Configure these three essential settings as shown in the screenshot below:
- Select collection with all products: Choose the collection you created in the prerequisites
- Select to include inactive products: Check “Show out-of-stock (sold-out) SKUs in the results” to include inactive products
- Write the field names and check the required boxes: For each field (like Product ID), write the tag name and check the “Show Content” box next to it

Configure XML Structure As a suggestion, you can use the following template as a format:

<?xml version="1.0" encoding="UTF-8"?>
<feed>
  <entry>
    <id>product-id</id>
    <title>Product Name</title>
    <description>Product description</description>
    <productType>Category &gt; Subcategory</productType>
    <brand>Brand Name</brand>
    <skuReferenceCode>SKU123</skuReferenceCode>
    <ean>1234567890123</ean>
    <link>https://store.com/product-url</link>
    <imageLink>https://store.com/image.jpg</imageLink>
    <price>99.99</price>
  </entry>
</feed>

Generate and Test Feed URL Once configured, it might take up to 30 minutes for VTEX to update the catalog into the XML. After that, test the public URL for the XML feed to ensure it generates the expected XML output.

The public URL is: https://{your-workspace-name}.vtexcommercestable.com.br/XMLData/{name-of-the-xml-from-previous-step}.xml
Configure Topsort Integration Contact your Topsort representative to set up the XML feed integration with:
- Your XML feed URL
- Your Topsort Advanced API Key
- Synchronization schedule requirements

Best Practices:

Ensure your XML feed reflects real-time inventory and pricing changes
Use high-quality, publicly accessible image URLs
Maintain consistent category hierarchies using ” > ” separators
Validate that all required fields are populated for optimal ad performance

Tracking Events

The Events Integration app tracks user interactions within the promoted products and sends this data to Topsort. It captures key events such as:

Impressions: When a user sees a promoted product in a listing page (PLP) or section.
Clicks: When a user clicks on a promoted product or adds it to the cart.
Purchases: When an order is completed and confirmed to be successful.

Install the Events Integration app:
Terminal window
```
vtex install topsortpartnercl.events@1.x
```
Confirm the app installation by running:
Terminal window
```
vtex ls
```
You should see topsortpartnercl.events listed among the installed apps.
Access the VTEX Admin portal, navigate to Apps > My Apps, and find Topsort’s Events Integration.

VTEX

Setting up Your API Key

Importing Catalog into Topsort

Sponsored Listings in Search Results

Tracking Events