# evoOrigin reference

> evoOrigin 1.1.6 reference: session data, the onEvooriginLead event, REST API routes, MCP tools, database tables and capture rules.

# evoOrigin reference

## Data kept in the session

The system plugin writes an array to the Joomla session under the configured key (`evo_origin` by default). Its keys are:

| Key | Content | Limit |
| --- | --- | --- |
| `gclid`, `gbraid`, `wbraid`, `msclkid`, `fbclid` | URL parameter value | 100 characters |
| `utm_source`, `utm_medium`, `utm_campaign` | URL parameter value | 100 characters |
| `hsa_cam` | URL parameter value | 100 characters |
| `referer` | Domain of the first-contact external referer, lower case and without `www.` | 150 characters |
| `referer_interno` | `1` if the first referer was one of your own domains |  |

Capture rules:

- A URL parameter replaces the previous value each time it appears.
- The referer is stored once per session: the first one that is not your own. Only the domain is stored, not the URL.
- A referer whose domain matches one of the *Own domains* (or a subdomain of one) does not count as an external origin.
- Capture happens only on the frontend, on GET requests with HTML format. `com_ajax`, requests carrying the `X-Requested-With` header and user agents containing "bot", "crawl" or "spider" are skipped.

## Visit logging

With *Log visits* on:

- At most one row is written per Joomla session (the session identifier is stored as an HMAC-SHA256 with a salt derived from the site secret, not in the clear).
- The row is written only if the session carries an origin: source, medium, campaign, referer or a click identifier.
- The landing page is stored without its query string.
- If the visitor identifies themselves later in the same session, the row gets their `user_id`.
- Click identifiers are stored only if *Store click identifiers* is on.
- In the statistics, an empty source is shown as `(direct)` and an empty medium as `(none)`.

## The `onEvooriginLead` event

The extension that creates the lead triggers it. evoOrigin reads the origin from the current session and stores the summary.

| Argument | Content | Format |
| --- | --- | --- |
| `refType` | Reference type (for example, `offer`) | Letters, numbers, `_`, `.` and `-`; up to 50 characters |
| `refId` | Reference identifier | As above plus `:`; up to 100 characters |

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

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

Behaviour:

- If *Store lead attribution* is off, or the arguments do not match the format, it does nothing.
- Each `refType` + `refId` pair has a single row.
- The first time, it stores the first and last origin as the same value. On later calls it updates the last origin only if the session carries an origin, and adds one to the `visits` counter every time the event is triggered.
- An error while storing attribution never prevents the lead from being created.

## REST API

Read-only routes. Use the `X-Joomla-Token: <token>` header and the `core.manage` permission on `com_evoorigin`. Without it, the API returns 403.

| Method and route | Returns |
| --- | --- |
| `GET /api/index.php/v1/evoorigin/stats` | Monthly counters: `month`, `source`, `medium`, `campaign`, `visits`. |
| `GET /api/index.php/v1/evoorigin/visits` | Visits: `ip`, `user_id`, `landing`, `source`, `medium`, `campaign`, `referer`, `created`. |
| `GET /api/index.php/v1/evoorigin/leads` | Lead attribution summaries. |
| `GET /api/index.php/v1/evoorigin/leads/:id` | One summary by numeric id. |

Parameters:

| Route | Parameter | Effect |
| --- | --- | --- |
| `stats` | `filter_month` | Month in `YYYY-MM` format |
| `visits` | `filter_source`, `filter_campaign` | Filters by exact value |
| `leads` | `filter_ref_type` | Filters by reference type |
| `visits`, `leads` | `page[limit]`, `page[offset]` | Pagination; the limit runs from 1 to 100 (20 by default) |

Responses are not cached. The IP in visits is always returned truncated; if it was stored as a hash, `(hash)` appears. Lead summaries do not include click identifiers. The statistics add up the detail still kept and the counters already aggregated.

## MCP tools (evoMCP)

They come from the `evomcp` group plugin. You need evoMCP, and the connection must have permission on the `evoorigin` component. The user also needs `core.manage` on `com_evoorigin` (and `core.delete` to delete).

| Tool | evoMCP permission | What it does |
| --- | --- | --- |
| `evoorigin_stats` | Read (statistics) | Visits by month, source, medium and campaign. Optional `month` parameter. |
| `evoorigin_list_visits` | Read (visits) | Lists visits, with a truncated IP. Filters `source`, `campaign`, `limit` (1 to 100), `offset`. Returns personal data. |
| `evoorigin_list_leads` | Read (leads) | Lists attribution summaries. Filters `ref_type`, `limit`, `offset`. |
| `evoorigin_get_lead_attribution` | Read (leads) | Attribution of one lead by `ref_type` and `ref_id`. |
| `evoorigin_delete_visits` | Write (visits) | Deletes up to 100 visits by id. Requires human approval. |
| `evoorigin_delete_leads` | Write (leads) | Deletes up to 100 summaries by id. Requires human approval. |
| `evoorigin_purge_now` | Write (visits) | Runs the retention purge now. Requires human approval. |

The write tools support `dry_run`. With it, deletion reports what it would remove and the purge returns the configured periods, without touching data. No tool returns the full IP.

## Tables

With your Joomla table prefix:

| Table | Level | Columns |
| --- | --- | --- |
| `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_*` and `last_*` (`source`, `medium`, `campaign`, `referer`, `at`), `visits`, `click_ids`, `created`, `updated` |
| `evoorigin_stats` | 3 | `month`, `source`, `medium`, `campaign`, `visits` |

## Scheduled task

The task type is `evoorigin.purge`. Each run does three things:

1. Adds to the statistics the visits older than the detail retention period and deletes them, in batches of 1000. If the aggregation fails, nothing is deleted.
2. Removes click identifiers from visits and leads older than their period, without deleting the row.
3. Deletes lead summaries whose last interaction is older than the period in months.

The purge runs even when visit logging is off, so data that already existed keeps being purged.

---

https://evoaddons.com/en/documentation/evoorigin-reference