create_auction recibe el número de slots, los IDs de los productos, sus quality scores, un ID de categoría, una búsqueda y el opaqueUserId del comprador, en ese orden. Pasa null en los argumentos que no uses.
<?phpuse 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"];
Para una subasta de banners, usa create_banner_auction:
Reporta un render cuando tu servidor inserta un ganador en la página, y una impresión cuando ese ganador se vuelve visible para el comprador. Envía el mismo opaqueUserId para un comprador en cada subasta y evento, por ejemplo un id que guardas en una cookie o en la sesión del usuario que inició sesión. Un id nuevo por evento rompe la atribución. El SDK no genera uno: los métodos report_* lanzan una Topsort\InvalidEventException cuando falta o está vacío, antes de enviar nada.Cada método report_* devuelve una promesa, y no se envía nada hasta que llamas a ->wait() sobre ella. wait() bloquea hasta que Topsort responde, así que, cuando sea posible, reporta los eventos después de enviar la respuesta al comprador, por ejemplo después de fastcgi_finish_request().
Si la página también carga analytics.js, la biblioteca ya reporta renders, impresiones y clics para cada elemento con data-ts-resolved-bid. No vuelvas a reportar esos eventos con el SDK.
<?phpuse 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
Un render registra que un anuncio patrocinado fue insertado en la página, se vuelva visible o no. Los renders son solo para anuncios patrocinados, por lo que report_render recibe el resolvedBidId como primer argumento y no existe el campo entity.
Una impresión registra que un anuncio o producto se volvió visible para el comprador. Tu servidor no puede verlo, así que repórtala desde la solicitud que envía tu frontend cuando el elemento entra en el viewport. report_impressions recibe una impresión por llamada.
Para resultados orgánicos, envía "entity" => ["type" => "product", "id" => "<product id>"] en lugar de resolvedBidId, tanto en impresiones como en clics.
Todos los eventos aceptan además un id, que el SDK genera si lo omites, y un occurredAt de tipo DateTime, que por defecto es la hora actual. Consulta la referencia de la API de eventos para ver todos los campos de los eventos.
Todos los errores del SDK extienden Topsort\TopsortException, así que un solo catch los maneja:
Topsort\InvalidEventException la lanza la propia llamada report_* cuando el evento no es válido, antes de enviar nada. Mantén la llamada dentro del try, no solo el ->wait().
Topsort\TopsortException la lanza ->wait() cuando la API rechaza la solicitud o no se puede conectar con ella. Para un error de la API, el mensaje incluye el cuerpo de la respuesta, por ejemplo Event creation failed: Content: {"errors":[...]}.
