@shoppexio/storefront 1.0.101 → 1.0.103

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.0.103
+
+- Web analytics (PR #3989): after a yes to analytics on the cookie banner, the SDK keeps an analytics session (30 idle minutes) and the session ids of the last 30 days for checkout, so an order keeps the visit it came from. A yes given without a reload starts the session on the page already counted (`session_start`, no second page view). Time on screen goes to the session the page was viewed in, also after that session went idle.
+
+## 1.0.102
+
+- The checkout URL carries the buyer's cookie banner answer in its hash (`#shoppex_consent=…`, PR #3938), so the full hosted checkout page sends the shop's Purchase tags under the same consent. The hash never reaches a server; without an answer on a shop with the banner on, the checkout sends no tags.
+
 ## 1.0.101
 
 - Supplier sourcing is retired (PR #3825): `Product.supplier_backed` and `ProductVariant.supplier_backed` are gone, and `orderable` no longer turns an empty local stock into unlimited stock. Stock helpers read local units only; `orderable` stays the buy/sold-out gate.

package/README.md

@@ -107,8 +107,8 @@ if (firstOrder) {
 }
 ```
 
-The publishable key and current browser origin must be configured under
-**Settings -> Developer -> Headless**. `rememberMe` is opt-in and keeps
+The publishable key comes from **Settings -> Developer -> Headless**; the
+current browser origin must be an allowed site in **Store -> Embed Hub**. `rememberMe` is opt-in and keeps
 the buyer signed in for up to 30 days.
 
 The order detail includes delivery status, service instructions, codes, serials,

package/dist/index.cjs

@@ -399,27 +399,9 @@ function buildEndpoint(template, params) {
 }
 
 // ../sdk/src/core/telemetry.ts
-var CONNECTION_ID_STORAGE_PREFIX = "presence_connection_";
 var CLIENT_ERROR_DEDUPE_WINDOW_MS = 15e3;
 var CLIENT_ERROR_TEXT_MAX_LENGTH = 500;
 var CLIENT_ERROR_URL_MAX_LENGTH = 2e3;
-function createPresenceConnectionId() {
-  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
-    return crypto.randomUUID();
-  }
-  return `spx_${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`;
-}
-function getStorefrontConnectionId(storeSlug) {
-  if (typeof window === "undefined") return null;
-  const storageKey2 = `${CONNECTION_ID_STORAGE_PREFIX}${storeSlug}`;
-  const existing = getItem(storageKey2);
-  if (existing && existing.trim()) {
-    return existing;
-  }
-  const nextId = createPresenceConnectionId();
-  setItem(storageKey2, nextId);
-  return nextId;
-}
 function getRecentClientErrorKey(payload) {
   return [
     payload.method,
@@ -449,7 +431,6 @@ async function reportStorefrontClientError(payload) {
   const body = JSON.stringify({
     event_type: "client_error",
     referer: document.referrer || void 0,
-    connection_id: getStorefrontConnectionId(config2.storeSlug) ?? void 0,
     client_error: {
       source: payload.source ?? "sdk",
       phase: payload.phase ?? "request",
@@ -1634,6 +1615,138 @@ async function quoteCart(coupon, currency) {
   return response;
 }
 
+// ../contracts/src/storefront-consent-choice.ts
+var COOKIE_CONSENT_VERSION = 1;
+var COOKIE_CONSENT_COOKIE = "shoppex_consent";
+var COOKIE_CONSENT_CHECKOUT_HASH_KEY = "shoppex_consent";
+var COOKIE_CONSENT_VALUE = new RegExp(`^v${COOKIE_CONSENT_VERSION}\\.f([01])\\.a([01])\\.m([01])$`);
+function parseCookieConsentValue(value) {
+  const match = value ? COOKIE_CONSENT_VALUE.exec(value) : null;
+  return match ? { functional: match[1] === "1", analytics: match[2] === "1", marketing: match[3] === "1" } : null;
+}
+
+// ../sdk/src/core/analytics-session.ts
+var ANALYTICS_SESSION_IDLE_MS = 30 * 60 * 1e3;
+var ANALYTICS_VISITS_WINDOW_MS = 30 * 24 * 60 * 60 * 1e3;
+var ANALYTICS_VISITS_MAX = 20;
+var MAX_ENGAGED_MS_PER_PAGE = 30 * 60 * 1e3;
+var analyticsSessionKey = (storeSlug) => `analytics_session_${storeSlug}`;
+var analyticsVisitsKey = (storeSlug) => `analytics_visits_${storeSlug}`;
+function readAnalyticsConsent() {
+  if (typeof document === "undefined" || typeof navigator === "undefined") return "unknown";
+  const privacy = navigator;
+  if (privacy.globalPrivacyControl === true || privacy.doNotTrack === "1") return "declined";
+  const prefix = `${COOKIE_CONSENT_COOKIE}=`;
+  let raw;
+  try {
+    raw = document.cookie.split(/;\s*/).find((part) => part.startsWith(prefix))?.slice(prefix.length);
+  } catch {
+    return "unknown";
+  }
+  const choice = parseCookieConsentValue(raw ?? null);
+  if (!choice) return "unknown";
+  return choice.analytics ? "granted" : "declined";
+}
+function readVisits(storeSlug, now) {
+  const stored = getItem(analyticsVisitsKey(storeSlug));
+  if (!Array.isArray(stored)) return [];
+  return stored.filter((visit2) => typeof visit2?.id === "string" && typeof visit2.at === "number" && now - visit2.at < ANALYTICS_VISITS_WINDOW_MS);
+}
+function forgetAnalyticsData(storeSlug) {
+  removeItem(analyticsSessionKey(storeSlug), "sessionStorage");
+  removeItem(analyticsVisitsKey(storeSlug));
+}
+function analyticsSessionId(storeSlug, options, now = Date.now()) {
+  removeItem(`presence_connection_${storeSlug}`);
+  if (readAnalyticsConsent() !== "granted") {
+    forgetAnalyticsData(storeSlug);
+    return null;
+  }
+  const stored = getItem(analyticsSessionKey(storeSlug), "sessionStorage");
+  const live = stored && typeof stored.id === "string" && typeof stored.at === "number" && now - stored.at < ANALYTICS_SESSION_IDLE_MS ? stored.id : null;
+  if (!options.touch) return live;
+  if (live) {
+    setItem(analyticsSessionKey(storeSlug), { id: live, at: now }, "sessionStorage");
+    return live;
+  }
+  if (typeof crypto === "undefined" || typeof crypto.randomUUID !== "function") return null;
+  const id = crypto.randomUUID();
+  setItem(analyticsSessionKey(storeSlug), { id, at: now }, "sessionStorage");
+  setItem(
+    analyticsVisitsKey(storeSlug),
+    [{ id, at: now }, ...readVisits(storeSlug, now)].slice(0, ANALYTICS_VISITS_MAX)
+  );
+  return id;
+}
+function checkoutAttribution(storeSlug, now = Date.now()) {
+  const consent = readAnalyticsConsent();
+  if (consent === "declined") {
+    forgetAnalyticsData(storeSlug);
+    return { declined: true };
+  }
+  if (consent === "unknown") return void 0;
+  const sessionIds = readVisits(storeSlug, now).map((visit2) => visit2.id);
+  return sessionIds.length > 0 ? { session_ids: sessionIds } : void 0;
+}
+var engagedMs = 0;
+var visibleSince = null;
+var clockInstalled = false;
+var pageViewed = false;
+var pageSession = null;
+function markPageViewed(sessionId) {
+  pageViewed = true;
+  pageSession = sessionId;
+}
+function currentPageSession() {
+  return pageSession;
+}
+function isPageViewed() {
+  return pageViewed;
+}
+function settleClock(now) {
+  if (visibleSince !== null) {
+    engagedMs += now - visibleSince;
+    visibleSince = document.visibilityState === "visible" ? now : null;
+  }
+}
+var consentListenerInstalled = false;
+function onAnalyticsConsent(onYes) {
+  if (consentListenerInstalled || typeof window === "undefined") return;
+  consentListenerInstalled = true;
+  window.addEventListener("shoppex:consent", () => {
+    if (readAnalyticsConsent() === "granted") onYes();
+  });
+}
+function installEngagedClock(onHidden) {
+  if (clockInstalled || typeof document === "undefined") return;
+  clockInstalled = true;
+  visibleSince = document.visibilityState === "visible" ? Date.now() : null;
+  document.addEventListener("visibilitychange", () => {
+    const now = Date.now();
+    if (document.visibilityState === "visible") {
+      visibleSince ?? (visibleSince = now);
+      return;
+    }
+    settleClock(now);
+    visibleSince = null;
+    onHidden();
+  });
+  window.addEventListener("pagehide", () => {
+    settleClock(Date.now());
+    visibleSince = null;
+    onHidden();
+  });
+  window.addEventListener("pageshow", (event) => {
+    if (event.persisted && document.visibilityState === "visible") visibleSince = Date.now();
+  });
+}
+function takeEngagedMs(now = Date.now()) {
+  settleClock(now);
+  const taken = Math.min(Math.max(0, Math.round(engagedMs)), MAX_ENGAGED_MS_PER_PAGE);
+  engagedMs = 0;
+  return taken;
+}
+
 // ../sdk/src/core/attribution.ts
 var STORAGE_PREFIX2 = "shoppex:utm:";
 var TTL_MS = 30 * 24 * 60 * 60 * 1e3;
@@ -1692,6 +1805,13 @@ function resolveUtmParameters(storeSlug) {
     return void 0;
   }
   const fromUrl = readFromUrl(window.location.search);
+  if (readAnalyticsConsent() !== "granted") {
+    try {
+      window.localStorage.removeItem(storefrontStorageKey(storageKey(storeSlug)));
+    } catch {
+    }
+    return Object.keys(fromUrl).length > 0 ? fromUrl : void 0;
+  }
   if (Object.keys(fromUrl).length > 0) {
     writeStored(storeSlug, fromUrl);
     return fromUrl;
@@ -1858,13 +1978,21 @@ async function trackPageView(cartValue, itemCount) {
   const sendView = async () => {
     const order2 = reservedOrder ? await reservedOrder : void 0;
     const settle2 = order2 ? claimCartReport(config2.storeSlug, order2.seq, cartValue, itemCount) : void 0;
+    const sessionId = analyticsSessionId(config2.storeSlug, { touch: true });
+    const previousSession = currentPageSession();
+    if (previousSession && previousSession !== sessionId) reportPageLeave();
+    markPageViewed(sessionId);
+    if (sessionId) installEngagedClock(reportPageLeave);
+    onAnalyticsConsent(startSessionOnConsent);
     const delivered = await postPing({
       referer: document.referrer || void 0,
       cart_value: cartValue,
       item_count: itemCount,
       cart_seq: order2?.seq,
       cart_seq_scope: order2?.scope,
-      connection_id: getStorefrontConnectionId(config2.storeSlug) ?? void 0,
+      session_id: sessionId ?? void 0,
+      // Time on screen of the page before this one (client-side navigation).
+      engaged_ms: sessionId ? takeEngagedMs() || void 0 : void 0,
       path: resolveStorefrontPagePath(),
       utm: resolveUtmParameters(config2.storeSlug)
     });
@@ -1892,11 +2020,44 @@ async function sendCartActivity(order2, cartValue, itemCount) {
     item_count: itemCount,
     cart_seq: order2.seq,
     cart_seq_scope: order2.scope,
-    connection_id: getStorefrontConnectionId(config2.storeSlug) ?? void 0,
+    // A cart marks the analytics session as one that did not bounce.
+    session_id: analyticsSessionId(config2.storeSlug, { touch: false }) ?? void 0,
     path: resolveStorefrontPagePath()
   });
   settle2(delivered);
 }
+function startSessionOnConsent() {
+  const config2 = getConfig();
+  if (!isPageViewed() || analyticsSessionId(config2.storeSlug, { touch: false })) return;
+  const sessionId = analyticsSessionId(config2.storeSlug, { touch: true });
+  if (!sessionId) return;
+  markPageViewed(sessionId);
+  installEngagedClock(reportPageLeave);
+  void postPing({
+    event_type: "session_start",
+    referer: document.referrer || void 0,
+    session_id: sessionId,
+    path: resolveStorefrontPagePath(),
+    utm: resolveUtmParameters(config2.storeSlug)
+  });
+}
+function reportPageLeave() {
+  const config2 = getConfig();
+  const sessionId = currentPageSession();
+  const engagedMs2 = takeEngagedMs();
+  if (!sessionId || engagedMs2 === 0 || readAnalyticsConsent() !== "granted") return;
+  try {
+    const endpoint = buildEndpoint("/v1/storefront/shops/:storeSlug/ping", { storeSlug: config2.storeSlug });
+    void fetch(`${config2.apiBaseUrl}${endpoint}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ event_type: "page_leave", session_id: sessionId, engaged_ms: engagedMs2 }),
+      keepalive: true
+    }).catch(() => {
+    });
+  } catch {
+  }
+}
 
 // ../sdk/src/storefront-storage-sdk.ts
 function init(storeSlugOrOptions, options) {
@@ -2953,10 +3114,16 @@ function buildCheckoutUrlFromInvoiceId(checkoutBaseUrl, invoiceId) {
     return null;
   }
 }
+function readStorefrontConsentValue() {
+  if (typeof document === "undefined" || typeof document.cookie !== "string") return null;
+  const value = document.cookie.split(";").map((part) => part.trim()).find((part) => part.startsWith(`${COOKIE_CONSENT_COOKIE}=`))?.slice(COOKIE_CONSENT_COOKIE.length + 1);
+  return parseCookieConsentValue(value) ? value : null;
+}
 function appendCheckoutUrlOptions(checkoutUrl, options) {
   const normalizedEmail = normalizeEmail(options.email);
   const normalizedLocale = typeof options.locale === "string" ? options.locale.trim() : "";
-  if (!normalizedEmail && !normalizedLocale) {
+  const consent = readStorefrontConsentValue();
+  if (!normalizedEmail && !normalizedLocale && !consent) {
     return checkoutUrl;
   }
   try {
@@ -2964,9 +3131,10 @@ function appendCheckoutUrlOptions(checkoutUrl, options) {
     if (normalizedLocale) {
       parsedCheckoutUrl.searchParams.set("locale", normalizedLocale);
     }
-    if (normalizedEmail) {
+    if (normalizedEmail || consent) {
       const hashParams = new URLSearchParams(parsedCheckoutUrl.hash.startsWith("#") ? parsedCheckoutUrl.hash.slice(1) : parsedCheckoutUrl.hash);
-      hashParams.set(CHECKOUT_PREFILL_EMAIL_HASH_KEY, normalizedEmail);
+      if (normalizedEmail) hashParams.set(CHECKOUT_PREFILL_EMAIL_HASH_KEY, normalizedEmail);
+      if (consent) hashParams.set(COOKIE_CONSENT_CHECKOUT_HASH_KEY, consent);
       parsedCheckoutUrl.hash = hashParams.toString();
     }
     return parsedCheckoutUrl.toString();
@@ -3080,7 +3248,10 @@ async function performCheckout(resolvedOptions) {
     // automatically so the server can refuse an invoice priced above it.
     // Undefined when nothing has been quoted this session — the endpoint
     // treats that exactly as an older SDK.
-    quote_token: resolvedOptions.quoteToken !== void 0 ? resolvedOptions.quoteToken ?? void 0 : getLatestQuoteToken() ?? void 0
+    quote_token: resolvedOptions.quoteToken !== void 0 ? resolvedOptions.quoteToken ?? void 0 : getLatestQuoteToken() ?? void 0,
+    // Where the buyer came from: their analytics sessions after a yes on the
+    // cookie banner, `declined` after a no. The server looks up the sources.
+    attribution: checkoutAttribution(config2.storeSlug)
   };
   const createAttempt = acquireCheckoutCreateIdempotency(checkoutRequestTarget, createIntent);
   const response = await post(
@@ -3929,7 +4100,6 @@ async function touchStorefrontPresence() {
     {
       event_type: "presence",
       referer: document.referrer || void 0,
-      connection_id: getStorefrontConnectionId(config2.storeSlug) ?? void 0,
       path: resolveStorefrontPagePath(),
       utm: resolveUtmParameters(config2.storeSlug)
     },