Referencia del SDK

Última actualización: 9 nov 2026

La API pública completa del código de captura de TraceLog —init, consentimiento, pasos y conversión— con los parámetros, tipos y ejemplos.

Estos métodos permiten iniciar TraceLog, gestionar el consentimiento y enviar pasos y conversiones. La etiqueta script los expone en el objeto global TraceLog; el paquete npm exporta el mismo objeto por defecto.

init

TypeScript

init(options: {
  key: string;
  endpoint?: string;
  mode?: "verification";
}): void;

Inicia el código de captura. Puedes llamarlo varias veces: la primera crea el motor y las siguientes vuelven a aplicar la configuración. Las llamadas anteriores a la primera se guardan, hasta 100, y se hacen en cuanto se ejecuta.

Parámetro	Tipo	Descripción
`key`	`string`	Clave de navegador: `tl_pk_` seguida de 26 caracteres base32 en minúscula. Es pública y está limitada a las direcciones de tu web.
`endpoint`	`string`	Destino de los lotes. De forma predeterminada usa `/v1/events` en tu propio origen. Debe ser `http` o `https`.
`mode`	`"verification"`	Marca la sesión como tráfico de verificación. La app de Shopify y el plugin de WooCommerce lo obtienen de la señal de pedido de prueba de la tienda; el módulo de PrestaShop y una página abierta desde la comprobación lo deducen por sí solos.

JavaScript

TraceLog.init({ key: "tl_pk_xxxxxxxxxxxxxxxxxxxxxxxxxx" });

Una clave o un endpoint no válidos no lanzan una excepción ni capturan datos. El código informa de config_invalid a la comprobación sin romper tu página.

TypeScript

consent.grant(): void;

Concede el consentimiento e inicia la captura. Antes de esta llamada no se crean identificadores, no se escribe en el almacenamiento y no se envían solicitudes. Una negativa se recuerda en una sola clave y nada más, así que el código no vuelve a preguntar a quien la rechazó. La aceptación no se recuerda: llámalo en cada carga de página mientras el consentimiento del visitante siga vigente, así el consentimiento que caduca o se retira en tu banner termina también en TraceLog.

JavaScript

TraceLog.consent.grant();

TypeScript

consent.deny(): void;

Deniega el consentimiento. La captura se detiene y se descarta lo que esté en cola.

JavaScript

TraceLog.consent.deny();

TypeScript

consent.state(): "unknown" | "granted" | "denied";

Devuelve el estado actual. unknown significa que todavía no se ha llamado a ninguno de los dos métodos; no equivale a consentimiento denegado. La comprobación usa esa diferencia para distinguir un código ausente de un aviso de consentimiento que lo está bloqueando.

JavaScript

if (TraceLog.consent.state() === "unknown") showConsentBanner();

step

TypeScript

step(name: string, context?: object, options?: {
  items?: {
    id: string;
    name: string;
    category?: string;
    quantity: number;
    price?: number;
  }[];
}): void;

Registra un paso declarado del recorrido de conversión.

Parámetro	Tipo	Descripción
`name`	`string`	Debe coincidir con el recorrido de conversión: minúsculas, empezar por una letra y continuar con letras, números o guiones bajos, hasta 64 caracteres.
`context`	`object`	Opcional. Cualquier objeto serializable como JSON, hasta 8 KB una vez serializado. Las claves que empiezan por `__tl.` son de TraceLog y se eliminan.
`options.items`	`array`	Opcional, en una conversión o un paso: hasta 100, cada uno con un ID, un nombre, una categoría opcional, una cantidad desde 1 y un precio unitario opcional.

JavaScript

TraceLog.step("begin_checkout", { cartSize: 3 });

Un paso cuyo nombre no figure en el recorrido de conversión se recibe, pero no forma parte de la verificación.

conversion

TypeScript

conversion(name: string, options: {
  identifier: string;
  value?: number;
  currency?: string;
  context?: object;
  items?: {
    id: string;
    name: string;
    category?: string;
    quantity: number;
    price?: number;
  }[];
  scheduledFor?: string;
  recurring?: boolean;
  first?: boolean;
}): void;

Registra la conversión declarada.

Parámetro	Tipo	Descripción
`name`	`string`	Nombre de la conversión en el recorrido, con el mismo formato que un paso.
`options.identifier`	`string`	Obligatorio, entre 1 y 256 caracteres. Un identificador estable propio, como un número de pedido, contacto o reserva. Si falta, o si el mismo identificador llega con datos incompatibles, se bloquea la verificación; un segundo valor en menos de 1 de cada 100 identificadores del día solo avisa.
`options.value`	`number`	Opcional, igual o mayor que cero.
`options.currency`	`string`	Opcional. Código ISO 4217 de tres letras mayúsculas, por ejemplo `EUR`.
`options.context`	`object`	Opcional. Cualquier objeto serializable como JSON, hasta 8 KB. Las claves que empiezan por `__tl.` son de TraceLog y se eliminan.
`options.items`	`array`	Opcional, en una conversión o un paso: hasta 100, cada uno con un ID, un nombre, una categoría opcional, una cantidad desde 1 y un precio unitario opcional.
`options.scheduledFor`	`string`	Opcional, en una conversión: para qué día es, AAAA-MM-DD.
`options.recurring`	`boolean`	Opcional, en una conversión: si es periódica.
`options.first`	`boolean`	Opcional, en una conversión: `true` si tus registros no tienen ninguna conversión anterior de este tipo hecha por la misma persona, `false` si la tienen; omítelo si no lo sabes.

JavaScript

TraceLog.conversion("purchase", {
  identifier: "1042",
  value: 89.9,
  currency: "EUR",
});

Un artículo cuyo ID es (other) se cuenta en «Otros», junto con los que pasan de los 500 de cada día.

Lo que no forma parte de la API

No hay métodos para leer una métrica, forzar un envío, asignar una identidad de usuario ni capturar una página vista. Los lotes se envían a su propio ritmo y también al ocultarse la página. TraceLog no mantiene identidades entre sitios y no captura páginas vistas, clics ni desplazamiento: la primera página de la visita en la que el visitante ya ha dado su consentimiento abre la sesión, y no se registra ninguna después.