Events API de TikTok para Shopify: configuración y deduplicación

La TikTok Events API es la conexión de servidor a servidor de TikTok para los datos de conversión. En lugar de depender solo del píxel de TikTok en el navegador del comprador, tu tienda, o una herramienta como ROASaurus, envía eventos como las compras directamente a TikTok. TikTok recomienda ejecutar la Events API junto al píxel y deduplicar ambos con un event_id compartido.

Esta guía cubre lo que envía la Events API desde una tienda de Shopify, los nombres de evento Purchase y CompletePayment, el click id y la cookie por los que TikTok vincula, cómo funciona la deduplicación, cómo probar en TikTok Events Manager y cómo configurarlo todo en ROASaurus.

¿Qué es la TikTok Events API?

El píxel de TikTok es un script de tu tienda. Dispara eventos desde el navegador del comprador, así que solo cuenta lo que ocurre mientras el script se carga y se ejecuta. Un bloqueador de anuncios, un error de script o un comprador que cierra la pestaña antes de que cargue la confirmación del pedido pueden detenerlo.

La Events API envía el mismo tipo de evento desde un servidor. En Shopify, el registro más fiable de una compra es el propio pedido. Shopify informa de cada pedido pagado mediante un webhook, se haya ejecutado o no el script del navegador. Esa es la idea del server-side tracking en Shopify.

Las dos no son alternativas. El consejo de TikTok es compartir eventos por ambas vías, mantenerlos coherentes a lo largo del recorrido de compra y dejar que TikTok elimine los duplicados.

¿Qué eventos envía ROASaurus a TikTok?

Cuatro momentos de una tienda de Shopify importan para la optimización de TikTok: una visualización de producto, un añadido al carrito, el inicio del checkout y la compra. ROASaurus envía los cuatro a la Events API y dispara los mismos cuatro mediante el píxel de TikTok, con los mismos ids de evento. Las visualizaciones de página pasan solo por el píxel.

En los ajustes del píxel puedes desmarcar los eventos del servidor que no quieras enviar y añadir filtros, como un país o un valor mínimo de pedido.

¿Purchase o CompletePayment?

TikTok cambió el nombre de su evento de compra. El nombre actual es Purchase. El nombre antiguo, CompletePayment, sigue funcionando: TikTok convierte los nombres heredados por su cuenta, los muestra con el nombre nuevo en los informes, las audiencias y la optimización, y dice que CompletePayment seguirá siendo compatible indefinidamente. TikTok pide que las configuraciones nuevas del píxel usen Purchase.

ROASaurus envía CompletePayment, tanto en el píxel como en la Events API. En TikTok Events Manager y en Ads Manager, esos eventos aparecen como Purchase. Para la deduplicación, lo que cuenta es que las dos copias de una compra usen el mismo nombre de evento, y así es.

¿Cómo vincula TikTok un evento con un comprador?

Un evento solo ayuda a tus campañas si TikTok puede vincularlo con la persona que vio el anuncio o hizo clic en él. TikTok llama a estos identificadores claves de coincidencia, y su guía de la Events API pide que devuelvas todas las claves de coincidencia relevantes para aumentar las tasas de coincidencia. Events Manager muestra el resultado como una puntuación de Calidad de coincidencia de eventos, un promedio ponderado de la frecuencia con la que está presente cada clave de coincidencia.

TikTok señala que el píxel comparte por defecto la dirección IP y el user agent, pero la Events API necesita que se añadan a mano. ROASaurus los toma de la sesión de checkout del comprador, o del pedido si no hubo sesión. Otras dos claves requieren atención en Shopify.

ttclid: el click id de TikTok

Cuando un comprador hace clic en un anuncio de TikTok, TikTok añade ttclid a la URL de la página de llegada. Si tu tienda no lo guarda en esa primera página, se pierde cuando llega el pedido, varias páginas después. ROASaurus lee ttclid en la página de llegada, lo guarda junto con el id de visitante, lo escribe en el carrito de Shopify y lo añade al evento del servidor cuando llega el pedido.

_ttp: la cookie del píxel

La cookie _ttp es una cookie first-party que el píxel de TikTok usa en tu dominio. ROASaurus la lee en la tienda y en el checkout y la envía como ttp en el evento del servidor. Es una razón más para mantener el píxel funcionando junto a la Events API.

{
  "event_source": "web",
  "event_source_id": "CXXXXXXXXXXXXXXXXXXX",
  "data": [{
    "event": "CompletePayment",
    "event_time": 1793016000,
    "event_id": "order-5512345678901",
    "user": {
      "email": "a3f1…9c2e",
      "phone": "7b40…11d8",
      "external_id": "e05c…4a7f",
      "ttclid": "E.C.P.v3…",
      "ttp": "2Xb7…",
      "ip": "203.0.113.24",
      "user_agent": "Mozilla/5.0 (iPhone; …)"
    },
    "page": { "url": "https://example-store.com/checkouts/…/thank-you" },
    "properties": {
      "currency": "USD",
      "value": 84,
      "content_type": "product",
      "contents": [{ "content_id": "44123456789", "content_name": "Linen shirt", "quantity": 2, "price": 42 }],
      "order_id": "5512345678901"
    }
  }]
}

¿Cómo funciona la deduplicación?

Cuando el píxel y la Events API informan de la misma compra, TikTok recibe dos eventos por un solo pedido. Para quedarse con uno solo, TikTok necesita que dos valores sean idénticos en ambas copias: el nombre del evento y el event_id. TikTok registra entonces la primera copia que recibe para la medición y los informes, así que el pedido cuenta una sola vez. Esto funciona con copias coincidentes que llegan en una ventana de 48 horas desde la primera.

ROASaurus construye el id de evento de una compra a partir del id de pedido de Shopify. La compra del pedido 5512345678901 tiene el id de evento order-5512345678901, tanto en el píxel del checkout como en el servidor. Los eventos de la tienda, como las visualizaciones de producto y los añadidos al carrito, reciben un id aleatorio cuando ocurren, y la copia del navegador y la del servidor lo comparten.

Veamos qué significa esto para las cifras. Imagina una tienda de ejemplo con 200 pedidos en una semana. El píxel se dispara en 150 de ellos. Los otros 50 compradores usaron un bloqueador de anuncios, rechazaron las cookies de marketing o se fueron antes de que cargara la página de confirmación. La Events API envía los 200.

El 350 es la cifra que debe preocuparte. Haría que el recuento de compras de TikTok, y el ROAS que se basa en él, fueran un 75% más altos que la realidad, porque 350 ÷ 200 = 1.75. TikTok también usa estos eventos para la optimización y la segmentación, así que su puja aprendería de 150 compras que no ocurrieron.

¿Por qué las compras se cuentan dos veces en Shopify?

El doble conteo ocurre cuando TikTok recibe dos copias de una compra que no puede vincular. Revisa estas causas antes de fiarte de un salto en las compras de TikTok:

• Dos herramientas envían el mismo píxel. La app del canal de ventas de TikTok en Shopify también puede enviar eventos para tu píxel. Sus ids de evento no coinciden con los que usa ROASaurus, así que TikTok cuenta cada pedido dos veces. Desconecta el píxel en esa app.
• El píxel también está en el código de tu tema. Un fragmento de píxel pegado en el tema dispara sus propios eventos sin tus ids de evento. Elimínalo y deja que una sola herramienta cargue el píxel.
• Un lado no tiene event_id. Una compra del servidor sin event_id, o con un id aleatorio nuevo, no se puede vincular con la copia del píxel.
• Los nombres de evento son distintos. TikTok solo deduplica eventos idénticos. Las dos copias de una compra deben usar el mismo nombre de evento.

El artículo de ayuda sobre el doble conteo recorre las mismas comprobaciones para Meta y las demás plataformas.

¿Cómo se prueba la Events API en TikTok Events Manager?

TikTok Events Manager tiene una pestaña Test events para los eventos del navegador y del servidor. Úsala antes de fiarte de los datos:

1. Copia un código de evento de prueba

   En TikTok Events Manager, abre tu píxel y ve a Test events. Copia el código del evento de prueba.

2. Pégalo en ROASaurus

   Abre Tracking & platforms, edita el píxel de TikTok y pega el código en el campo Test event code. Los eventos del servidor ya lo llevan.

3. Haz un pedido de prueba

   Visita tu tienda, mira un producto, añádelo al carrito y completa un pedido.

4. Comprueba ambos lados

   En Test events, filtra por eventos del navegador y del servidor. Deberías ver la compra de ambos. En ROASaurus, el Event log muestra cada envío del servidor como enviado o fallido.

5. Quita el código de prueba

   Elimina el código del evento de prueba cuando termines, para que tus eventos del servidor en producción dejen de enviarse como eventos de prueba.

TikTok puede responder a una solicitud con HTTP 200 y rechazar aun así el evento, con un código de error en el cuerpo de la respuesta. ROASaurus lee ese código, así que un evento rechazado aparece como fallido en el Event log en lugar de pasar en silencio.

Tras un día de tráfico real, abre el resumen del píxel en Events Manager. Muestra cada evento con su método de conexión, su puntuación de Calidad de coincidencia de eventos y cuándo se recibió por última vez. Los detalles del evento incluyen información sobre coincidencia y deduplicación, y Diagnostics enumera los problemas de calidad con indicaciones para solucionarlos.

Cómo configurar la TikTok Events API en Shopify con ROASaurus

Necesitas una tienda de Shopify con la app de ROASaurus y acceso a TikTok Events Manager. La página de la integración con TikTok enumera todos los campos que envía ROASaurus.

1. Conecta tu tienda de Shopify

   Ve a Add a store › Shopify, haz clic en Install app y activa el app embed de ROASaurus en el editor de temas. El embed captura ttclid y la cookie _ttp en cada página. La guía de configuración de Shopify muestra cada paso.

2. Añade el píxel del checkout

   En Shopify admin › Settings › Customer events, añade un píxel personalizado llamado ROASaurus y pega el fragmento de tu página Tracking & platforms. Dispara el píxel de TikTok en el checkout, incluida la copia de la compra del navegador.

3. Crea un token de acceso

   En TikTok Events Manager, abre tu píxel y genera un token de acceso de la Events API en sus ajustes. Copia el token y el código del píxel.

4. Añade el píxel de TikTok en ROASaurus

   Ve a Tracking & platforms, haz clic en Add pixel en la tarjeta de TikTok y rellena Pixel code y Events API access token. Deja marcado Also load the browser pixel (recommended, deduplicated), para que los eventos del navegador y del servidor compartan ids.

5. Añade el gasto (opcional)

   Rellena Advertiser ID for spend y un Marketing API token. ROASaurus importa entonces el gasto de TikTok, de modo que las campañas de TikTok muestran el ROAS y el CPA junto a tus demás canales.

6. Prueba y sal en directo

   Envía un pedido de prueba con un código de evento de prueba como se describe arriba y después quita el código.

Con Respect visitor consent activado, que es lo predeterminado, ROASaurus sigue la elección del comprador en el banner de cookies de Shopify. Cuando un comprador rechaza las cookies de marketing, ROASaurus no carga el píxel de TikTok para él, no asigna ningún id de visitante, así que sus clics no se le asocian, y no envía sus eventos de navegación a TikTok. Su pedido pagado se sigue enviando a la Events API desde el servidor, con los datos del pedido con hash y con la dirección IP y el user agent del pedido, pero sin ttclid ni _ttp. La guía de consentimiento y privacidad explica qué se almacena y qué se envía.

Con el gasto sincronizado, las campañas de TikTok aparecen en los informes de atribución junto a Meta, y la analítica de creatividades añade las estadísticas de vídeo de TikTok por anuncio. ROASaurus atribuye los pedidos a los clics en anuncios y las UTM que registró, y solo cuenta las conversiones por visualización como una estimación modelada en su modelo Clicks & views, así que sus totales suelen diferir de los de TikTok Ads Manager. Para las demás plataformas server-side, consulta la guía de la Pinterest Conversions API y la guía de la Meta Conversions API.

Fuentes

1. TikTok For Business: About Events API
2. TikTok Ads Manager: About Event Deduplication
3. TikTok Ads Manager: How to Adopt TikTok's Updated Standard Events
4. TikTok Ads Manager: How to set up matching events with Events API
5. TikTok Ads Manager: About diagnostic and monitoring tools in TikTok Events Manager

En ROASaurus

• Integración con TikTok
• Server-side tracking en ROASaurus
• Ayuda: evitar el doble conteo
• Ayuda: configurar ROASaurus en Shopify

Sigue leyendo