Skip to main content

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.