Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.topsort.com/llms.txt

Use this file to discover all available pages before exploring further.

If the retailer already is running ads using an ad server, it is possible to run it alongside Topsort using a fallback logic. This allows retailers to compare ad servers performance and increase fill-rates.

​
Use Cases

Fallback Logic

Use a secondary ad server when Topsort returns no winners, ensuring maximum fill rate

A/B Testing

Compare ad server performance using audience segments or traffic splits

​
How It Works

For instance, if the retailer is running banner ads using GAM (Google Ad Manager), they can set Topsort as the primary ad server to make sure their direct sold campaigns have priority over GAM’s demand. Ad requests and interactions coming from ads not served by Topsort can be reported to Topsort to see and compare metrics in one place.
1

Integrate with Topsort

Set up Topsort as your primary ad server using any of the integration methods (API, SDK, or low-code).
2

Request Topsort Ad First

Always request an ad from Topsort first in your ad serving logic.
3

Check for Winners

If Topsort returns winners, display the Topsort ad.
4

Fallback to Secondary

If no winners are returned, request an ad from your secondary ad server.

​
Implementation Example

async function displayAd() {
  try {
    const response = await fetch("https://api.topsort.com/v2/auctions", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        // Your auction request parameters
      }),
    });
    const auctionData = await response.json();

    if (auctionData?.results?.winners) {
      console.log("Topsort ad displayed.");
      return; // Exit early - Topsort ad is displayed
    } else {
      console.log("No Topsort ad available.");
    }
  } catch (error) {
    console.error("Error fetching Topsort ad:", error);
  }

  // Fallback to secondary network
  if (secondaryNetwork) {
    // Render ad from secondary network
    console.log("Displaying secondary ad.");
  } else {
    console.warn("No secondary ad network configured.");
  }
}

displayAd();

​
A/B Testing Approach

For A/B testing, modify the selection logic using:
  • Audience Segments - Route specific user segments to different ad servers
  • Traffic Split - Randomly assign a percentage of traffic to each ad server
Report all ad interactions (including from secondary ad servers) to Topsort to compare metrics in one unified dashboard.