Events are the flow of data through which Topsort can track auction-centered information from your app so it can keep track of clicks and bill vendors properly. They are also necessary to properly inform vendors about campaigns' performance: CTR, CPC, ROAS, etc.

Topsort periodically updates this performance information for vendors so they can make informed decisions when managing their campaigns.

📘

Prerequisites

Go to API Reference / Report an event

Reporting Events

There's 3 types of events which should be reported to Topsort: impressions, clicks and purchases. Next sections describe what, when and how to report.

Events may be sent deferred. If this is the case, you must include the timestamp of the instant when the event occurred, otherwise Topsort will assume the report was done synchronously and analytics data will be skewed.

For each of these event requests, you must include the authorization header as explained here.

Impressions

Every time a promotable element (e.g. product, banner) is rendered in a promotable location (i.e. a location where auction results may be rendered) on a customers' screen, we count it as one impression.
You should report an impression for a product every time that it is rendered on your customers' screen, even if it was not promoted. Often your app will render multiple products at once; for this reason, and to reduce the number of requests and bandwidth required, the impressions events may include multiple impressions.

When reporting an impression for a promoted product, you must include the auction ID associated with that promotion as well as the session ID. This way Topsort will be able to attribute impressions and properly compute CTR, both of which are provided to vendors.

Go to API Reference / Report an impression

Request Fields

The following are the absolute minimum fields that need to be set to report impressions:

NameTypeDescription
eventTypestringDiscriminator for the type of event. Must be "Impression".
sessionobjectThe session object allows correlating user activity during a session whether or not they are actually logged in.
session.sessionIdstringThe session ID is a long term identifier for a user device. This field should persist over long periods of time.
impressionsarrayDetails for each impression.
impressions[*].placementobjectWhere was this impression placed in the app.
impressions[*].placement.pagestringA marketplace assigned name for a page.
impressions[*].productIdstringThe ID of the product that was rendered.
impressions[*].auctionIdoptionalRequired for promoted products. Must be the ID of the auction for which this product was a winner.
occurredAtdate-timeRFC3339 formatted timestamp of the instant when the impression occurred, including UTC offset.

Impressions Response

These are the fields returned by Topsort as a result of a set of impressions being reported.

NameTypeDescription
impressions[*].idstringThe impression ID you provided, if any.
impressions[*].impressionIdstringA unique Topsort ID for a specific impression.

Clicks

When a product or any of its buttons (e.g. add to cart) is clicked by a customer, we count this as a click.
You should report all clicks over listings, even if they are not promoted.

When reporting a click for a promoted product, you must include the auction ID associated with that promotion as well as the session ID. This way Topsort will be able to attribute clicks and properly compute CTR, CPC and the conversion rate, all of which are provided to vendors.

Go to API Reference / Report a click

Request Fields

The following are the absolute minimum fields that need to be set to report a click:

NameTypeDescription
eventTypestringDiscriminator for the type of event. Must be "Click".
sessionobjectThe session object allows correlating user activity during a session whether or not they are actually logged in.
session.sessionIdstringThe session ID is a long term identifier for a user device. This field should persist over long periods of time.
placementobjectWhat was the ad placement in the app.
placement.pagestringA marketplace assigned name for a page.
productIdstringThe ID of the product that was clicked.
auctionIdoptionalThe Topsort ID for the auction where this product was a winner.
occurredAtdate-timeRFC3339 formatted timestamp of the instant when the click occurred, including UTC offset.

Clicks Response

These are the fields returned by Topsort as a result of a click being reported.

NameTypeDescription
idstringThe click ID you provided, if any.
clickIdstringA unique Topsort ID for a specific click.

Purchases

Every time a customer makes a payment for an products order, we count it as one purchase.
You should report all customer purchases, even if they were not promoted.

When reporting a purchase, you must include the session ID used with other events (you may include the auction ID associated with that promotion as well which may help with disambiguation but this is not required). This way Topsort will be able to attribute purchases to clicks and properly compute ROAS and conversion rate, both of which are provided to vendors.

Go to API Reference / Report a purchase

Request Fields

The following are the absolute minimum fields that need to be set to report a purchase:

NameTypeDescription
eventTypestringDiscriminator for the type of event. Must be "Purchase".
sessionobjectThe session object allows correlating user activity during a session whether or not they are actually logged in.
session.session_idstringThe session ID is a long term identifier for a user device. This field should persist over long periods of time.
idstringThe marketplace assigned ID for the order.
purchasedAtdate-timeRFC3339 formatted timestamp of the instant when the purchase occurred, including UTC offset.
itemsarrayItems purchased.
items[*].productIdstringThe ID of the item that was purchase.
items[*].unitPriceintegerThe price of a single item in minor currency units. For example, in the US (currency code "USD") the unit price is specified in cents.

Purchases Response

These are the fields returned by Topsort as a result of a purchase being reported.

NameTypeDescription
idstringThe order ID you provided, if any.
purchaseIdstringA unique Topsort ID for a specific purchase.