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.magazine.page.hotspot.activated	A hotspot is activated — a link, pop‑up, video, form, etc.
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,
    "page_name": "Cover"
  }
}

• 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, page_name
joomag.magazine.page.hotspot.activated	publication_id, url, datetime, type, name, target, tooltip, page_number, page_name, tags
joomag.reader.identified	publication_id, url, datetime, identification_source

page_name, tooltip, and tags are included only when set.

Hotspot types

joomag.magazine.page.hotspot.activated fires for every hotspot interactive item — when a reader activates one (e.g. clicks a link or pop-up) and when a pop-up is set to auto-open on page load. The type field tells you which kind it is, name is a human‑readable label (the same one shown in your Hotspots Performance report, with a fallback when the hotspot is untitled), and target is the machine‑usable value — its meaning depends on type:

type	name	target
link	the URL	the URL
mailto	the email address	the email address
phone	the phone number	the phone number
go_to_page	Go to page N	the destination page number
article	(Article)	the article ID
webpage_popup	the URL	the URL
youtube_popup	the video title	the YouTube video ID
vimeo_popup	the video title	the Vimeo video ID
image_popup	the image name	the image name
video_popup	the video name	the video name
form_popup	the form name	the form name
custom_popup	the custom pop‑up name	the custom pop‑up name

page_number is the page the hotspot sits on, tooltip (when set) is the tooltip text you gave the hotspot in the editor, and tags (when set) are the tags you placed on the hotspot element.

Note

Pop-ups set to auto-open on page load fire this event as well, and aren’t distinguishable from a click — so for pop-up types the count includes auto-opens, not only clicks.

Example event.detail for a YouTube hotspot:

{
  "reader": { "uuid": "957e5291-d378-4c4c-8be6-957845d4aaa7", "email": "reader@example.com", "timezone": "America/New_York" },
  "event_data": {
    "publication_id": "0956205001697194622",
    "url": "https://viewer.joomag.com/january/0956205001697194622",
    "datetime": "2024-04-12T07:53:10.000Z",
    "type": "youtube_popup",
    "name": "15 Best Countries to Visit in Asia",
    "target": "dQw4w9WgXcQ",
    "tooltip": "Watch our travel video",
    "page_number": 9,
    "page_name": "Travel Section",
    "tags": ["campaign-x"]
  }
}

---

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, hotspot.activated	The page being viewed, or the page a clicked hotspot sits on.
page_name	page.viewed, hotspot.activated	The page’s name, as set by the publisher in the editor’s page properties (max 100 characters). Omitted when the page has no name.
identification_source	reader.identified	How the reader was identified (e.g. query_params, subscribe_form, reader_login).
type	hotspot.activated	The hotspot kind — see Hotspot types.
name	hotspot.activated	Decorative, human‑readable label for the hotspot (falls back to e.g. (Unnamed custom pop-up) when untitled).
target	hotspot.activated	The hotspot’s value/destination; its meaning depends on type.
tooltip	hotspot.activated	The hotspot’s tooltip text, as set in the editor’s hotspot properties (max 118 characters). Omitted when not set.
tags	hotspot.activated	The tags placed on the hotspot element (array), when present.

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.