@antelopejs/dms-marketing 0.3.2 → 0.4.0

package/static/tracker.js

@@ -8,7 +8,7 @@
  * Optional attributes:
  *   data-host-url        override the collect origin (defaults to the script origin)
  *   data-heatmap-sample  0-1 click/scroll sampling rate; overrides the module setting
- *   data-do-not-track    "false" to ignore the browser DNT signal
+ *   data-do-not-track    "false" to ignore the browser DNT and GPC signals
  *
  * Cookieless by design: no identifier is generated or stored client-side —
  * the backend derives an anonymous visitor hash per request. Payload shape
@@ -36,12 +36,17 @@
   const CONFIG_GLOBAL = "__dmsMarketingTrackerConfig";
   /** Global the capture script (snapshot.js) reads its page context from. */
   const SNAPSHOT_CONTEXT_GLOBAL = "__dmsMarketingSnapshotContext";
+  /** Set by the first tracker that starts collecting on the page. */
+  const INSTALLED_GLOBAL = "__dmsMarketingInstalled";
 
   const DEFAULT_SAMPLE_RATE = 0.1;
   const FLUSH_INTERVAL_MS = 5000;
   const MAX_BATCH = 25;
-  /** Mirrors the backend MAX_URL_LENGTH: a longer field fails validation. */
+  /** Mirror the backend caps (MAX_URL_LENGTH, MAX_TITLE_LENGTH,
+   * MAX_EVENT_NAME_LENGTH): cut here, nothing is lost to validation. */
   const MAX_URL_LENGTH = 500;
+  const MAX_TITLE_LENGTH = 200;
+  const MAX_EVENT_NAME_LENGTH = 50;
   const MAX_SELECTOR_LENGTH = 120;
   const SELECTOR_DEPTH = 3;
   const COORDINATE_PRECISION = 4;
@@ -51,6 +56,11 @@
   const SNAPSHOT_DELAY_MS = 3000;
   /** SPA navigations may ask again, this many times per page load. */
   const MAX_SNAPSHOTS_PER_LOAD = 3;
+  /** After a SPA navigation, time for the new view to render before its
+   * unscrolled depth is measured. */
+  const SCROLL_MEASURE_DELAY_MS = 1000;
+  /** Where a keyboard-activated click is anchored inside its element. */
+  const ELEMENT_CENTER = 0.5;
 
   // --- Public API -----------------------------------------------------------
 
@@ -72,11 +82,6 @@
 
   // --- Configuration --------------------------------------------------------
 
-  const script = document.currentScript;
-  if (!script) {
-    return;
-  }
-
   /** Read once and removed: the injected settings are not a page-facing API. */
   function servedConfig() {
     const injected = window[CONFIG_GLOBAL];
@@ -84,6 +89,21 @@
     return injected && typeof injected === "object" ? injected : {};
   }
 
+  const config = servedConfig();
+
+  // Collection paused (Settings): the page API without the collection, so
+  // `variation()` answers the control. A page already running the tracker
+  // keeps it.
+  if (config.paused === true) {
+    window.dmsMarketing = window.dmsMarketing || NOOP_API;
+    return;
+  }
+
+  const script = document.currentScript;
+  if (!script) {
+    return;
+  }
+
   function firstFiniteNumber(values) {
     return values.find((value) => Number.isFinite(value));
   }
@@ -98,16 +118,27 @@
     return Math.min(Math.max(rate, 0), 1);
   }
 
-  const config = servedConfig();
   const websiteId = script.getAttribute("data-website-id");
   if (!websiteId) {
     publishApi();
     return;
   }
 
+  // A tag included twice (theme and tag manager) would count everything twice.
+  if (window[INSTALLED_GLOBAL]) {
+    console.warn("[dms-marketing] tracker included twice; ignoring the copy.");
+    return;
+  }
+  window[INSTALLED_GLOBAL] = true;
+
+  /** Global Privacy Control is the opt-out signal browsers ship now that DNT
+   * is deprecated; both are honoured alike. */
   const respectDnt = script.getAttribute("data-do-not-track") !== "false";
-  const dntEnabled = navigator.doNotTrack === "1" || window.doNotTrack === "1";
-  if (respectDnt && dntEnabled) {
+  const optedOut =
+    navigator.doNotTrack === "1" ||
+    window.doNotTrack === "1" ||
+    navigator.globalPrivacyControl === true;
+  if (respectDnt && optedOut) {
     publishApi();
     return;
   }
@@ -135,7 +166,7 @@
   const base = () => ({
     url: currentUrl(),
     referrer: document.referrer.slice(0, MAX_URL_LENGTH) || undefined,
-    title: document.title || undefined,
+    title: document.title.slice(0, MAX_TITLE_LENGTH) || undefined,
     screen: `${screen.width}x${screen.height}`,
     language: navigator.language || undefined,
     at: Date.now(),
@@ -179,7 +210,8 @@
    * navigation rewrites `location` before the depth of the page being left
    * is flushed. */
   let scrolledUrl = null;
-  let maxScrollDepth = 0;
+  /** -1 until the page has been measured once. */
+  let maxScrollDepth = -1;
 
   function trackPageview() {
     if (location.pathname === lastPath) {
@@ -188,17 +220,34 @@
     flushScrollDepth();
     lastPath = location.pathname;
     scrolledUrl = currentUrl();
-    maxScrollDepth = 0;
-    enqueue(Object.assign(base(), { kind: "pageview" }));
+    maxScrollDepth = -1;
+    // The rate it applies, for the server's "recorded on N % of page loads":
+    // counting scroll events against pageviews undercounts the views left
+    // before their depth is sent.
+    enqueue(
+      Object.assign(base(), { kind: "pageview", data: { sample: sampleRate } }),
+    );
+    scheduleScrollMeasure();
     scheduleSnapshot();
   }
 
-  const originalPushState = history.pushState;
-  history.pushState = function pushState(...args) {
-    originalPushState.apply(this, args);
-    trackPageview();
-  };
+  /** pushState and replaceState (a client-side redirect lands on a page
+   * too); a same-path call — a query or hash update — is no navigation. */
+  for (const method of ["pushState", "replaceState"]) {
+    const original = history[method];
+    history[method] = function navigate(...args) {
+      original.apply(this, args);
+      trackPageview();
+    };
+  }
   window.addEventListener("popstate", trackPageview);
+  // A page restored from the back/forward cache runs no script again.
+  window.addEventListener("pageshow", (event) => {
+    if (event.persisted) {
+      lastPath = null;
+      trackPageview();
+    }
+  });
 
   // --- Scroll depth (max reached per page, flushed on leave) ----------------
 
@@ -215,19 +264,30 @@
     );
   }
 
-  window.addEventListener(
-    "scroll",
-    () => {
-      const depth = currentScrollDepth();
-      if (depth > maxScrollDepth) {
-        maxScrollDepth = depth;
-      }
-    },
-    { passive: true },
-  );
+  function measureScrollDepth() {
+    const depth = currentScrollDepth();
+    if (depth > maxScrollDepth) {
+      maxScrollDepth = depth;
+    }
+  }
+
+  window.addEventListener("scroll", measureScrollDepth, { passive: true });
+
+  /**
+   * Every sampled view reports a depth, scrolled or not: what shows without
+   * scrolling is reached too (all of a page shorter than the window), and a
+   * view that never scrolls belongs in the denominator.
+   */
+  function scheduleScrollMeasure() {
+    if (document.readyState === "complete") {
+      setTimeout(measureScrollDepth, SCROLL_MEASURE_DELAY_MS);
+      return;
+    }
+    window.addEventListener("load", measureScrollDepth, { once: true });
+  }
 
   function flushScrollDepth() {
-    if (!heatmapSampled || maxScrollDepth <= 0) {
+    if (!heatmapSampled || maxScrollDepth < 0) {
       return;
     }
     enqueue(
@@ -237,7 +297,7 @@
         data: { depth: maxScrollDepth },
       }),
     );
-    maxScrollDepth = 0;
+    maxScrollDepth = -1;
   }
 
   // --- Click capture (sampled, viewport-normalized) -------------------------
@@ -257,19 +317,16 @@
     return parts.join(">").slice(0, MAX_SELECTOR_LENGTH);
   }
 
-  function normalized(value, total) {
-    if (total <= 0) {
-      return 0;
-    }
-    return Number(Math.min(value / total, 1).toFixed(COORDINATE_PRECISION));
-  }
-
   function rounded(value) {
     return Number(
       Math.min(Math.max(value, 0), 1).toFixed(COORDINATE_PRECISION),
     );
   }
 
+  function normalized(value, total) {
+    return total <= 0 ? 0 : rounded(value / total);
+  }
+
   /**
    * Where the click landed inside the element it hit, so the point survives
    * being read back at another window size. Document fractions do not: they
@@ -284,7 +341,7 @@
    * several elements, and the embedder resolving it would otherwise land on
    * whichever comes first in the document.
    */
-  function elementAnchor(target, event) {
+  function elementAnchor(target, point) {
     if (target === document.body || target === document.documentElement) {
       return null;
     }
@@ -310,16 +367,37 @@
     }
     return {
       selector: selector,
-      ox: rounded((event.clientX - box.left) / box.width),
-      oy: rounded((event.clientY - box.top) / box.height),
+      ox: rounded((point.clientX - box.left) / box.width),
+      oy: rounded((point.clientY - box.top) / box.height),
       nth: nth,
     };
   }
 
+  /**
+   * Where the click happened. A click from the keyboard (Enter, Space) has no
+   * pointer — detail 0, coordinates 0,0 — and is placed at the centre of the
+   * element it activated instead of the window's corner.
+   */
+  function clickPoint(target, event) {
+    if (event.detail !== 0 || event.clientX !== 0 || event.clientY !== 0) {
+      return event;
+    }
+    const box = target.getBoundingClientRect();
+    const clientX = box.left + box.width * ELEMENT_CENTER;
+    const clientY = box.top + box.height * ELEMENT_CENTER;
+    return {
+      clientX: clientX,
+      clientY: clientY,
+      pageX: clientX + scrollX,
+      pageY: clientY + scrollY,
+    };
+  }
+
   document.addEventListener(
     "click",
     (event) => {
-      if (!heatmapSampled) {
+      // Script-dispatched clicks (element.click()) are no visitor's.
+      if (!heatmapSampled || !event.isTrusted) {
         return;
       }
       const target = event.target;
@@ -327,18 +405,19 @@
         return;
       }
       const doc = document.documentElement;
+      const point = clickPoint(target, event);
       enqueue(
         Object.assign(base(), {
           kind: "click",
           data: Object.assign(
             {
-              x: normalized(event.clientX, innerWidth),
-              y: normalized(event.clientY, innerHeight),
-              dx: normalized(event.pageX, doc.scrollWidth),
-              dy: normalized(event.pageY, doc.scrollHeight),
+              x: normalized(point.clientX, innerWidth),
+              y: normalized(point.clientY, innerHeight),
+              dx: normalized(point.pageX, doc.scrollWidth),
+              dy: normalized(point.pageY, doc.scrollHeight),
               selector: shortSelector(target),
             },
-            elementAnchor(target, event),
+            elementAnchor(target, point),
           ),
         }),
       );
@@ -369,6 +448,9 @@
       return;
     }
     snapshotsRequested++;
+    // The upload is only accepted for the page the visit's last pageview
+    // named: that pageview must be on its way before the capture is.
+    flush();
     const path = location.pathname;
     window[SNAPSHOT_CONTEXT_GLOBAL] = {
       website: websiteId,
@@ -466,7 +548,16 @@
 
   publishApi({
     track(name, data) {
-      enqueue(Object.assign(base(), { kind: "custom", name, data }));
+      enqueue(
+        Object.assign(base(), {
+          kind: "custom",
+          name:
+            typeof name === "string"
+              ? name.slice(0, MAX_EVENT_NAME_LENGTH)
+              : name,
+          data,
+        }),
+      );
     },
     /** Assigned variation of a running experiment, or null. Reports the
      * exposure, so only call it where the variation is actually applied. */

package/dist/pages/campaigns/page.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"page.js","sourceRoot":"","sources":["../../../src/pages/campaigns/page.ts"],"names":[],"mappings":";;;;;;;;;AAAA,kEAAwE;AACxE,oEAAuE;AACvE,yDAA8E;AAC9E,iDAAwD;AASjD,IAAM,sBAAsB,GAA5B,MAAM,sBAAuB,SAAQ,IAAA,qBAAc,EACxD,WAAW,EACX;IACE,WAAW,EAAE,iCAAiC;IAC9C,WAAW,EAAE,uCAAuC;IACpD,IAAI,EAAE,gBAAgB;IACtB,MAAM,EAAE,+BAAmB;IAC3B,KAAK,EAAE,CAAC;CACT,EACD,IAAA,uBAAa,EAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CACnC;IACC,MAAM,CAAC,OAAO,GAAG,IAAA,wBAAe,EAAC,2BAA2B,CAAC,CAAC;;AAXnD,wDAAsB;iCAAtB,sBAAsB;IADlC,IAAA,mBAAY,GAAE;GACF,sBAAsB,CAYlC"}

package/frontend-vue/app/components/CampaignsView.vue

@@ -1,330 +0,0 @@
-<script setup lang="ts">
-import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue'
-import { useDmsRoute, useI18n } from '#dms/frontend-module'
-import { useChildId } from '../composables/useChildId'
-import { useLatestRequest } from '../composables/useLatestRequest'
-import {
-  useMarketingApi,
-  type MarketingCampaignEntry,
-  type MarketingCampaigns,
-  type MarketingChannel,
-} from '../composables/useMarketingApi'
-import {
-  MARKETING_PERIOD_PRESETS,
-  ndToPreset,
-  useMarketingPeriod,
-} from '../composables/useMarketingPeriod'
-import { useMarketingWebsites } from '../composables/useMarketingWebsites'
-
-import type { TableColumn } from '@nuxt/ui'
-
-/**
- * Acquisition surface: the five-channel split of sessions (donut) next to the
- * UTM campaign table — one row per (source, medium, campaign) triple observed
- * on new sessions — with UTM terms and contents as top lists below.
- *
- * Everything reads the daily rollups through one campaigns fetch; the search
- * box filters the table server-side because a day's map caps its entries and
- * the merged table can exceed what one response carries.
- */
-const PERIOD_SCOPE = 'dms-marketing-campaigns'
-const SEARCH_DEBOUNCE_MS = 300
-
-// The DMS page renderer hands every component its identity; keeping it is what
-// lets dms-ui primitives key their events and persisted state per child.
-const props = withDefaults(
-  defineProps<{ componentId?: string, pageId?: string }>(),
-  { componentId: 'marketing-campaigns', pageId: 'marketing' },
-)
-
-const childId = useChildId(() => props.componentId)
-
-const api = useMarketingApi()
-const { t, te } = useI18n()
-const route = useDmsRoute()
-
-const queryParam = (key: string): string => {
-  const value = route.query[key]
-  return typeof value === 'string' ? value : ''
-}
-
-// Read once: the selector seeds its preset at init and never reactively, so a
-// deep link's window has to be resolved before it renders.
-const initialPreset = ndToPreset(queryParam('period'))
-
-const {
-  websites,
-  items: websiteItems,
-  selectedId,
-  loading: loadingWebsites,
-  failed: websitesFailed,
-  load: loadWebsites,
-  create: createWebsite,
-} = useMarketingWebsites(queryParam('website'))
-
-const period = useMarketingPeriod(PERIOD_SCOPE)
-const search = ref('')
-
-let searchTimer: ReturnType<typeof setTimeout> | null = null
-
-const {
-  data: acquisition,
-  loading: loadingCampaigns,
-  failed: campaignsFailed,
-  settled: campaignsSettled,
-  run: loadCampaigns,
-} = useLatestRequest<MarketingCampaigns>(() =>
-  // Server-side there is no session to authenticate with: the fetch belongs to
-  // the client, like every other read here.
-  selectedId.value && !import.meta.env.SSR
-    ? api.getCampaigns(selectedId.value, period.value, search.value.trim())
-    : null,
-)
-
-// The watcher owns every fetch, including the first: seeding it from onMounted
-// as well would issue the initial request twice on a bare link, and not at all
-// on a link that already names the site the list would have picked — resolving
-// it writes back the same id, which is no change to watch.
-watch([selectedId, period], () => {
-  void loadCampaigns()
-}, { immediate: true })
-
-watch(search, () => {
-  if (searchTimer) {
-    clearTimeout(searchTimer)
-  }
-  searchTimer = setTimeout(() => void loadCampaigns(), SEARCH_DEBOUNCE_MS)
-})
-
-onBeforeUnmount(() => {
-  if (searchTimer) {
-    clearTimeout(searchTimer)
-  }
-})
-
-const loading = computed(
-  () =>
-    loadingWebsites.value
-    || loadingCampaigns.value
-    || (!!selectedId.value && !campaignsSettled.value),
-)
-
-// Two failures, two flags: retrying the campaigns fetch must not clear the
-// one that says the site list itself never loaded.
-const failed = computed(() => websitesFailed.value || campaignsFailed.value)
-
-/** Retry entry point: whichever of the two fetches has nothing to show. */
-function reload() {
-  return websites.value.length === 0 ? loadWebsites() : loadCampaigns()
-}
-
-onMounted(loadWebsites)
-
-// --- Channels ---------------------------------------------------------------
-
-/** Display order mirrors the backend's MARKETING_CHANNELS. */
-const CHANNEL_ORDER: MarketingChannel[] = ['direct', 'organic', 'social', 'referral', 'paid']
-
-/** Known channels localize; a key minted by a future classifier still shows. */
-function channelLabel(channel: string): string {
-  const key = `page.marketing.campaigns.channels.${channel}`
-  return te(key) ? t(key) : channel
-}
-
-const channelRecords = computed(() => {
-  const channels = acquisition.value?.channels ?? {}
-  return CHANNEL_ORDER
-    .map(channel => ({ label: channelLabel(channel), value: channels[channel] ?? 0 }))
-    .filter(record => record.value > 0)
-})
-
-// --- Campaign table ---------------------------------------------------------
-
-const campaignRows = computed(() => acquisition.value?.campaigns ?? [])
-const truncated = computed(() => acquisition.value?.truncated ?? false)
-
-const columns = computed<TableColumn<MarketingCampaignEntry>[]>(() => [
-  { accessorKey: 'source', header: t('page.marketing.campaigns.table.source') },
-  { accessorKey: 'medium', header: t('page.marketing.campaigns.table.medium') },
-  { accessorKey: 'campaign', header: t('page.marketing.campaigns.table.campaign') },
-  {
-    accessorKey: 'sessions',
-    header: t('page.marketing.campaigns.table.sessions'),
-    meta: { class: { th: 'text-right', td: 'text-right' } },
-  },
-])
-
-// --- Referrer / term / content top lists ------------------------------------
-
-const TOP_LIST_LIMIT = 8
-
-function toTopItems(record: Record<string, number> | undefined) {
-  return Object.entries(record ?? {})
-    .sort((a, b) => b[1] - a[1])
-    .slice(0, TOP_LIST_LIMIT)
-    .map(([label, value]) => ({ id: label, title: label, value }))
-}
-
-const topLists = computed(() => [
-  // Referrer domains across all channels — the overview's acquisition card
-  // links here for this detail.
-  {
-    id: 'referrers',
-    title: t('page.marketing.campaigns.top.referrers'),
-    items: toTopItems(acquisition.value?.referrers),
-  },
-  {
-    id: 'terms',
-    title: t('page.marketing.campaigns.top.terms'),
-    items: toTopItems(acquisition.value?.terms),
-  },
-  {
-    id: 'contents',
-    title: t('page.marketing.campaigns.top.contents'),
-    items: toTopItems(acquisition.value?.contents),
-  },
-])
-</script>
-
-<template>
-  <div class="space-y-6 p-6">
-    <div class="flex flex-wrap items-center justify-between gap-4">
-      <div>
-        <h1 class="text-xl font-semibold">{{ t('page.marketing.campaigns.title') }}</h1>
-        <p class="text-sm text-muted">{{ t('page.marketing.campaigns.subtitle') }}</p>
-      </div>
-      <div class="flex items-center gap-3">
-        <USelect
-          v-if="websites.length > 1"
-          v-model="selectedId"
-          :items="websiteItems"
-          class="w-56"
-        />
-        <DmsPeriodSelector
-          :id="PERIOD_SCOPE"
-          :component-id="childId('period')"
-          :page-id="props.pageId"
-          :default-preset="initialPreset"
-          :presets="MARKETING_PERIOD_PRESETS"
-          :comparisons="['none']"
-          :show-range-label="false"
-        />
-        <UButton
-          icon="i-ph-arrow-clockwise"
-          color="neutral"
-          variant="subtle"
-          size="sm"
-          :loading="loading"
-          @click="loadCampaigns"
-        />
-      </div>
-    </div>
-
-    <div v-if="failed" class="flex flex-col items-start gap-3">
-      <UAlert
-        color="error"
-        variant="subtle"
-        icon="i-ph-warning-circle"
-        :title="t('page.marketing.campaigns.error.title')"
-        :description="t('page.marketing.campaigns.error.description')"
-      />
-      <UButton
-        icon="i-ph-arrow-clockwise"
-        :label="t('page.marketing.campaigns.retry')"
-        color="neutral"
-        variant="subtle"
-        size="sm"
-        @click="reload"
-      />
-    </div>
-
-    <DmsMarketingNoWebsiteState
-      v-else-if="!loading && websites.length === 0"
-      icon="i-ph-megaphone"
-      :title="t('page.marketing.campaigns.empty.title')"
-      :description="t('page.marketing.campaigns.empty.description')"
-      @create="createWebsite"
-    />
-
-    <!-- Only before the first answer: a refetch keeps the tables on screen
-    and spins the refresh button instead. -->
-    <USkeleton v-else-if="loading && !acquisition" class="h-96 w-full" />
-
-    <template v-else>
-      <div class="grid gap-4 lg:grid-cols-3">
-        <UCard>
-          <template #header>
-            <div>
-              <p class="font-medium">{{ t('page.marketing.campaigns.channels.title') }}</p>
-              <p class="text-sm text-muted">{{ t('page.marketing.campaigns.channels.subtitle') }}</p>
-            </div>
-          </template>
-          <DmsChart
-            v-if="channelRecords.length > 0"
-            :component-id="childId('channels')"
-            :page-id="props.pageId"
-            type="donut"
-            :static-dataset="channelRecords"
-            height="300px"
-            :show-total="true"
-          />
-          <p v-else class="py-12 text-center text-sm text-muted">
-            {{ t('page.marketing.campaigns.channels.empty') }}
-          </p>
-        </UCard>
-
-        <UCard class="lg:col-span-2">
-          <template #header>
-            <div class="flex flex-wrap items-center justify-between gap-3">
-              <div>
-                <p class="font-medium">{{ t('page.marketing.campaigns.table.title') }}</p>
-                <p class="text-sm text-muted">{{ t('page.marketing.campaigns.table.subtitle') }}</p>
-              </div>
-              <UInput
-                v-model="search"
-                icon="i-ph-magnifying-glass"
-                :placeholder="t('page.marketing.campaigns.table.search_placeholder')"
-                class="w-56"
-              />
-            </div>
-          </template>
-          <UTable :data="campaignRows" :columns="columns">
-            <template #source-cell="{ row }">
-              <span v-if="row.original.source">{{ row.original.source }}</span>
-              <span v-else class="text-muted">—</span>
-            </template>
-            <template #medium-cell="{ row }">
-              <span v-if="row.original.medium">{{ row.original.medium }}</span>
-              <span v-else class="text-muted">—</span>
-            </template>
-            <template #campaign-cell="{ row }">
-              <span v-if="row.original.campaign">{{ row.original.campaign }}</span>
-              <span v-else class="text-muted">—</span>
-            </template>
-            <template #empty>
-              <p class="py-8 text-center text-sm text-muted">
-                {{ t('page.marketing.campaigns.table.empty') }}
-              </p>
-            </template>
-          </UTable>
-          <p v-if="truncated" class="mt-2 text-sm text-muted">
-            {{ t('page.marketing.campaigns.table.truncated') }}
-          </p>
-        </UCard>
-      </div>
-
-      <div class="grid gap-4 md:grid-cols-2 lg:grid-cols-3">
-        <DmsTopListCard
-          v-for="list in topLists"
-          :key="list.id"
-          :component-id="childId(`top-${list.id}`)"
-          :page-id="props.pageId"
-          :title="list.title"
-          :static-items="list.items"
-          :show-delta="false"
-          :empty-label="t('page.marketing.campaigns.top.empty')"
-        />
-      </div>
-    </template>
-  </div>
-</template>