Tecnologías

Guías de implementación por stack / framework. El objetivo es que puedas capturar los datos de tracking en frontend, guardarlos en tu backend/CRM y, si procede, sincronizar conversiones.

🟢 Node.js / Express

Integración de Referrer Tracker en aplicaciones Node.js con Express.

Instalación Frontend

Añade el script en tu template HTML (EJS, Pug, Handlebars, etc.):

<!-- En tu layout.ejs, layout.pug, etc. -->
<script src="/referrer-tracker.min.js"></script>
<script>
  ReferrerTracker.configure({
    apiKey: '<%= process.env.REFERRER_TRACKER_API_KEY %>'
  });
</script>

Captura en Backend

Procesa los datos de tracking en tu endpoint de formulario:

// routes/contact.js
const express = require('express');
const router = express.Router();

router.post('/submit', async (req, res) => {
  const {
    name,
    email,
    phone,
    message,
    // Datos de tracking
    utm_source,
    utm_medium,
    utm_campaign,
    gclid,
    fbclid,
    referrer
  } = req.body;

  // Guardar en base de datos
  const lead = await db.leads.create({
    name,
    email,
    phone,
    message,
    // Campos de atribución
    source: utm_source,
    medium: utm_medium,
    campaign: utm_campaign,
    google_click_id: gclid,
    facebook_click_id: fbclid,
    referrer_url: referrer,
    created_at: new Date()
  });

  // Enviar a CRM o webhook
  await sendToCRM(lead);

  res.json({ success: true, message: 'Lead recibido' });
});

module.exports = router;

Modelo de Base de Datos (Sequelize)

// models/Lead.js
module.exports = (sequelize, DataTypes) => {
  const Lead = sequelize.define('Lead', {
    // Datos del contacto
    name: DataTypes.STRING,
    email: DataTypes.STRING,
    phone: DataTypes.STRING,
    message: DataTypes.TEXT,
    
    // Datos de atribución
    utm_source: DataTypes.STRING,
    utm_medium: DataTypes.STRING,
    utm_campaign: DataTypes.STRING,
    utm_content: DataTypes.STRING,
    utm_term: DataTypes.STRING,
    
    // Click IDs
    gclid: DataTypes.STRING,
    fbclid: DataTypes.STRING,
    msclkid: DataTypes.STRING,
    ttclid: DataTypes.STRING,
    
    // Otros
    referrer: DataTypes.TEXT,
    landing_page: DataTypes.TEXT
  });
  
  return Lead;
};

🔴 Laravel / PHP

Integración de Referrer Tracker en aplicaciones Laravel.

Instalación Frontend

Añade el script en tu layout Blade:

{{-- resources/views/layouts/app.blade.php --}}
<!DOCTYPE html>
<html>
<head>
    <title>@yield('title')</title>
    
    {{-- Referrer Tracker --}}
    <script src="{{ asset('js/referrer-tracker.min.js') }}"></script>
    <script>
      ReferrerTracker.configure({
        apiKey: '{{ config('services.referrer_tracker.api_key') }}'
      });
    </script>
</head>
<body>
    @yield('content')
</body>
</html>

Configuración

// config/services.php
return [
    // ...
    'referrer_tracker' => [
        'api_key' => env('REFERRER_TRACKER_API_KEY'),
    ],
];

Migración de Base de Datos

// database/migrations/xxxx_create_leads_table.php
public function up()
{
    Schema::create('leads', function (Blueprint $table) {
        $table->id();
        $table->string('name');
        $table->string('email');
        $table->string('phone')->nullable();
        $table->text('message')->nullable();
        
        // Campos de atribución
        $table->string('utm_source')->nullable();
        $table->string('utm_medium')->nullable();
        $table->string('utm_campaign')->nullable();
        $table->string('utm_content')->nullable();
        $table->string('utm_term')->nullable();
        
        // Click IDs
        $table->string('gclid')->nullable()->index();
        $table->string('fbclid')->nullable()->index();
        $table->string('msclkid')->nullable()->index();
        $table->string('ttclid')->nullable()->index();
        
        // Otros
        $table->text('referrer')->nullable();
        $table->timestamps();
        
        // Índices para reportes
        $table->index(['utm_source', 'utm_medium']);
        $table->index('created_at');
    });
}

Controller

// app/Http/Controllers/LeadController.php
namespace App\Http\Controllers;

use App\Models\Lead;
use Illuminate\Http\Request;

class LeadController extends Controller
{
    public function store(Request $request)
    {
        $validated = $request->validate([
            'name' => 'required|string|max:255',
            'email' => 'required|email',
            'phone' => 'nullable|string',
            'message' => 'nullable|string',
            
            // Campos de tracking (opcionales)
            'utm_source' => 'nullable|string',
            'utm_medium' => 'nullable|string',
            'utm_campaign' => 'nullable|string',
            'utm_content' => 'nullable|string',
            'utm_term' => 'nullable|string',
            'gclid' => 'nullable|string',
            'fbclid' => 'nullable|string',
            'msclkid' => 'nullable|string',
            'ttclid' => 'nullable|string',
            'referrer' => 'nullable|string',
        ]);

        $lead = Lead::create($validated);

        // Enviar a CRM, email, etc.
        // event(new LeadCreated($lead));

        return response()->json([
            'success' => true,
            'message' => 'Lead recibido correctamente'
        ]);
    }
}

⚛️ React / Next.js

Integración de Referrer Tracker en aplicaciones React y Next.js.

Next.js - Instalación

Añade el script en _document.js o _app.js:

// pages/_document.js
import { Html, Head, Main, NextScript } from 'next/document'

export default function Document() {
  return (
    <Html>
      <Head>
        <script src="/referrer-tracker.min.js"></script>
        <script
          dangerouslySetInnerHTML={{
            __html: `
              ReferrerTracker.configure({
                apiKey: '${process.env.NEXT_PUBLIC_REFERRER_TRACKER_API_KEY}'
              });
            `,
          }}
        />
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

React Hook para Formularios

// hooks/useReferrerTracker.js
import { useEffect, useState } from 'react';

export function useReferrerTracker() {
  const [trackingData, setTrackingData] = useState({});

  useEffect(() => {
    // Obtener datos de tracking cuando el componente se monta
    if (typeof window !== 'undefined' && window.ReferrerTracker) {
      const data = window.ReferrerTracker.getData();
      setTrackingData(data);
    }
  }, []);

  return trackingData;
}

Componente de Formulario

// components/ContactForm.jsx
import { useState } from 'react';
import { useReferrerTracker } from '../hooks/useReferrerTracker';

export default function ContactForm() {
  const [formData, setFormData] = useState({
    name: '',
    email: '',
    message: ''
  });
  const trackingData = useReferrerTracker();

  const handleSubmit = async (e) => {
    e.preventDefault();
    
    // Combinar datos del formulario con datos de tracking
    const payload = {
      ...formData,
      ...trackingData
    };

    const response = await fetch('/api/leads', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(payload)
    });

    if (response.ok) {
      alert('¡Gracias! Nos pondremos en contacto contigo.');
      setFormData({ name: '', email: '', message: '' });
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        value={formData.name}
        onChange={(e) => setFormData({...formData, name: e.target.value})}
        placeholder="Nombre"
        required
      />
      <input
        type="email"
        value={formData.email}
        onChange={(e) => setFormData({...formData, email: e.target.value})}
        placeholder="Email"
        required
      />
      <textarea
        value={formData.message}
        onChange={(e) => setFormData({...formData, message: e.target.value})}
        placeholder="Mensaje"
      />
      
      {/* Campos ocultos tradicionales (alternativa) */}
      <input type="hidden" name="utm_source" id="rt_source" />
      <input type="hidden" name="utm_medium" id="rt_medium" />
      <input type="hidden" name="gclid" id="rt_gclid" />
      
      <button type="submit">Enviar</button>
    </form>
  );
}

API Route (Next.js)

// pages/api/leads.js
export default async function handler(req, res) {
  if (req.method !== 'POST') {
    return res.status(405).json({ message: 'Method not allowed' });
  }

  const {
    name,
    email,
    message,
    utm_source,
    utm_medium,
    utm_campaign,
    gclid,
    fbclid,
    referrer
  } = req.body;

  // Guardar en base de datos
  // await prisma.lead.create({ data: { ... } });

  // Enviar a CRM
  // await sendToCRM({ ... });

  res.status(200).json({ success: true });
}

💚 Vue.js / Nuxt

Integración de Referrer Tracker en aplicaciones Vue.js y Nuxt.

Nuxt 3 - Instalación

Añade el script en app.vue o crea un plugin:

// plugins/referrer-tracker.client.js
export default defineNuxtPlugin(() => {
  if (process.client) {
    const script = document.createElement('script');
    script.src = '/referrer-tracker.min.js';
    script.onload = () => {
      window.ReferrerTracker.configure({
        apiKey: useRuntimeConfig().public.referrerTrackerApiKey
      });
    };
    document.head.appendChild(script);
  }
});

Configuración

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      referrerTrackerApiKey: process.env.REFERRER_TRACKER_API_KEY
    }
  }
})

Composable para Tracking

// composables/useReferrerTracker.js
export const useReferrerTracker = () => {
  const trackingData = ref({});

  onMounted(() => {
    if (window.ReferrerTracker) {
      trackingData.value = window.ReferrerTracker.getData();
    }
  });

  return {
    trackingData
  };
};

Componente de Formulario

<!-- components/ContactForm.vue -->
<template>
  <form @submit.prevent="handleSubmit">
    <input v-model="form.name" type="text" placeholder="Nombre" required>
    <input v-model="form.email" type="email" placeholder="Email" required>
    <textarea v-model="form.message" placeholder="Mensaje"></textarea>
    
    <!-- Campos ocultos -->
    <input type="hidden" name="utm_source" id="rt_source">
    <input type="hidden" name="gclid" id="rt_gclid">
    
    <button type="submit">Enviar</button>
  </form>
</template>

<script setup>
const { trackingData } = useReferrerTracker();
const form = ref({
  name: '',
  email: '',
  message: ''
});

const handleSubmit = async () => {
  const payload = {
    ...form.value,
    ...trackingData.value
  };

  await $fetch('/api/leads', {
    method: 'POST',
    body: payload
  });

  alert('¡Gracias!');
  form.value = { name: '', email: '', message: '' };
};
</script>

🔌 WordPress

WordPress es el CMS más utilizado del mundo. Referrer Tracker se integra fácilmente con cualquier theme y los plugins de formularios más populares.

Instalación en WordPress

Descargar plugin WordPress

Paso 1: Descarga y sube el script

  1. Descarga el archivo referrer-tracker.min.js desde tu Dashboard
  2. Súbelo a la raíz de tu WordPress (la misma carpeta donde está wp-config.php)

Tip: Puedes subirlo vía FTP, usando el administrador de archivos de tu hosting, o mediante un plugin como File Manager.

Paso 2: Añade el código de carga

Tienes dos opciones para cargar el script:

Opción A: Usando functions.php (Recomendado)

Añade este código en el archivo functions.php de tu theme hijo:

// Referrer Tracker - Añadir script de tracking
function add_referrer_tracker_script() {
    ?>
    <script>
    (function() {
        var script = document.createElement('script');
        script.src = '/referrer-tracker.min.js';
        script.setAttribute('data-api-key', 'TU_API_KEY');
        script.setAttribute('data-api-url', 'https://www.referrertracker.com');
        document.head.appendChild(script);
    })();
    </script>
    <?php
}
add_action('wp_head', 'add_referrer_tracker_script');
Opción B: Usando un plugin de snippets

Si usas plugins como Code Snippets o WPCode, crea un nuevo snippet con el código JavaScript y configúralo para ejecutarse en el <head>.

Contact Form 7

Contact Form 7 es el plugin de formularios más popular de WordPress. La integración es muy sencilla.

Paso 1: Añade los campos ocultos al formulario

Edita tu formulario en Contact Form 7 y añade estos campos ocultos:

[hidden rt_source id:rt_source]
[hidden rt_medium id:rt_medium]
[hidden rt_campaign id:rt_campaign]
[hidden rt_content id:rt_content]
[hidden rt_term id:rt_term]
[hidden rt_gclid id:rt_gclid]
[hidden rt_fbclid id:rt_fbclid]
[hidden rt_landing_page id:rt_landing_page]
[hidden rt_referrer id:rt_referrer]

Paso 2: Configura el email de notificación

En la pestaña "Mail" de tu formulario, añade las etiquetas para incluir los datos en el email:

--- Datos de Tracking ---
Fuente: [rt_source]
Medio: [rt_medium]
Campaña: [rt_campaign]
Landing Page: [rt_landing_page]
Google Click ID: [rt_gclid]
Facebook Click ID: [rt_fbclid]

¡Listo! Referrer Tracker detectará automáticamente los campos por su ID (con prefijo rt_) y los rellenará con los datos de tracking.

Gravity Forms

Gravity Forms es un plugin premium muy potente. Soporta campos ocultos de forma nativa.

Paso 1: Añade campos ocultos

  1. Edita tu formulario en Gravity Forms
  2. Añade un campo "Hidden" desde la sección "Advanced Fields"
  3. En la configuración del campo, establece el Field Name como rt_source
  4. En la pestaña "Advanced", añade el CSS Class: js-rt-source
  5. Repite para cada campo de tracking que necesites
Campos recomendados:
- rt_source (CSS Class: js-rt-source)
- rt_medium (CSS Class: js-rt-medium)
- rt_campaign (CSS Class: js-rt-campaign)
- rt_gclid (CSS Class: js-rt-gclid)
- rt_fbclid (CSS Class: js-rt-fbclid)
- rt_landing_page (CSS Class: js-rt-landing_page)
- rt_referrer (CSS Class: js-rt-referrer)

Alternativa: Usar gform_pre_render

Puedes añadir los campos dinámicamente con PHP:

// Añadir campos ocultos de tracking a Gravity Forms
add_filter('gform_pre_render', 'add_tracking_fields_to_gf');
function add_tracking_fields_to_gf($form) {
    // Añadir script para rellenar campos después de cargar
    ?>
    <script>
    document.addEventListener('DOMContentLoaded', function() {
        // Buscar campos por clase CSS
        var fields = ['source', 'medium', 'campaign', 'gclid', 'fbclid'];
        fields.forEach(function(field) {
            var input = document.querySelector('.js-rt-' + field + ' input');
            if (input) {
                input.id = 'rt_' + field;
            }
        });
    });
    </script>
    <?php
    return $form;
}

WPForms

WPForms es otro plugin popular con una interfaz muy intuitiva.

Paso 1: Añade campos ocultos

  1. Edita tu formulario en WPForms
  2. Arrastra un campo "Hidden Field" al formulario
  3. En la configuración, establece el Label como rt_source
  4. En "Advanced Options", añade la CSS Classes: js-rt-source
  5. Repite para cada campo de tracking

Nota: WPForms genera IDs dinámicos, por lo que es mejor usar las clases CSS (js-rt-*) para que Referrer Tracker detecte los campos.

Configurar con JavaScript

Si los campos no se detectan automáticamente, añade este script:

// WPForms - Asignar IDs a campos ocultos
document.addEventListener('DOMContentLoaded', function() {
    var mappings = {
        'rt_source': '.js-rt-source input',
        'rt_medium': '.js-rt-medium input',
        'rt_campaign': '.js-rt-campaign input',
        'rt_gclid': '.js-rt-gclid input',
        'rt_fbclid': '.js-rt-fbclid input'
    };
    
    Object.keys(mappings).forEach(function(id) {
        var input = document.querySelector(mappings[id]);
        if (input) input.id = id;
    });
});

Elementor Forms

Elementor Pro incluye un potente constructor de formularios. La integración requiere algunos pasos adicionales.

Paso 1: Añade campos ocultos en Elementor

  1. Edita tu página con Elementor
  2. Selecciona el widget de Form
  3. Añade un nuevo campo y selecciona tipo "Hidden"
  4. En el campo ID, escribe: rt_source
  5. Repite para cada campo de tracking
Campos a crear en Elementor Forms:
┌─────────────────┬──────────────────┐
│ Tipo            │ ID               │
├─────────────────┼──────────────────┤
│ Hidden          │ rt_source        │
│ Hidden          │ rt_medium        │
│ Hidden          │ rt_campaign      │
│ Hidden          │ rt_content       │
│ Hidden          │ rt_term          │
│ Hidden          │ rt_gclid         │
│ Hidden          │ rt_fbclid        │
│ Hidden          │ rt_landing_page  │
│ Hidden          │ rt_referrer      │
└─────────────────┴──────────────────┘

Paso 2: Verificar que los IDs se aplican correctamente

Elementor a veces modifica los IDs. Añade este script para asegurar la compatibilidad:

// Elementor Forms - Compatibilidad con Referrer Tracker
document.addEventListener('DOMContentLoaded', function() {
    // Elementor usa data-id, necesitamos mapear a id
    var fields = document.querySelectorAll('.elementor-field-group input[type="hidden"]');
    
    fields.forEach(function(field) {
        var wrapper = field.closest('.elementor-field-group');
        if (wrapper) {
            var fieldId = wrapper.getAttribute('data-id');
            if (fieldId && fieldId.startsWith('rt_')) {
                field.id = fieldId;
            }
        }
    });
});

Paso 3: Configurar las acciones del formulario

En la configuración del formulario de Elementor:

  1. Ve a Actions After Submit
  2. Si usas Email, los campos ocultos se incluirán automáticamente
  3. Si usas Webhook, los campos se enviarán en el payload JSON

Integración con CRMs: Si conectas Elementor con HubSpot, Mailchimp u otros CRMs mediante las acciones nativas, los campos de tracking se enviarán automáticamente.

Fluent Forms

Fluent Forms es una alternativa ligera y rápida.

// Fluent Forms - Añadir campos ocultos via shortcode
// Usa el shortcode en tu formulario:
[fluentform_hidden name="rt_source" id="rt_source"]
[fluentform_hidden name="rt_medium" id="rt_medium"]
[fluentform_hidden name="rt_campaign" id="rt_campaign"]
[fluentform_hidden name="rt_gclid" id="rt_gclid"]
[fluentform_hidden name="rt_fbclid" id="rt_fbclid"]

Ninja Forms

Ninja Forms soporta campos ocultos de forma nativa:

  1. Añade un campo "Hidden" al formulario
  2. En Administration → Field Key, escribe: rt_source
  3. En Display → Custom CSS Classes, añade: js-rt-source

Verificar la Integración

Para verificar que todo funciona correctamente:

  1. Visita tu web con parámetros UTM: ?utm_source=test&utm_medium=test
  2. Abre las DevTools del navegador (F12)
  3. En la consola, escribe: ReferrerTracker.getData()
  4. Verifica que los datos aparecen correctamente
  5. Envía un formulario de prueba y verifica que los campos ocultos contienen los datos

Debug: Si los campos no se rellenan, verifica en la consola que no hay errores y que el script se ha cargado correctamente. Usa ReferrerTracker.debug() para ver información detallada.

Shopify

Próximamente

Estamos trabajando en una guía completa de integración con Shopify, incluyendo:

  • Instalación en theme.liquid
  • Tracking en checkout
  • Atribución de conversiones
  • Integración con Shopify Flow

Mientras tanto, puedes añadir el script manualmente en tu theme de Shopify.