# evoLeadGate: referencia

> Referencia de evoLeadGate: campos del elemento, opciones de entrega, eventos de analítica, evento de Joomla, API REST, herramientas de evoMCP y límites.

# evoLeadGate: referencia

## Elemento «Lead magnet»

Las etiquetas del constructor están en castellano. Los valores por defecto son los del elemento recién añadido.

### Pestaña Formulario

| Opción | Qué hace | Por defecto |
| --- | --- | --- |
| ID del formulario | Identificador único del formulario. Se normaliza a minúsculas, sin acentos ni espacios, con guiones (solo letras a-z y cifras). Se guarda en cada lead y se envía en los eventos de analítica. Sin él, el formulario no se muestra. | vacío |
| Campos adicionales | Lista de campos (ver más abajo). El email siempre se pide y no forma parte de esta lista. Máximo 20; los sobrantes se ignoran. | un campo «Nombre» de ejemplo |
| Archivo de descarga | Archivo que se entrega. Debe estar en `images/evoleadgate-privado/`. Acepta la ruta que guarda el selector (`images/evoleadgate-privado/…`); si apunta a otra carpeta, se descarta. | vacío |

### Pestaña Textos

| Opción | Qué hace | Por defecto |
| --- | --- | --- |
| Título | Título sobre el formulario. | vacío |
| Elemento del título | Etiqueta HTML del título: H2, H3, H4 o Div. | H3 |
| Descripción | Texto enriquecido bajo el título. | vacío |
| Texto del botón de envío | Texto del botón. | texto del idioma del sitio («Descargar») |
| Mensaje de éxito | Mensaje tras enviar. | texto del idioma del sitio |

### Pestaña Entrega y avisos

| Opción | Qué hace | Por defecto |
| --- | --- | --- |
| Entrega | «Descarga inmediata y email» o «Solo por email (doble opt-in)». Ver «Modos de entrega» más abajo. | Descarga inmediata y email |
| Emails de aviso | Uno o varios destinatarios del aviso de cada lead, separados por comas, punto y coma, espacios o saltos de línea. Las direcciones no válidas se descartan. Si queda vacío se usa el email de aviso por defecto de las opciones. | vacío |

### Pestaña Consentimiento

| Opción | Qué hace | Por defecto |
| --- | --- | --- |
| Texto de privacidad (obligatorio) | Texto de la casilla de privacidad, que el visitante debe marcar. | texto del idioma del sitio («Acepto la política de privacidad») |
| Texto del enlace | Texto del enlace a la política. | texto del idioma del sitio («Ver política») |
| Enlace a la política de privacidad | URL de la política. Se abre en una pestaña nueva. Sin ella no se muestra el enlace. | vacío |
| Texto de comunicaciones comerciales (opcional) | Texto de la casilla de comunicaciones comerciales. Si queda vacío, la casilla no se muestra. Se muestra sin marcar. | vacío |

El texto exacto de cada casilla se guarda con el lead en el momento del envío.

### Pestaña Analítica

| Opción | Qué hace | Por defecto |
| --- | --- | --- |
| Evento de Analytics | Nombre del evento que se añade al `dataLayer`. | `generate_lead` |
| Conversión de Google Ads | Formato `AW-XXXXXXX/etiqueta`. Vacío si no usas Google Ads. | vacío |
| Evento de Meta Ads | Nombre del evento que se envía a `fbq`. | `Lead` |

### Pestaña Ajustes y Avanzado

Opciones habituales de YOOtheme: márgenes superior e inferior, ancho máximo, alineación del bloque y del texto, animación y visibilidad. Márgenes por defecto: «default» arriba y abajo. La pestaña Avanzado trae las opciones estándar del constructor.

### Elemento hijo «Campo»

| Opción | Qué hace |
| --- | --- |
| Etiqueta | Texto que ve el visitante. De ella sale el nombre interno del campo (minúsculas, sin acentos, con guiones bajos y sin repetirse dentro del formulario). Los campos sin etiqueta se ignoran. |
| Tipo | Texto, Teléfono, Desplegable o Casilla. |
| Obligatorio | Marca el campo como obligatorio. |
| Texto de ayuda | Texto de ayuda dentro del campo. Solo para Texto y Teléfono. |
| Opciones | Una opción por línea. Solo para Desplegable. Máximo 50 opciones de hasta 100 caracteres; las repetidas se descartan. |

Validación en el servidor, siempre contra la definición firmada del formulario:

| Tipo | Regla |
| --- | --- |
| Email | Se pasa a minúsculas, máximo 190 caracteres, formato de email válido. |
| Texto | Máximo 255 caracteres. |
| Teléfono | De 6 a 30 caracteres entre cifras, `+`, `(`, `)`, `-`, `.` y espacios. |
| Desplegable | El valor debe ser una de las opciones definidas. |
| Casilla | Se guarda `1` si está marcada y vacío si no. Si es obligatoria, debe estar marcada. |

## Modos de entrega

| Modo | Valor | Comportamiento |
| --- | --- | --- |
| Descarga inmediata y email | `instant_email` | Al enviar, el visitante ve un botón de descarga. También recibe un email con el enlace. |
| Solo por email (doble opt-in) | `email_only` | Al enviar, el visitante solo ve que se le ha enviado un email. No recibe enlace en pantalla. El primer uso válido del enlace marca el email del lead como verificado. |

En los dos modos:

- el aviso va a los emails de aviso del formulario o, si no hay, al email por defecto de las opciones. Si no hay ningún destinatario, el estado del aviso queda como `skipped`;
- el email de entrega va a la dirección escrita en ese mismo formulario;
- un fallo de correo no impide guardar el lead; queda como `failed` en su estado;
- el enlace de descarga sirve las veces que haga falta hasta que caduca. Cada descarga se registra;
- el archivo se entrega por PHP como adjunto, sin exponer su ruta real. Un enlace caducado responde 410; un enlace desconocido o un archivo que ya no está responde 404.

## Eventos de analítica

Tras un envío correcto, el script del formulario hace lo siguiente en el navegador:

| Acción | Condición |
| --- | --- |
| `dataLayer.push({event: <Evento de Analytics>, form_id, event_id})` | Siempre. |
| `gtag('event', 'conversion', {send_to: <Conversión de Google Ads>})` | Si hay un valor en «Conversión de Google Ads» y `gtag` es una función. |
| `fbq('track', <Evento de Meta Ads>, {}, {eventID: event_id})` | Si `fbq` es una función. |
| `dataLayer.push({event: 'file_download', form_id})` | Al hacer clic en el botón de descarga (solo en entrega inmediata). |

`event_id` es el UUID del lead, así que coincide con el `event_id` que ves en el detalle del lead y sirve para deduplicar conversiones.

El script no consulta el estado del consentimiento. Detecta si `gtag` y `fbq` existen: los píxeles los carga tu sitio, por ejemplo desde el panel de scripts de YOOtheme en la categoría de marketing, y solo existen si el visitante los ha aceptado. El script no carga scripts de terceros; lo que hagan `gtag` y `fbq` depende de cómo los cargues tú.

## Evento de Joomla para integraciones

Cada lead nuevo dispara un evento de Joomla después de guardarse y de enviar los emails:

|  |  |
| --- | --- |
| Nombre | `onEvoleadgateLeadCreated` |
| Grupo de plugins | `evoleadgate` (se importa antes de lanzar el evento) |
| Argumento | `lead`: array con todas las columnas del lead más su `id` |

El argumento incluye también la IP guardada, el agente de usuario, los consentimientos, los datos de atribución y el token de descarga. Trátalo como dato personal y como credencial. Si tu plugin lanza una excepción, se ignora: no impide guardar el lead.

Fragmento mínimo de un plugin suscrito:

```
public static function getSubscribedEvents(): array
{
    return ['onEvoleadgateLeadCreated' => 'onLead'];
}

public function onLead(\Joomla\Event\Event $event): void
{
    $lead = $event->getArgument('lead'); // ['id' => ..., 'email' => ..., 'form_id' => ..., ...]
}
```

## API REST (solo lectura)

La proporciona el plugin de servicios web del paquete. Usa la cabecera `X-Joomla-Token` y requiere un usuario con el permiso `core.manage` sobre `com_evoleadgate`. Las respuestas no se cachean.

| Método y ruta | Qué devuelve |
| --- | --- |
| `GET /api/index.php/v1/evoleadgate/leads` | Lista de leads, del más reciente al más antiguo. Parámetros: `filter_form` (ID del formulario), `page[limit]` (de 1 a 100, por defecto 20), `page[offset]`. Atributos: `form_id`, `email`, `verified`, `delivery`, `created`. Incluye `meta.total-items`. |
| `GET /api/index.php/v1/evoleadgate/leads/{id}` | Un lead: `form_id`, `email`, `fields`, `source_url`, `consent_privacy`, `consent_marketing`, `consented_at`, `verified`, `delivery`, `utm_source`, `utm_medium`, `utm_campaign`, `created`. |

Ninguna de las dos incluye la IP ni el agente de usuario. No hay rutas de escritura. Con un usuario sin permiso responden 403.

## Herramientas para evoMCP (opcional)

Si tienes [evoMCP](https://evoaddons.com/es/productos/evomcp) instalado, el plugin `evomcp` del paquete registra estas herramientas bajo el componente «evoLeadGate». Requieren `core.manage` sobre `com_evoleadgate` y los permisos de la conexión MCP.

| Herramienta | Permiso | Qué hace |
| --- | --- | --- |
| `evoleadgate_list_leads` | lectura | Lista leads con filtros (formulario, email, verificado, fechas) y paginación de hasta 100. Marcada como dato personal. |
| `evoleadgate_get_lead` | lectura | Un lead con sus campos, consentimientos, UTM y estado de los emails. No incluye IP ni agente de usuario. |
| `evoleadgate_lead_stats` | lectura | Leads por formulario y por día, sin datos personales. |
| `evoleadgate_delete_leads` | escritura | Borra hasta 50 leads con sus descargas. Exige además `core.delete` y siempre aprobación humana. Admite `dry_run`. |

## Puntos de entrada del componente

Informativo: el script del formulario los usa, y no están pensados para llamarlos a mano.

| Entrada | Uso |
| --- | --- |
| `GET /index.php?option=com_evoleadgate&format=json&task=lead.token` | Devuelve un token CSRF vigente. El script lo pide al cargar, para que el formulario funcione con la página en caché. |
| `POST /index.php?option=com_evoleadgate&format=json&task=lead.submit` | Recibe el envío. Respuestas: 200 con `ok`, `event_id`, `delivery` y, en entrega inmediata, `download_url`; 422 con los errores por campo; 400 si el antispam bloquea el envío o la configuración firmada no es válida; 403 si falla el token CSRF; 503 si el archivo ya no está disponible. |
| `GET /?option=com_evoleadgate&task=lead.download&token=<token>` | Entrega el archivo con un enlace válido. |

La configuración del formulario viaja en un campo oculto firmado con HMAC-SHA256 con el secreto del sitio, sin caducidad. Cambiar el secreto de Joomla invalida los formularios que sigan en caché hasta que se vuelvan a generar.

## Límites

| Límite | Valor |
| --- | --- |
| Campos adicionales por formulario | 20 |
| Opciones de un desplegable | 50, de hasta 100 caracteres |
| Archivos por formulario | 1 |
| Campos de texto | 255 caracteres |
| Email | 190 caracteres |
| Leads por llamada de la API REST | 100 |
| Leads por borrado desde evoMCP | 50 |

---

https://evoaddons.com/es/documentacion/evoleadgate-referencia