Referencia del SDK

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.

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 por una lista de orígenes.
`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; una página abierta desde una sesión de verificación lo deduce por sí sola.

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 sesión de verificació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ó.

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 sesión de verificació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): void;

Registra un paso declarado del recorrido de conversión.

Parámetro	Tipo	Descripción
`name`	`string`	Debe coincidir con el plan: 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.

JavaScript

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

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

conversion

TypeScript

conversion(name: string, options: {
  identifier: string;
  value?: number;
  currency?: string;
  context?: object;
}): void;

Registra la conversión declarada.

Parámetro	Tipo	Descripción
`name`	`string`	Nombre de la conversión en el plan, 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, lead o reserva. Si falta, o si el mismo identificador llega con datos incompatibles, se bloquea la verificación.
`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.

JavaScript

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

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.