Topsort.php

A PHP Software Development Kit for interacting with the auctions and events endpoints

Topsort.php is a PHP Software Development Kit for Topsort’s auction and event tracking APIs.

Minimum requirements: PHP 7.3 and Composer.

Installation

Install with Composer:

composer require topsort/sdk

Or add to your composer.json:

{
  "require": {
    "topsort/sdk": "^4.0"
  }
}

Running an Auction

create_auction takes the number of slots, the product IDs, their quality scores, a category ID, a search query and the shopper’s opaqueUserId, in that order. Pass null for the arguments you do not use.

<?php
use Topsort\SDK;

$topsort_client = new SDK("my_api_key");

$opaque_user_id = "<YOUR_OPAQUE_USER_ID>"; // The same persistent id for this shopper
$products = ["i8bfHPJaxcAb3", "gDG0HV97ed2s"];
$slots = 1;

$auction_result = $topsort_client->create_auction($slots, $products, null, null, null, $opaque_user_id)->wait();
$winners = $auction_result["results"][0]["winners"];

For a banner auction, use create_banner_auction:

$banner_result = $topsort_client->create_banner_auction([
    "slots" => 1,
    "slotId" => "home-banner",
    "device" => "desktop",
    "opaqueUserId" => $opaque_user_id,
])->wait();

Reporting Events

Report a render when your server inserts a winner into the page, and an impression when that winner becomes visible to the shopper. Send the same opaqueUserId for a shopper on every auction and event, for example an id you keep in a cookie or your login session. A new id per event breaks attribution. The SDK does not generate one: the report_* methods throw a Topsort\InvalidEventException when it is missing or blank, before sending anything.

Each report_* method returns a promise, and nothing is sent until you call ->wait() on it. wait() blocks until Topsort responds, so where possible report events after the response has been sent to the shopper, for example after fastcgi_finish_request().

If the page also loads analytics.js, it already reports renders, impressions and clicks for every element with data-ts-resolved-bid. Do not report those events again with the SDK.

<?php
use Topsort\SDK;
use Topsort\TopsortException;

$topsort_client = new SDK("my_api_key");

$opaque_user_id = "<YOUR_OPAQUE_USER_ID>"; // The same id you sent on the auction
$placement = ["path" => "/categories/shoes"];
$winner = $winners[0]; // A winner from the auction result

Renders

A render records that a sponsored ad was inserted into the page, whether or not it ever becomes visible. Renders are sponsored-only, so report_render takes the resolvedBidId as its first argument and there is no entity field.

try {
    $topsort_client->report_render($winner["resolvedBidId"], [
        "opaqueUserId" => $opaque_user_id,
        "placement" => $placement,
    ])->wait();
} catch (TopsortException $e) {
    error_log($e->getMessage());
}

Impressions

An impression records that an ad or product became visible to the shopper. Your server cannot see that, so report it from the request your frontend sends when the element enters the viewport. report_impressions takes one impression per call.

try {
    $topsort_client->report_impressions([
        "resolvedBidId" => $winner["resolvedBidId"],
        "opaqueUserId" => $opaque_user_id,
        "placement" => $placement,
    ])->wait();
} catch (TopsortException $e) {
    error_log($e->getMessage());
}

Clicks

A click records that the shopper clicked an ad or product.

try {
    $topsort_client->report_click([
        "resolvedBidId" => $winner["resolvedBidId"],
        "opaqueUserId" => $opaque_user_id,
        "placement" => $placement,
    ])->wait();
} catch (TopsortException $e) {
    error_log($e->getMessage());
}

For organic results, send "entity" => ["type" => "product", "id" => "<product id>"] instead of resolvedBidId, in impressions and clicks.

Purchases

A purchase records the products a shopper bought. Topsort attributes it to the ads the shopper interacted with.

try {
    $topsort_client->report_purchase([
        "id" => "<Marketplace id for the purchase>",
        "opaqueUserId" => $opaque_user_id,
        "items" => [
            ["productId" => "gDG0HV97ed2s", "quantity" => 2, "unitPrice" => 10000],
        ],
    ])->wait();
} catch (TopsortException $e) {
    error_log($e->getMessage());
}

Every event also accepts an id, generated by the SDK when you omit it, and an occurredAt DateTime, which defaults to the current time. See the events API reference for every event field.

Handling Errors

All SDK errors extend Topsort\TopsortException, so one catch handles them:

• Topsort\InvalidEventException is thrown by the report_* call itself when the event is invalid, before anything is sent. Keep the call inside the try, not only the ->wait().
• Topsort\TopsortException is thrown by ->wait() when the API rejects the request or cannot be reached. For an API error, the message includes the response body, for example Event creation failed: Content: {"errors":[...]}.

For full documentation, see the GitHub repository.