Events API

Track impressions, clicks, and purchases to enable attribution and campaign optimization

The Events API allows you to send real-time user interaction data to Topsort. This data powers campaign attribution, reporting, and optimization algorithms.

Event Types

Topsort tracks three core event types:

Event	Description	When to Send
Impression	User views a promoted product	When a sponsored product is rendered on screen
Click	User clicks on a promoted product	When a user clicks a sponsored product
Purchase	User completes a transaction	When an order is confirmed

Integration Options

Direct API

Send events directly to Topsort’s Events API for maximum control and flexibility.

Analytics.js

Use our JavaScript SDK for easy client-side event tracking.

Twilio Segment

Route events through Segment if you’re already using it for analytics.

RudderStack

Integrate via RudderStack for unified event routing.

Key Concepts

Resolved Bid ID

The resolvedBidId is a unique identifier returned from the Auctions API that links an event to a specific auction winner. This is required for impression and click events to enable proper attribution.

{
  "impressions": [
    {
      "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVh...",
      "occurredAt": "2023-05-01T12:00:00Z"
    }
  ]
}

Event Attribution

Events are attributed to campaigns based on:

• Direct attribution: User interacts with a promoted product and converts
• Halo attribution: User views a promoted product but purchases a different product from the same vendor

Learn more about attribution models.

Implementation Steps

1. Store the Resolved Bid ID

   When displaying auction winners, store the resolvedBidId from the auction response.

2. Track Impressions

   Send an impression event when a sponsored product becomes visible to the user.

3. Track Clicks

   Send a click event when a user clicks on a sponsored product.

4. Track Purchases

   Send purchase events when orders are completed, including all purchased products.

Example: Sending Events

curl -X POST https://api.topsort.com/v2/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "impressions": [
      {
        "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4...",
        "occurredAt": "2023-05-01T12:00:00Z"
      }
    ],
    "clicks": [
      {
        "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4...",
        "occurredAt": "2023-05-01T12:00:05Z"
      }
    ]
  }'

Next Steps

• Events API Reference - Full API documentation
• Analytics.js Guide - Client-side tracking
• Attribution Models - Understanding attribution