Topsort.php

Ein PHP Software Development Kit zur Interaktion mit Auktions- und Ereignis-Endpunkten

Topsort.php ist ein PHP Software Development Kit für die Auktions- und Ereignisverfolgung-APIs von Topsort.

Mindestanforderungen: PHP 7.3 und Composer.

Installation

Installieren Sie mit Composer:

composer require topsort/sdk

Oder fügen Sie zu Ihrer composer.json hinzu:

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

Ausführen einer Auktion

create_auction erhält die Anzahl der Slots, die Produkt-IDs, deren Quality Scores, eine Kategorie-ID, eine Suchanfrage und die opaqueUserId des Käufers, in dieser Reihenfolge. Übergeben Sie null für die Argumente, die Sie nicht verwenden.

<?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"];

Für eine Banner-Auktion verwenden Sie create_banner_auction:

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

Ereignismeldung

Melden Sie einen Render, wenn Ihr Server einen Gewinner in die Seite einfügt, und eine Impression, wenn dieser Gewinner für den Käufer sichtbar wird. Senden Sie für einen Käufer bei jeder Auktion und jedem Ereignis dieselbe opaqueUserId, zum Beispiel eine ID, die Sie in einem Cookie oder in Ihrer Login-Sitzung speichern. Eine neue ID pro Ereignis verhindert die Attribution. Das SDK erzeugt keine eigene ID: Die report_*-Methoden werfen eine Topsort\InvalidEventException, wenn sie fehlt oder leer ist, bevor etwas gesendet wird.

Jede report_*-Methode gibt ein Promise zurück, und es wird nichts gesendet, bis Sie ->wait() darauf aufrufen. wait() blockiert, bis Topsort antwortet. Melden Sie Ereignisse daher nach Möglichkeit erst, nachdem die Antwort an den Käufer gesendet wurde, zum Beispiel nach fastcgi_finish_request().

Wenn die Seite auch analytics.js lädt, meldet diese Bibliothek bereits Renders, Impressionen und Klicks für jedes Element mit data-ts-resolved-bid. Melden Sie diese Ereignisse nicht zusätzlich mit dem 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

Ein Render erfasst, dass eine gesponserte Anzeige in die Seite eingefügt wurde, unabhängig davon, ob sie jemals sichtbar wird. Renders gibt es nur für gesponserte Anzeigen, daher erhält report_render die resolvedBidId als erstes Argument und es gibt kein entity-Feld.

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

Impressionen

Eine Impression erfasst, dass eine Anzeige oder ein Produkt für den Käufer sichtbar wurde. Ihr Server kann das nicht sehen. Melden Sie sie daher aus der Anfrage, die Ihr Frontend sendet, wenn das Element in den Viewport gelangt. report_impressions erhält eine Impression pro Aufruf.

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

Klicks

Ein Klick erfasst, dass der Käufer auf eine Anzeige oder ein Produkt geklickt hat.

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

Für organische Ergebnisse senden Sie bei Impressionen und Klicks "entity" => ["type" => "product", "id" => "<product id>"] anstelle von resolvedBidId.

Käufe

Ein Kauf erfasst die Produkte, die der Käufer gekauft hat. Topsort ordnet ihn den Anzeigen zu, mit denen der Käufer interagiert hat.

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());
}

Jedes Ereignis akzeptiert außerdem eine id, die das SDK erzeugt, wenn Sie sie weglassen, und ein occurredAt vom Typ DateTime, standardmäßig die aktuelle Zeit. Alle Ereignisfelder finden Sie in der API-Referenz für Ereignisse.

Fehlerbehandlung

Alle Fehler des SDK erweitern Topsort\TopsortException, daher behandelt ein einziges catch sie alle:

• Topsort\InvalidEventException wird vom report_*-Aufruf selbst geworfen, wenn das Ereignis ungültig ist, bevor etwas gesendet wird. Lassen Sie den Aufruf im try, nicht nur das ->wait().
• Topsort\TopsortException wird von ->wait() geworfen, wenn die API die Anfrage ablehnt oder nicht erreichbar ist. Bei einem API-Fehler enthält die Meldung den Antworttext, zum Beispiel Event creation failed: Content: {"errors":[...]}.

Für die vollständige Dokumentation besuchen Sie das GitHub-Repository.