Reader Events & Tag Manager Integration

The Joomag Viewer emits real‑time reader events as readers open and move through a publication. You can consume these events in three ways, and they all carry the same data:

1. Plain JavaScript — listen for events on document (great for custom code or your own SDKs).
2. Google Tag Manager (GTM) — events are pushed to your container’s data layer.
3. Ensighten (CHEQ) — events are fired as native Ensighten events for your rules to act on.

This lets you forward reader activity to any analytics destination (Google Analytics, Adobe Analytics, etc.) using the tools you already know.

Events

Event	Fired when
joomag.magazine.viewed	The reader opens the publication.
joomag.magazine.page.viewed	The reader views a page (fires on every page turn).
joomag.reader.identified	The reader becomes identified.

Single-page application

The Viewer is a single‑page application: as the reader turns pages or moves between articles, the URL changes without a full page reload. joomag.magazine.page.viewed is your reliable signal for a page/virtual‑page view — prefer it over a tag manager’s generic “history change” trigger.

The data model

Every event carries one payload with two parts:

{
  "reader": {
    "uuid": "957e5291-d378-4c4c-8be6-957845d4aaa7",
    "email": "reader@example.com",
    "timezone": "America/New_York",
    "first_name": "Nobo",
    "last_name": "Moko"
  },
  "event_data": {
    "publication_id": "0956205001697194622",
    "url": "https://viewer.joomag.com/january/0956205001697194622",
    "datetime": "2024-04-12T07:53:10.000Z",
    "page_number": 1
  }
}

• reader — who triggered the event. email / first_name / last_name are present only once the reader is identified; before that you’ll have just the anonymous uuid.
• event_data — everything about this specific event occurrence: which publication, the browser URL at the moment it fired, when it fired, plus any per‑event fields (see the table below).

In addition, static publication and publisher metadata is made available to your tag manager when the page loads (see Static page context), so you can enrich any event with the publication title, publisher company, etc.

event_data per event

publication_id, url, and datetime are present on every event. The extra field depends on the event:

Event	event_data
joomag.magazine.viewed	publication_id, url, datetime
joomag.magazine.page.viewed	publication_id, url, datetime, page_number
joomag.reader.identified	publication_id, url, datetime, identification_source

---

Setup

In your publication’s Viewer settings, connect the tag manager you use:

• Google Tag Manager — enable it and enter your container ID (e.g. GTM-XXXXXXX).
• Ensighten (CHEQ) — paste your Ensighten Bootstrap URL (e.g. //nexus.ensighten.com/<client>/<space>/Bootstrap.js, or your own first‑party serving URL).

No setup is needed for the plain‑JavaScript (document) events — they are always available in the reader’s browser.

Caution

Reader events fire for readers only. They are not emitted when you preview your own publication as the account owner.

---

Integration

1. Plain JavaScript (document events)

Listen on document; the payload is in event.detail:

document.addEventListener('joomag.magazine.page.viewed', (event) => {
  const { reader, event_data } = event.detail;
  console.log('Page', event_data.page_number, 'of', event_data.publication_id, 'by', reader.email);
});

document.addEventListener('joomag.reader.identified', (event) => {
  console.log('Identified:', event.detail.reader.email,
              'via', event.detail.event_data.identification_source);
});

document.addEventListener('joomag.magazine.viewed', (event) => {
  console.log('Opened:', event.detail.event_data.publication_id);
});

2. Google Tag Manager

Each event is pushed to your container’s data layer namespaced under a joomag key, with the event name as the GTM event:

// what your container receives, per event
{
  "event": "joomag.magazine.page.viewed",
  "joomag": {
    "reader":     { "uuid": "…", "email": "reader@example.com", "timezone": "America/New_York", "first_name": "Nobo", "last_name": "Moko" },
    "event_data": { "publication_id": "0956205001697194622", "url": "https://…", "datetime": "2024-04-12T07:53:10.000Z", "page_number": 1 }
  }
}

The static page context (joomag.publication, joomag.publisher) is loaded into the same data layer, so when you read a variable like {{joomag.publication.title}} it resolves alongside the event data.

To set it up:

1. Create a Custom Event trigger that matches the event name, e.g. joomag.magazine.page.viewed.
2. Create Data Layer Variables for the keys you need:
   • joomag.event_data.page_number, joomag.event_data.url, joomag.event_data.datetime, joomag.event_data.publication_id
   • joomag.reader.email, joomag.reader.uuid
   • joomag.publication.title, joomag.publication.publish_date, joomag.publisher.company (static context)
3. Add your destination tag (e.g. a GA4 event tag), map those variables to parameters, and fire it on the trigger.

Note

The static context and events use the same joomag.* paths, so a single set of Data Layer Variables works across all events. Event‑specific values live under joomag.event_data.* and are refreshed on every event.

3. Ensighten (CHEQ) — e.g. to Adobe Analytics

Each event is fired as a native Ensighten Named Event via Bootstrapper.ensEvent.trigger(<event name>, <payload>), where the payload is the object shown in The data model. Inside a tag or rule that fires for the event, the payload’s keys are available on this — e.g. this.event_data.page_number, this.reader.email.

The static page context is provided separately as a JavaScript object you read with a Data Definition:

window.ensightenDataLayer.joomag.publication // { id, title, publish_date, page_count }
window.ensightenDataLayer.joomag.publisher   // { account_id, company }

To set it up:

1. In Ensighten Manage, create a Named Event for each event you want to act on, naming it to match the event exactly (e.g. joomag.magazine.page.viewed), then Publish it to your Tag Delivery Network. Joomag fires events by name — if no matching, published Named Event exists, nothing happens.
2. Create a Data Definition (type JavaScript variable) for each static field you need, e.g. ensightenDataLayer.joomag.publication.title.
3. Bind your destination tag (e.g. Adobe Analytics / AppMeasurement) to the Named Event. Read the event’s own values from this inside the tag (this.event_data.page_number, this.reader.email, …) and the static values from your Data Definitions.

See Ensighten’s Getting Started with Events and Create a Named Event for full details.

Quick QA in the browser console (note the array of names, the regular function, and this for the data):

Bootstrapper.ensEvent.add(['joomag.magazine.page.viewed'], function () {
  console.log(this.event_data, this.reader);
});

Turn a page in the viewer and you should see the payload logged.

---

Field reference

reader

Field	Description
uuid	Anonymous, stable reader identifier. Always present.
email	Reader email. Present once identified.
first_name, last_name	Reader name, when known.
timezone	Reader’s time zone (IANA name).

Custom reader properties you pass during identification (via query params or JWT) also appear under reader.

event_data

Field	Present on	Description
publication_id	all events	The publication’s ID. Matches joomag.publication.id.
url	all events	The browser address (window.location.href) at the moment the event fired. Updates per page in the SPA.
datetime	all events	When the event fired (ISO 8601, UTC).
page_number	page.viewed	The page being viewed.
identification_source	reader.identified	How the reader was identified (e.g. query_params, subscribe_form, reader_login).

Static page context

Loaded once when the publication opens, available to GTM (joomag.publication / joomag.publisher in the data layer) and Ensighten (window.ensightenDataLayer.joomag.*):

Object	Fields
publication	id, title, publish_date, page_count
publisher	account_id, company

Tip

Use event_data.publication_id to correlate an event with the static publication context.