SDK de servidor PHP y Laravel

traqio/traqio-php es el SDK de Traqio para backends PHP y Laravel — la mitad servidor del SDK web de Traqio. La conversión que cuenta en un sitio web — un registro, una suscripción, una compra — ocurre en tu backend, donde se conoce el id de usuario. Este paquete la reporta con el trackID, el click id del anuncio que @traqio/web guardó en almacenamiento first-party desde la página de llegada, y Traqio acredita la campaña que trajo al usuario — de forma determinista, por el id de ese clic. Sin más dependencia que ext-curl; descubrimiento automático en Laravel.

Requisitos#

• PHP 8.1 o posterior, con ext-curl y ext-json. Laravel 12 o 13 para la integración con descubrimiento automático; si no, PHP simple, Symfony o cualquier framework PSR-7.
• Una clave de servidor para el producto (tq_sk_…). Ni la clave SDK de la app ni una clave web funcionan aquí.
• @traqio/web en el sitio, y anuncios que apunten a enlaces de seguimiento con un destino web — así es como el trackID llega a tu formulario de registro.

Configuración#

1. Crear una clave de servidor#

   En la consola, abre Integraciones → SDK y crea una clave de servidor. Se muestra una sola vez: ponla en .env, nunca en el código ni en una página. Traqio solo guarda su huella; una clave perdida se sustituye por una nueva y la antigua se revoca.

   .env

   TRAQIO_SECRET_KEY=tq_sk_...

2. Instalar el paquete#

   composer require traqio/traqio-php

   Mientras el paquete no esté en Packagist, añade la carpeta que te enviamos como repositorio de tipo path:

   # the folder you received, committed inside the backend's repository
   composer config repositories.traqio path ./vendor-src/traqio-php
   composer require traqio/traqio-php:@dev

3. Configurar el cliente#

   Laravel: no hay nada que escribir — el service provider y la facade Traqio se descubren solos y leen TRAQIO_SECRET_KEY. Para cambiar el endpoint, el timeout o los reintentos, publica el archivo de configuración:

   php artisan vendor:publish --tag=traqio-config

   PHP simple: un cliente, creado una vez.

   use Traqio\Traqio;
   
   $traqio = new Traqio(getenv('TRAQIO_SECRET_KEY'));

4. Reportar el registro con su trackID#

   Llama a signup() una vez, donde se crea la cuenta. @traqio/web escribe el trackID en la cookie traq_click de tu propio dominio, así que el navegador lo envía con la petición de registro; TrackId::fromRequest() lo lee.

   LaravelPHP

   use Illuminate\Http\Request;
   use Traqio\Laravel\Facades\Traqio;
   use Traqio\TraqioException;
   use Traqio\TrackId;
   
   public function store(Request $request)
   {
       $user = User::create($request->validated());
   
       try {
           // Reads the raw Cookie header: Laravel's cookie decryption would drop traq_click.
           Traqio::signup((string) $user->id, TrackId::fromRequest($request));
       } catch (TraqioException $e) {
           report($e); // never fail the sign-up itself
       }
   
       return redirect('/welcome');
   }

   En Laravel, para sacar la llamada de la petición, ejecútala después de enviar la respuesta:

   dispatch(fn () => Traqio::signup((string) $user->id, $trackId))->afterResponse();

   Si el backend está en otro dominio que el sitio, la cookie no le llega: envía en su lugar Traqio.getTrackId() desde el navegador con el formulario. El registro es el momento en que el usuario es captado; el último clic anterior, dentro de tu ventana de atribución, se lleva el crédito.

5. Registrar las conversiones#

   Traqio::track((string) $user->id, 'purchase', [
       'value' => 49,
       'currency' => 'EUR',
       'transactionId' => $paymentIntent->id, // one payment, one row — whoever reports it
       'store' => 'stripe',
   ]);

   Las conversiones siguen al usuario: se acreditan a la campaña que lo captó.

Qué te dice la respuesta#

$result = Traqio::signup((string) $user->id, $trackId);

$result->trackId;                 // "matched" | "unknown" | "expired" | "claimed" | "refused" | null
$result->acquired;                // true: the sign-up is recorded
$result->attribution->network;    // "meta", "tiktok"… or "organic"
$result->attribution->campaignId; // the campaign that brought the user

Qué hace hoy y qué no#

Las conversiones enviadas aquí aparecen en Eventos en directo, marcadas como no vinculadas a una instalación — lo esperado para un sitio web. Un registro acreditado a una campaña se cuenta en el informe de ROAS como una conversión web de esa campaña, junto a sus instalaciones, y la respuesta de cada llamada te da la atribución al instante.

Errores y reintentos#

Un error de red, un timeout, un 429 o un 5xx se reintenta — dos veces por defecto, con el mismo cuerpo, así que nada se cuenta dos veces. Un 4xx (clave errónea o revocada, payload no válido) no se reintenta. Ambos terminan en una Traqio\TraqioException:

use Traqio\TraqioException;

try {
    Traqio::signup((string) $user->id, $trackId);
} catch (TraqioException $e) {
    // $e->status: 401 = wrong or revoked key, 400 = invalid payload, null = network
    Log::warning($e->getMessage(), ['status' => $e->status, 'body' => $e->body]);
}

Referencia de la API#

// config/traqio.php
return [
    'secret_key'  => env('TRAQIO_SECRET_KEY'),                       // required
    'endpoint'    => env('TRAQIO_ENDPOINT', 'https://api.traqio.app'),
    'timeout'     => (float) env('TRAQIO_TIMEOUT', 10),               // seconds per attempt
    'max_retries' => (int) env('TRAQIO_MAX_RETRIES', 2),              // network error, 429, 5xx
];

En PHP simple, las mismas opciones son el segundo argumento del constructor: endpoint, timeout, max_retries y transport para enviar las peticiones a través de tu propio cliente HTTP.

Preguntas frecuentes#

¿Por qué $request->cookie('traq_click') devuelve null en Laravel?

Laravel cifra sus cookies y las descifra en cada petición; una cookie escrita por JavaScript — la que pone @traqio/web — no supera ese descifrado, así que Laravel devuelve null. TrackId::fromRequest lee en su lugar la cabecera Cookie en bruto, que el descifrado nunca toca. No hace falta añadir traq_click a las excepciones de EncryptCookies.

¿Qué versiones de Laravel son compatibles?

Laravel 12 y 13, mediante el descubrimiento automático de paquetes: el service provider, el archivo de configuración y la facade Traqio se registran solos. El cliente en sí es PHP 8.1+ simple y funciona en Symfony, Slim o cualquier aplicación PSR-7.

¿Y si el visitante no vino de un anuncio?

TrackId::fromRequest devuelve null y el registro se guarda igualmente, como orgánico: no se acredita ninguna campaña.

¿Un reintento contará una compra dos veces?

No. Cada llamada genera sus ids de evento una sola vez y reintenta exactamente el mismo cuerpo, y una compra se identifica además por su transactionId, así que el mismo pago reportado dos veces se guarda una sola vez.