Events 1.0

Events allow tracking campaign metrics like CTR, CPC, and ROAS. Report 3 event types to Topsort: impressions, clicks, and purchases. Begin with impressions and clicks.

๐Ÿ“˜

Prerequisites

โ—๏ธ

Events can be sent deferred. Include event timestamps if so.

Impressions

Count each rendered promotable element as an impression. Report impressions for all products, promoted or not. Impressions events can include multiple impressions. Include auction and session IDs for promoted products.

Requests

[impressions] is an Array ([ 1 .. 50 ] items), details of each item are as follows:

NameTypeDescription
opaqueUserIdstringLong-lived user ID for activity correlation
placementobjectImpression placement
placement.pathstringURL path of the page triggering the event.
resolvedBidIdoptionalResolvedBidId from /auctions request (from an ad promotion)
occurredAtdate-timeRFC3339 formatted timestamp with UTC offset
idstringThe marketplace's unique ID for the impression.

Responses

Fields returned by Topsort

NameTypeDescription
impressions[*].idstringProvided impression ID, if any
impressions[*].impressionIdstringUnique Topsort impression ID

๐Ÿ“˜

OpaqueUserId: Logged-in vs. Guest Users

Logged-in Users:
Use a hashed customer ID as the opaque user ID for tracking activities like impressions, clicks, and purchases.

Guest Users:
Generate a random ID (e.g. UUIDv4), store it in local storage with at least a month lifespan, and use it as the opaque user ID for tracking activities.

Clicks

Count product or button clicks as clicks. Report all clicks, even non-promoted ones. Include auction and session IDs for promoted products.

Request Fields

[clicks] is an Array ([ 1 .. 50 ] items), details of each item are as follows:

NameTypeDescription
resolvedBidIdoptionalResolvedBidId from /auctions request if ad promotion
placementobjectAd placement in the app
placement.pathstringURL path of the page triggering the event.
opaqueUserIdstringLong-lived user ID for activity correlation
occurredAtdate-timeRFC3339 formatted timestamp with UTC offset
idstringThe marketplace's unique ID for the click.

Clicks Response

Fields returned by Topsort:

NameTypeDescription
idstringProvided click ID, if any
clickIdstringUnique Topsort click ID

Purchases

Count each product order payment as a purchase. Report all purchases, even non-promoted ones. Include session ID and optional auction ID for promoted products.

Request Fields

Minimum fields for purchases:

NameTypeDescription
opaqueUserIdstringLong-lived user ID for activity correlation
idstringMarketplace-assigned order ID
occurredAtdate-timeRFC3339 formatted timestamp with UTC offset
itemsarrayPurchased items
items[*].productIdstringPurchased item ID
items[*].unitPriceintegerPrice of a single item in minor currency units
idstringThe marketplace's unique ID for the order.

Purchases Response

Fields returned by Topsort

NameTypeDescription
idstringProvided order ID, if any
purchaseIdstringUnique Topsort purchase ID