@hagicode/hagilight-core 0.6.1-dev.74.1.7df157f → 0.6.1

package/Footer.astro

@@ -1,5 +1,6 @@
 ---
 import Copyright from './Copyright.astro';
+import { siteLinkGaAttributes } from './dist/analytics-events.js';
 import { resolveSiteLinks, type SiteLinksOptions } from './dist/links.js';
 import { resolveRssFooterLinks } from './dist/rss-footer-context.js';
 
@@ -51,6 +52,7 @@ const resolvedLinks = resolveSiteLinks(locale, {
                 target={link.target}
                 rel={link.rel}
                 aria-label={link.ariaLabel}
+                {...siteLinkGaAttributes(link, 'footer')}
               >{link.label}</a>
             </li>
           ))}
@@ -68,6 +70,7 @@ const resolvedLinks = resolveSiteLinks(locale, {
                 target={link.target}
                 rel={link.rel}
                 aria-label={link.ariaLabel}
+                {...siteLinkGaAttributes(link, 'footer')}
               >{link.label}</a>
             </li>
           ))}

package/GoogleAnalytics.astro

@@ -19,3 +19,9 @@ const scriptUrl = `https://www.googletagmanager.com/gtag/js?id=${encodeURICompon
     </script>
   </>
 )}
+
+<script>
+  import { installGaEventTracking } from './dist/analytics-events.js';
+
+  installGaEventTracking();
+</script>

package/README.md

@@ -27,7 +27,7 @@ attribution by itself. Plain-Astro sites that want the literal
 `@hagicode/hagilight/Footer`; that component reads the exact build-time version
 from `@hagicode/hagilight`'s own manifest, not from Astro.
 
-Other entry points include `Copyright`, `PromotoBanner`, `GoogleAnalytics`, and `Analytics51LA` Astro components; `links`, `favicon`, `seo`, `seo-schema`, `rss`, `rss-ownership`, and `promotions` utilities; and `logo.png` and `favicon.ico` assets. For example:
+Other entry points include `Copyright`, `PromotoBanner`, `GoogleAnalytics`, and `Analytics51LA` Astro components; `links`, `favicon`, `seo`, `seo-schema`, `rss`, `rss-ownership`, `promotions`, and `analytics-events` utilities; and `logo.png` and `favicon.ico` assets. For example:
 
 ```ts
 import { resolveSiteLinks } from '@hagicode/hagilight-core/links';
@@ -35,4 +35,55 @@ import { resolveSiteLinks } from '@hagicode/hagilight-core/links';
 const links = resolveSiteLinks('en-US');
 ```
 
+## Google Analytics click events
+
+`GoogleAnalytics` also reports clicks on the key links and download buttons that the shared components render. There is nothing to configure: events follow the same rules as page views, so they are sent only on production pages where Google Analytics is enabled, never on the Starlight 404 page, and silently skipped when `gtag` is missing (development builds, blocked scripts).
+
+A click on a tagged link calls `gtag('event', <action>, …)` once:
+
+| Field | Value |
+| --- | --- |
+| Event name (action) | `download_click` for the `download` category, `link_click` for every other category |
+| `event_category` | `download`, `navigation`, `community`, or `promotion` |
+| `event_label` | The link's stable id (for example `downloadClient`), never its localized text |
+| `link_location` | Where the link sits: `header`, `footer`, `article_promotion`, `promoto_banner`, or your own value |
+| `link_url` | The destination at click time |
+| `transport_type` | `beacon`, so same-tab navigations still deliver |
+
+Reporting never delays, cancels, or changes navigation, and carries no link text, form values, or visitor identifiers.
+
+### Tracked links
+
+The shared components tag exactly these links. The authoritative list is `TRACKED_SITE_LINKS` in `src/analytics-events.ts`; renaming a link id changes its GA label.
+
+| `event_label` | `event_category` | Reported from |
+| --- | --- | --- |
+| `home`, `blog`, `support` | `navigation` | header (`home` also in the HagiCode showcase) |
+| `dockerCompose`, `blogPosts` | `navigation` | footer quick links |
+| `productDocs` | `navigation` | footer quick links, HagiCode showcase |
+| `downloadClient`, `microsoftStore` | `download` | footer quick links, HagiCode showcase (the Microsoft Store badge and its fallback link report `microsoftStore`) |
+| `github`, `discord`, `issueFeedback` | `community` | footer community links |
+| the promotion's id | `promotion` | floating promotion banner call to action, including rotated slides |
+
+Related-site links, RSS, sitemap, about, contact, filings, the language chooser, and links you add through `extraLinks` do not report events. A consumer that overrides a tracked link's destination keeps the original label and reports the new destination as `link_url`.
+
+### Tag your own links
+
+```astro
+---
+import { gaEventAttributes } from '@hagicode/hagilight-core/analytics-events';
+---
+
+<a
+  href="/downloads/"
+  {...gaEventAttributes({ category: 'download', label: 'pricingDownload', location: 'pricing' })}
+>Download</a>
+```
+
+`gaEventAttributes()` returns the `data-ga-category`, `data-ga-label`, `data-ga-location`, and optional `data-ga-url` attributes (pass `url` when the tagged element has no `href` of its own). It throws a `TypeError` for an unknown category or an empty label or location. A hand-written `data-ga-*` tag with an invalid category is ignored at click time. The page must render `GoogleAnalytics` for the click to be reported. `siteLinkGaAttributes(link, location)` tags a resolved site link and returns `{}` for ids outside the tracked list.
+
+### Reports
+
+`event_category`, `event_label`, `link_location`, and `link_url` are custom event parameters. The property owner must register them as GA4 custom dimensions before they appear in standard reports; until then they are visible in DebugView and exports only. Ad blockers and browsers that block Google Analytics drop these events like any other, so treat the counts as directional.
+
 See the [repository documentation](https://github.com/HagiCode-org/hagilight#readme) for the full list of entry points and usage.

package/dist/analytics-events.d.ts

@@ -0,0 +1,49 @@
+import type { SiteLink, SiteLinkKey } from './links.js';
+export declare const GA_CATEGORIES: readonly ["download", "navigation", "community", "promotion"];
+export type GaCategory = (typeof GA_CATEGORIES)[number];
+export type GaAction = 'download_click' | 'link_click';
+export declare const GA_CATEGORY_ACTIONS: Readonly<Record<GaCategory, GaAction>>;
+export declare const GA_LOCATIONS: readonly ["header", "footer", "article_promotion", "promoto_banner"];
+export type GaLocation = (typeof GA_LOCATIONS)[number];
+/** Shared links that report click events, keyed by `SiteLink.id`. Renaming a key changes its GA label. */
+export declare const TRACKED_SITE_LINKS: Readonly<Partial<Record<SiteLinkKey, GaCategory>>>;
+export interface GaEventTag {
+    category: GaCategory;
+    /** Stable identifier, never localized text. */
+    label: string;
+    /** Where the link sits, for example one of `GA_LOCATIONS`. */
+    location: string;
+    /** Destination to report when the tagged element has no `href` of its own. */
+    url?: string;
+}
+export interface GaEventAttributes {
+    'data-ga-category': GaCategory;
+    'data-ga-label': string;
+    'data-ga-location': string;
+    'data-ga-url'?: string;
+}
+export interface GaEventParams {
+    event_category: GaCategory;
+    event_label: string;
+    link_location: string;
+    link_url?: string;
+    transport_type: 'beacon';
+}
+export type GaSend = (action: GaAction, params: GaEventParams) => void;
+/** Builds the `data-ga-*` attributes that make a link report a click event. */
+export declare function gaEventAttributes(tag: GaEventTag): GaEventAttributes;
+/** Returns tag attributes for catalog links in `TRACKED_SITE_LINKS` and `{}` for every other link. */
+export declare function siteLinkGaAttributes(link: Pick<SiteLink, 'id'>, location: string): Partial<GaEventAttributes>;
+/**
+ * Reports the first tagged element in the click's composed path. Never throws and never
+ * touches the event, so navigation is unaffected.
+ */
+export declare function handleGaClick(event: {
+    composedPath(): readonly unknown[];
+}, send: GaSend): void;
+/**
+ * Installs one capture-phase click listener per document. Events are sent only while
+ * `gtag` exists, so development builds, disabled sites, and the 404 page stay silent.
+ * Returns `false` when the document was already instrumented.
+ */
+export declare function installGaEventTracking(target?: Pick<EventTarget, 'addEventListener'>, getGtag?: () => unknown): boolean;

package/dist/analytics-events.js

@@ -0,0 +1,112 @@
+export const GA_CATEGORIES = ['download', 'navigation', 'community', 'promotion'];
+// GA4 has no native category/action/label: the action is the event name.
+export const GA_CATEGORY_ACTIONS = Object.freeze({
+    download: 'download_click',
+    navigation: 'link_click',
+    community: 'link_click',
+    promotion: 'link_click',
+});
+export const GA_LOCATIONS = ['header', 'footer', 'article_promotion', 'promoto_banner'];
+/** Shared links that report click events, keyed by `SiteLink.id`. Renaming a key changes its GA label. */
+export const TRACKED_SITE_LINKS = Object.freeze({
+    home: 'navigation',
+    blog: 'navigation',
+    support: 'navigation',
+    downloadClient: 'download',
+    microsoftStore: 'download',
+    dockerCompose: 'navigation',
+    productDocs: 'navigation',
+    blogPosts: 'navigation',
+    github: 'community',
+    discord: 'community',
+    issueFeedback: 'community',
+});
+function isCategory(value) {
+    return typeof value === 'string' && GA_CATEGORIES.includes(value);
+}
+function requireText(name, value) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new TypeError(`Analytics event ${name} must be a non-empty string.`);
+    }
+    return value;
+}
+/** Builds the `data-ga-*` attributes that make a link report a click event. */
+export function gaEventAttributes(tag) {
+    if (!isCategory(tag.category)) {
+        throw new TypeError(`Analytics event category must be one of: ${GA_CATEGORIES.join(', ')}.`);
+    }
+    return {
+        'data-ga-category': tag.category,
+        'data-ga-label': requireText('label', tag.label),
+        'data-ga-location': requireText('location', tag.location),
+        ...(tag.url === undefined ? {} : { 'data-ga-url': requireText('url', tag.url) }),
+    };
+}
+/** Returns tag attributes for catalog links in `TRACKED_SITE_LINKS` and `{}` for every other link. */
+export function siteLinkGaAttributes(link, location) {
+    if (!Object.hasOwn(TRACKED_SITE_LINKS, link.id))
+        return {};
+    return gaEventAttributes({
+        category: TRACKED_SITE_LINKS[link.id],
+        label: link.id,
+        location,
+    });
+}
+function isTaggedElement(value) {
+    return typeof value === 'object' && value !== null
+        && typeof value.getAttribute === 'function'
+        && (value.getAttribute('data-ga-category') !== null
+            || value.getAttribute('data-ga-label') !== null);
+}
+function nonEmpty(value) {
+    return typeof value === 'string' && value.trim() ? value : undefined;
+}
+/**
+ * Reports the first tagged element in the click's composed path. Never throws and never
+ * touches the event, so navigation is unaffected.
+ */
+export function handleGaClick(event, send) {
+    try {
+        const element = event.composedPath().find(isTaggedElement);
+        if (!element)
+            return;
+        const category = element.getAttribute('data-ga-category');
+        const label = nonEmpty(element.getAttribute('data-ga-label'));
+        const location = nonEmpty(element.getAttribute('data-ga-location'));
+        if (!isCategory(category) || !label || !location)
+            return;
+        const linkUrl = nonEmpty(element.getAttribute('data-ga-url'))
+            ?? nonEmpty(element.href)
+            ?? nonEmpty(element.getAttribute('href'));
+        send(GA_CATEGORY_ACTIONS[category], {
+            event_category: category,
+            event_label: label,
+            link_location: location,
+            ...(linkUrl === undefined ? {} : { link_url: linkUrl }),
+            transport_type: 'beacon',
+        });
+    }
+    catch {
+        // Analytics must never interfere with the click.
+    }
+}
+const INSTALLED = Symbol.for('hagilight.ga-event-tracking');
+/**
+ * Installs one capture-phase click listener per document. Events are sent only while
+ * `gtag` exists, so development builds, disabled sites, and the 404 page stay silent.
+ * Returns `false` when the document was already instrumented.
+ */
+export function installGaEventTracking(target = document, getGtag = () => globalThis.gtag) {
+    const marked = target;
+    if (marked[INSTALLED])
+        return false;
+    marked[INSTALLED] = true;
+    target.addEventListener('click', (event) => {
+        handleGaClick(event, (action, params) => {
+            const gtag = getGtag();
+            if (typeof gtag === 'function')
+                gtag('event', action, params);
+        });
+    }, true);
+    return true;
+}

package/dist/promoto-banner.js

@@ -1,3 +1,4 @@
+import { gaEventAttributes } from './analytics-events.js';
 import { loadActivePromotions } from './promotions.js';
 const ELEMENT_NAME = 'hagilight-promoto-banner';
 const DISMISSED_SIGNATURE_KEY = 'hagilight:promoto-banner:dismissed-signature';
@@ -228,6 +229,12 @@ export function definePromotoBannerElement() {
                 link.target = '_blank';
                 link.rel = 'noopener noreferrer';
                 link.textContent = card.ctaLabel;
+                for (const [name, value] of Object.entries(gaEventAttributes({
+                    category: 'promotion',
+                    label: card.id,
+                    location: 'promoto_banner',
+                })))
+                    link.setAttribute(name, value);
                 slide.append(copy);
                 if (card.image) {
                     const media = document.createElement('span');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight-core",
-  "version": "0.6.1-dev.74.1.7df157f",
+  "version": "0.6.1",
   "type": "module",
   "description": "Shared TypeScript utilities, components, and assets for HagiCode Astro and Starlight sites",
   "repository": {
@@ -46,6 +46,10 @@
       "types": "./dist/promotions.d.ts",
       "default": "./dist/promotions.js"
     },
+    "./analytics-events": {
+      "types": "./dist/analytics-events.d.ts",
+      "default": "./dist/analytics-events.js"
+    },
     "./Copyright": "./Copyright.astro",
     "./PromotoBanner": "./PromotoBanner.astro",
     "./GoogleAnalytics": "./GoogleAnalytics.astro",