# Referencia de evoOrigin

> Referencia de evoOrigin 1.1.6: datos de sesión, evento onEvooriginLead, rutas de la API REST, herramientas MCP, tablas y reglas de captura.

# Referencia de evoOrigin

## Datos que se guardan en la sesión

El plugin de sistema escribe en la sesión de Joomla un array bajo la clave configurada (por defecto `evo_origin`). Estas son sus claves:

| Clave | Contenido | Límite |
| --- | --- | --- |
| `gclid`, `gbraid`, `wbraid`, `msclkid`, `fbclid` | Valor del parámetro de la URL | 100 caracteres |
| `utm_source`, `utm_medium`, `utm_campaign` | Valor del parámetro de la URL | 100 caracteres |
| `hsa_cam` | Valor del parámetro de la URL | 100 caracteres |
| `referer` | Dominio del referer externo del primer contacto, en minúsculas y sin `www.` | 150 caracteres |
| `referer_interno` | `1` si el primer referer era un dominio propio |  |

Reglas de captura:

- Un parámetro de la URL sustituye al valor anterior cada vez que aparece.
- El referer se guarda una sola vez por sesión: el primero que no sea propio. Solo se guarda el dominio, no la URL.
- Un referer cuyo dominio coincide con uno de los *Dominios propios* (o con un subdominio) no cuenta como origen externo.
- Solo se captura en el frontal, en peticiones GET con formato HTML, y se omiten `com_ajax`, las peticiones con la cabecera `X-Requested-With` y los agentes de usuario que contienen «bot», «crawl» o «spider».

## Registro de la visita

Con *Registrar visitas* activo:

- Se escribe como máximo una fila por sesión de Joomla (el identificador de sesión se guarda como HMAC-SHA256 con una sal derivada del secreto del sitio, no en claro).
- La fila se escribe solo si la sesión trae algún origen: fuente, medio, campaña, referer o algún identificador de clic.
- La página de entrada se guarda sin query.
- Si el visitante se identifica después en la misma sesión, la fila recibe su `user_id`.
- Los identificadores de clic solo se guardan si *Guardar identificadores de clic* está activo.
- En las estadísticas, una fuente vacía se muestra como `(direct)` y un medio vacío como `(none)`.

## Evento `onEvooriginLead`

Lo lanza la extensión que crea el lead. evoOrigin lee el origen de la sesión actual y guarda el resumen.

| Argumento | Contenido | Formato |
| --- | --- | --- |
| `refType` | Tipo de referencia (por ejemplo, `offer`) | Letras, números, `_`, `.` y `-`; hasta 50 caracteres |
| `refId` | Identificador de la referencia | Lo anterior y `:`; hasta 100 caracteres |

```
use Joomla\CMS\Factory;
use Joomla\Event\Event;

Factory::getApplication()->getDispatcher()->dispatch(
    'onEvooriginLead',
    new Event('onEvooriginLead', ['refType' => 'offer', 'refId' => (string) $offerId])
);
```

Comportamiento:

- Si *Guardar la atribución de leads* está apagado, o los argumentos no cumplen el formato, no hace nada.
- Cada pareja `refType` + `refId` tiene una sola fila.
- La primera vez guarda el primer origen y el último origen iguales. En las siguientes, actualiza el último origen solo si la sesión trae algún origen, y suma uno al contador `visits` cada vez que se lanza el evento.
- Un error al guardar la atribución nunca impide que se cree el lead.

## API REST

Rutas de solo lectura. Usa la cabecera `X-Joomla-Token: <token>` y el permiso `core.manage` sobre `com_evoorigin`. Sin ese permiso, la API devuelve 403.

| Método y ruta | Devuelve |
| --- | --- |
| `GET /api/index.php/v1/evoorigin/stats` | Contadores mensuales: `month`, `source`, `medium`, `campaign`, `visits`. |
| `GET /api/index.php/v1/evoorigin/visits` | Visitas: `ip`, `user_id`, `landing`, `source`, `medium`, `campaign`, `referer`, `created`. |
| `GET /api/index.php/v1/evoorigin/leads` | Resúmenes de atribución de leads. |
| `GET /api/index.php/v1/evoorigin/leads/:id` | Un resumen por su id numérico. |

Parámetros:

| Ruta | Parámetro | Efecto |
| --- | --- | --- |
| `stats` | `filter_month` | Mes en formato `YYYY-MM` |
| `visits` | `filter_source`, `filter_campaign` | Filtra por valor exacto |
| `leads` | `filter_ref_type` | Filtra por tipo de referencia |
| `visits`, `leads` | `page[limit]`, `page[offset]` | Paginación; el límite va de 1 a 100 (20 por defecto) |

Las respuestas no se guardan en caché. La IP de las visitas sale siempre truncada; si estaba guardada como hash, aparece `(hash)`. Los resúmenes de leads no incluyen los identificadores de clic. Las estadísticas suman el detalle que aún se conserva y los contadores ya agregados.

## Herramientas MCP (evoMCP)

Las incluye el plugin del grupo `evomcp`. Hacen falta evoMCP y que la conexión tenga permiso sobre el componente `evoorigin`. Además, el usuario necesita `core.manage` sobre `com_evoorigin` (y `core.delete` para borrar).

| Herramienta | Permiso en evoMCP | Qué hace |
| --- | --- | --- |
| `evoorigin_stats` | Lectura (estadísticas) | Visitas por mes, fuente, medio y campaña. Parámetro opcional `month`. |
| `evoorigin_list_visits` | Lectura (visitas) | Lista visitas, con IP truncada. Filtros `source`, `campaign`, `limit` (1 a 100), `offset`. Devuelve datos personales. |
| `evoorigin_list_leads` | Lectura (leads) | Lista resúmenes de atribución. Filtros `ref_type`, `limit`, `offset`. |
| `evoorigin_get_lead_attribution` | Lectura (leads) | Atribución de un lead por `ref_type` y `ref_id`. |
| `evoorigin_delete_visits` | Escritura (visitas) | Elimina hasta 100 visitas por id. Exige aprobación humana. |
| `evoorigin_delete_leads` | Escritura (leads) | Elimina hasta 100 resúmenes por id. Exige aprobación humana. |
| `evoorigin_purge_now` | Escritura (visitas) | Ejecuta la purga de retención ahora. Exige aprobación humana. |

Las herramientas de escritura admiten `dry_run`. Con él, el borrado indica qué eliminaría y la purga devuelve los plazos configurados, sin tocar datos. Ninguna herramienta devuelve la IP completa.

## Tablas

Con el prefijo de tablas de tu Joomla:

| Tabla | Nivel | Columnas |
| --- | --- | --- |
| `evoorigin_visits` | 1 | `id`, `session_hash`, `user_id`, `ip`, `landing`, `source`, `medium`, `campaign`, `referer`, `click_ids`, `created` |
| `evoorigin_leads` | 2 | `id`, `ref_type`, `ref_id`, `first_*` y `last_*` (`source`, `medium`, `campaign`, `referer`, `at`), `visits`, `click_ids`, `created`, `updated` |
| `evoorigin_stats` | 3 | `month`, `source`, `medium`, `campaign`, `visits` |

## Tarea programada

El tipo de tarea es `evoorigin.purge`. Cada ejecución hace tres cosas:

1. Suma a las estadísticas las visitas anteriores al plazo de retención del detalle y las borra, en lotes de 1000. Si falla la suma, no borra.
2. Quita los identificadores de clic de las visitas y de los leads anteriores a su plazo, sin borrar la fila.
3. Borra los resúmenes de leads cuya última interacción es anterior al plazo en meses.

La purga se ejecuta aunque el registro de visitas esté apagado, de modo que los datos que ya existieran se siguen purgando.

---

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