Skip to main content
Topsort.php est un kit de développement logiciel PHP pour les API d’enchères et de suivi d’événements de Topsort.
Configuration minimale requise : PHP 7.3 et Composer.

Installation

Installez avec Composer :
Ou ajoutez à votre composer.json :

Exécution d’une enchère

create_auction prend le nombre de slots, les identifiants des produits, leurs quality scores, un identifiant de catégorie, une recherche et l’opaqueUserId de l’acheteur, dans cet ordre. Passez null pour les arguments que vous n’utilisez pas.
Pour une enchère de bannières, utilisez create_banner_auction :

Signalement des événements

Signalez un render lorsque votre serveur insère un gagnant dans la page, et une impression lorsque ce gagnant devient visible pour l’acheteur. Envoyez le même opaqueUserId pour un acheteur dans chaque enchère et chaque événement, par exemple un identifiant que vous conservez dans un cookie ou dans votre session de connexion. Un nouvel identifiant par événement casse l’attribution. Le SDK n’en génère pas : les méthodes report_* lèvent une Topsort\InvalidEventException lorsqu’il est absent ou vide, avant tout envoi. Chaque méthode report_* renvoie une promesse, et rien n’est envoyé tant que vous n’appelez pas ->wait() dessus. wait() bloque jusqu’à la réponse de Topsort : dans la mesure du possible, signalez donc les événements après avoir envoyé la réponse à l’acheteur, par exemple après fastcgi_finish_request().
Si la page charge également analytics.js, celle-ci signale déjà les renders, les impressions et les clics pour chaque élément portant data-ts-resolved-bid. Ne signalez pas ces événements une seconde fois avec le SDK.

Renders

Un render enregistre qu’une publicité sponsorisée a été insérée dans la page, qu’elle devienne visible ou non. Les renders concernent uniquement les publicités sponsorisées, c’est pourquoi report_render prend le resolvedBidId comme premier argument et il n’y a pas de champ entity.

Impressions

Une impression enregistre qu’une publicité ou un produit est devenu visible pour l’acheteur. Votre serveur ne peut pas le voir : signalez-la depuis la requête que votre frontend envoie lorsque l’élément entre dans le viewport. report_impressions prend une impression par appel.

Clics

Un clic enregistre que l’acheteur a cliqué sur une publicité ou un produit.
Pour les résultats organiques, envoyez "entity" => ["type" => "product", "id" => "<product id>"] au lieu de resolvedBidId, dans les impressions comme dans les clics.

Achats

Un achat enregistre les produits achetés par l’acheteur. Topsort l’attribue aux publicités avec lesquelles l’acheteur a interagi.
Chaque événement accepte aussi un id, généré par le SDK si vous l’omettez, et un occurredAt de type DateTime, qui vaut par défaut l’heure actuelle. Consultez la référence de l’API des événements pour la liste complète des champs d’événement.

Gestion des erreurs

Toutes les erreurs du SDK étendent Topsort\TopsortException, un seul catch suffit donc à les traiter :
  • Topsort\InvalidEventException est levée par l’appel report_* lui-même lorsque l’événement est invalide, avant tout envoi. Gardez l’appel dans le try, pas seulement le ->wait().
  • Topsort\TopsortException est levée par ->wait() lorsque l’API rejette la requête ou est injoignable. Pour une erreur de l’API, le message inclut le corps de la réponse, par exemple Event creation failed: Content: {"errors":[...]}.
Pour la documentation complète, consultez le dépôt GitHub.