TikTok
Pixel + Events API

1. Instalar y conectar

1. En WordPress abre Plugins → Añadir nuevo → Subir plugin. Sube ndc-tiktok-1.0.0.zip, instala y activa.
2. Abre Ajustes → NDC TikTok.
3. En TikTok Ads Manager, entra en el administrador de eventos, crea o selecciona la fuente de datos web y copia el ID del píxel. En la configuración de Events API genera un token para esa misma fuente.
4. Pega ambos datos. El campo del token queda vacío al volver a abrir el panel: se conserva el valor guardado. Solo se borra marcando la casilla correspondiente.
5. Elige cómo recoger el consentimiento. Si ya hay banner de cookies, usa el modo externo y su adaptador; si no, puedes activar el aviso incluido para TikTok.
6. Marca Activar medición, guarda y realiza las pruebas del apartado 5. Los administradores no se miden: utiliza una ventana privada.

La instalación empieza desactivada. No se incluyen credenciales ni datos reales de ninguna cuenta.

Panel de configuración

Captura de una instalación local de prueba. TESTPIXEL123 es un ejemplo; el token nunca aparece.

2. Qué mide esta versión

Una compra usa el mismo identificador en ambas vías para deduplicar. Un pedido pendiente o fallido no se envía como compra. El estado de pago lo decide WooCommerce/la pasarela: el módulo no concilia tu banco. En contra reembolso y pasarelas personalizadas, verifica cuándo se marca como pagado.

El importe de compra es el total del pedido, incluidos impuestos y envío. Los artículos incluyen ID de producto o variación, cantidad y precio de línea después de descuentos y sin impuestos. Los IDs de catálogo deberán coincidir si usas anuncios dinámicos.

Los clics en WhatsApp no confirman conversaciones; CF7 confirma el envío técnico del formulario, no la calidad comercial del lead. No se miden llamadas contestadas, reservas externas ni ventas cerradas por WhatsApp.

3. Consentimiento

Aviso propio

Incluye aceptar, rechazar y un botón permanente «Privacidad TikTok» para cambiar la decisión. Solo controla este plugin de TikTok. No bloquea Google, Meta, YouTube u otros scripts instalados por otras herramientas y no sustituye a una CMP general del sitio.

No carga el SDK ni guarda el identificador del clic antes de aceptar. Al retirar el consentimiento, detiene nuevos eventos del módulo, elimina sus identificadores accesibles y recarga la página para descargar el SDK. No puede retirar datos ya recibidos por TikTok.

Banner o CMP existente

En modo externo, el banner debe comunicar el estado de marketing en cada página y en cada cambio. No basta con seleccionar este modo: hay que conectar su callback. Para aceptar:

window.ndcTikTokConsent = true;
window.dispatchEvent(new CustomEvent('ndctt:consent', {
  detail: { granted: true }
}));

Para rechazar o retirar, usa false en ambos valores. La variable permite informar antes de cargar el módulo y el evento permite actualizarlo después. También está disponible window.NDCTikTok.setConsent(true/false) una vez cargado.

La compra conserva la decisión e identificadores del checkout para poder comunicar el pago confirmado por una notificación posterior de la pasarela. No se reconstruye consentimiento para pedidos antiguos ni se consulta retroactivamente el navegador desde una notificación de pago.

Usa un único responsable de instalar el píxel. Si el mismo píxel ya se carga desde GTM, el plugin oficial u otro módulo, desactiva esa instalación para evitar medición duplicada o cargas anteriores al consentimiento.

4. Compatibilidad y requisitos

• WordPress 6.4 o posterior y PHP 7.4 o posterior. Probado en WordPress aislado con PHP 8.3.
• Divi, Elementor y editor de bloques: el módulo no depende del maquetador para cargar el píxel ni detectar enlaces. Los formularios nativos de Divi/Elementor requieren adaptación; la integración automática de formularios de esta versión es Contact Form 7.
• WooCommerce: adaptadores para checkout clásico y Store API/bloques; usa la API de pedidos, compatible por diseño con HPOS. Hay que validar el recorrido completo en la versión y pasarela concretas del sitio.
• Sin WooCommerce: siguen disponibles las visitas, contactos y CF7. No es necesario instalarlo si solo captas leads.
• Hosting: conexión HTTPS saliente a TikTok y WP-Cron operativo. El servidor normal de WordPress suele bastar; si el hosting bloquea esas conexiones o desactiva cron, habrá que corregirlo allí.
• Caché: excluir carrito, checkout, confirmación del pedido y admin-ajax.php. No cachear páginas privadas ni el HTML de un pedido. Vaciar la caché después de cambiar la configuración.
• No incluido: instalación multisite en red, PrestaShop, Shopify, iframes de reservas, formularios de terceros ni conectores CRM.

El archivo contiene código fuente legible; no utiliza licencias remotas, cuotas ni servidor de Nivel de Calidad.

5. Validar antes de campañas

1. Abre la web en una ventana privada. Antes de decidir y después de rechazar, no debe haber peticiones del módulo a TikTok.
2. Acepta. Comprueba la visita, el producto y los clics en enlaces con TikTok Pixel Helper. Un clic repetido es otra interacción; no es otro cliente.
3. Para comprobar servidor, pega el código de Test Events del administrador de eventos. Mientras está presente, el módulo suspende el píxel para no contaminar producción con pruebas del navegador.
4. Crea un pedido nuevo, con consentimiento aceptado, y confirma el pago usando la pasarela de pruebas. La compra se entrega por WP-Cron aunque el navegador no vuelva a la confirmación. Revisa Últimos envíos API y Test Events.
5. Prueba un pedido fallido y otro rechazando consentimiento: no deben convertirse en compras enviadas. Si hay CF7, prueba éxito, error de validación y rechazo del consentimiento.
6. Quita el código de Test Events. Para validar la combinación real píxel + API y su deduplicación, usa una fuente de datos de pruebas y un pedido nuevo. Los pedidos creados en modo prueba no se reenvían a producción.
7. Retira el consentimiento desde el aviso o la CMP. Verifica que se detiene la medición del módulo.

La API registra aceptación técnica, no atribución. TikTok decide si puede asociar el evento a un anuncio y según qué ventana.

Si no llegan eventos

No se reenvían compras de hace más de 48 horas ni errores permanentes indefinidamente. Tras corregir credenciales, valida con un pedido nuevo; esta versión no incluye reenvío manual de pedidos.

6. Datos y mantenimiento

El token se guarda en las opciones de WordPress, fuera del HTML público y sin mostrarlo en el campo de ajustes. No está cifrado en la base de datos: protege el acceso de administradores, base de datos y copias de seguridad.

El contexto del pedido puede contener IP, agente de navegador, ttclid, _ttp, fecha de consentimiento e identificador del píxel. Se programa su limpieza a los dos días de reconocer el pago, o a los 30 días para pedidos sin pago. Estas tareas dependen de WP-Cron y del módulo activo. Los marcadores de envío no contienen email ni IP.

La opción de coincidencia avanzada añade únicamente el email de facturación, normalizado y convertido a SHA-256, para las compras que se generen con esa opción y consentimiento activados. No se extraen emails de formularios. Un hash no convierte un dato personal en anónimo.

El registro guarda las últimas 30 respuestas resumidas, sin payloads ni datos personales directos. Se puede vaciar desde el panel. Al desactivar se detienen los envíos; al eliminar el plugin se borran ajustes, token, registro y metadatos propios, conservando pedidos. Las cookies ya existentes caducarán en el navegador.

El SDK de TikTok puede leer la URL y el referente. Evita incluir datos personales o sensibles en URLs y revisa la configuración de eventos automáticos y coincidencia avanzada en TikTok. El módulo no altera esos ajustes remotos ni concede consentimiento para otros plugins.

7. Qué se ha comprobado

24 pruebas de servidor con dobles de WooCommerce y API: bloqueo sin consentimiento, pedidos impagados, total y moneda, identificadores, deduplicación, reintentos, errores permanentes, antigüedad, separación de pruebas/producción, hash de email, credenciales y limpieza.

16 comprobaciones de navegador en WordPress aislado: activación y panel, token no expuesto, rechazo, aceptación, retirada, no duplicar PageView, enlace WhatsApp con elementos anidados, CF7 sin doble evento, CMP externa y modo prueba.

La API de TikTok se simuló durante las pruebas; no se han enviado datos reales. Falta comprobar recepción y atribución con tu cuenta, y el recorrido completo con WooCommerce, CF7, pasarela y maquetador de la web de destino.

Referencias técnicas

• TikTok · Events API
• TikTok · Deduplicación
• TikTok · Eventos estándar
• WooCommerce · Hooks y checkout de bloques

Primera versión · 8 de octubre de 2026 · GPL-2.0-or-later