End to end API example

Before diving in, it’s important to realize that this article describes just one situation. The Topsort platform is designed to support different use-cases and marketplace-vendor relationships.

In this tutorial you’ll play the role of marketplace owner. On your marketplace a variety of vendors sell different products.

Many of these vendors are interested in boosting their sales and promoting some of their products.

After a discussion with your team you decide there are two ways products can be promoted in your marketplace. You want to allow:

• A maximum of 2 promoted products at the top of the search results.
• A maximum of 4 promoted products in a highlighted section on the homepage.

To make this a fully functioning system, a number of components are required:

1. A catalog of vendors, categories and products.
2. A way for vendors to create and manage campaigns and make products available for promotion.
3. Auctions to decide which products get to be promoted in the marketplace.

Finally, to calculate campaign performance it’s necessary to collect events like clicks and purchases (in a privacy-friendly manner of course).

View requests in the web inspector

Keep your web inspector open to see the network requests. Also, remember to change the api keys to your own!

The catalog

There are several ways for the catalog to be constructed. Topsort can:

1. Pull data from product feeds.
2. Automatically import products when they pass through the proxy.
3. Receive product data from the APIs.

In this article we’ll use the API.

Every product always belongs to at least one vendor. By using the product upsert endpoint, we can populate vendors, products and categories in one go.

Example request

Run code

Campaigns

Next up, we need to create a campaign. The campaign will additionally hold the bids (products) that are available for promotion. In this example we use the product we created in the previous request using the autoBidder.

Example request

Run code

Auctions

The marketplace needs to run an auction every time it wants to include promoted products in a request.

In this situation it will need to run auctions when the homepage is requested or when users search for products.

When an auction is run, Topsort will look at the triggered bids from the available campaigns and determine the ones that win.

Auctions are fully customizable.

For example, a search results auction request could look like this:

Example request

Run code

One important element is the resolvedBidId. This is an ID that Topsort provides and it identifies the winning bid.

When sending analytics events to Topsort, you will need to include this ID in order to attribute these events to the right campaigns.

Analytics

Now that an auction has been run, it’s important to keep track of the results. If a user ends up purchasing a promoted product, that sale needs to be attributed to the right campaign. This will allow vendors to track campaign performance.

There are three kinds of events that are tracked: Impressions, Clicks and Purchases.

Topsort provides several libraries for different platforms to make it easy to track these events.

• Web: analytics.js
• Android: analytics.kotlin
• iOS: topsort.swift

As before, the API can also be used directly. This is also where the resolvedBidId comes in.

In the following example, a request is sent that contains a single impression, click and purchase that are all attributed to the first bid of our search results auction.

Example request

Run code

Summary

And with the sending of that event, we have gone concluded this guide. We discussed the basics of a Topsort integration, namely:

• Importing a catalog.
• Creating a campaign.
• Running an auction.
• Sending events to Topsort.

If you have any questions or comments, feel free to contact us.