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:
| Name | Type | Description |
|---|---|---|
| opaqueUserId | string | Long-lived user ID for activity correlation |
| placement | object | Impression placement |
| placement.path | string | URL path of the page triggering the event. |
| resolvedBidId | optional | ResolvedBidId from /auctions request (from an ad promotion) |
| occurredAt | date-time | RFC3339 formatted timestamp with UTC offset |
| id | string | The marketplace's unique ID for the impression. |
Responses
Fields returned by Topsort
| Name | Type | Description |
|---|---|---|
| impressions[*].id | string | Provided impression ID, if any |
| impressions[*].impressionId | string | Unique 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:
| Name | Type | Description |
|---|---|---|
| resolvedBidId | optional | ResolvedBidId from /auctions request if ad promotion |
| placement | object | Ad placement in the app |
| placement.path | string | URL path of the page triggering the event. |
| opaqueUserId | string | Long-lived user ID for activity correlation |
| occurredAt | date-time | RFC3339 formatted timestamp with UTC offset |
| id | string | The marketplace's unique ID for the click. |
Clicks Response
Fields returned by Topsort:
| Name | Type | Description |
|---|---|---|
| id | string | Provided click ID, if any |
| clickId | string | Unique 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:
| Name | Type | Description |
|---|---|---|
| opaqueUserId | string | Long-lived user ID for activity correlation |
| id | string | Marketplace-assigned order ID |
| occurredAt | date-time | RFC3339 formatted timestamp with UTC offset |
| items | array | Purchased items |
| items[*].productId | string | Purchased item ID |
| items[*].unitPrice | integer | Price of a single item in minor currency units |
| id | string | The marketplace's unique ID for the order. |
Purchases Response
Fields returned by Topsort
| Name | Type | Description |
|---|---|---|
| id | string | Provided order ID, if any |
| purchaseId | string | Unique Topsort purchase ID |