@pageviews/tracker 0.2.4 → 0.4.1

package/README.md

@@ -37,6 +37,8 @@ track('signup', { props: { plan: 'pro' } })
 identify({ userId: 'user-123' })
 ```
 
+`track()` and `identify()` are safe to call before `init()` has finished, or even before it has been called: up to 100 calls are queued and sent, in order, as soon as tracking starts. Awaiting `init()` is optional.
+
 Your site ID is available in the Pageviews dashboard under **Settings → Tracking**.
 
 ## Framework Examples

package/dist/module/index.cjs

@@ -36,7 +36,14 @@ function sendBeaconEvent(endpoint, payload, siteId) {
 
 // src/core/utils.ts
 const ALLOWED_QUERY_PARAMS = new Set([
+    // Attribution
     'utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'ref',
+    // Pagination
+    'page', 'p', 'offset', 'limit', 'per_page',
+    // Sorting & filtering
+    'sort', 'order', 'orderby', 'order_by', 'filter', 'category', 'cat', 'tag', 'type',
+    // Content identifiers
+    'id', 'v', 'tab', 'view', 'lang', 'locale', 'hl',
 ]);
 function sanitizeUrl(url) {
     try {
@@ -469,6 +476,23 @@ const CACHE_KEY = 'pageviews_config';
 const CACHE_TTL = 1000 * 60 * 60; // 1 hour
 let instance = null;
 let initialized = false;
+/** Bumped by destroy(), so a config fetch that resolves afterwards does not start tracking. */
+let generation = 0;
+const MAX_QUEUED_CALLS = 100;
+/** track()/identify() calls made before init() has finished, replayed once tracking starts. */
+let queued = [];
+function enqueue(call) {
+    if (queued.length < MAX_QUEUED_CALLS)
+        queued.push(call);
+}
+function replayQueued() {
+    if (!instance)
+        return;
+    const calls = queued;
+    queued = [];
+    for (const call of calls)
+        call(instance.tracker);
+}
 function getCachedConfig(siteId) {
     try {
         const raw = localStorage.getItem(`${CACHE_KEY}_${siteId}`);
@@ -499,6 +523,7 @@ async function fetchConfig(endpoint, siteId) {
 }
 function startTracking(config) {
     instance = initTracking(config);
+    replayQueued();
 }
 async function init(options) {
     if (initialized)
@@ -506,6 +531,7 @@ async function init(options) {
     initialized = true;
     const ingestEndpoint = (options.endpoint || 'https://data.pageviews.ai') + '/api/event';
     const cfgEndpoint = options.configEndpoint || 'https://pageviews.ai';
+    const current = generation;
     const cached = getCachedConfig(options.siteId);
     if (cached) {
         startTracking(Object.assign(Object.assign({}, cached), { siteId: options.siteId, endpoint: ingestEndpoint }));
@@ -515,26 +541,46 @@ async function init(options) {
         }).catch(() => { });
         return;
     }
-    const configData = await fetchConfig(cfgEndpoint, options.siteId);
+    let configData;
+    try {
+        configData = await fetchConfig(cfgEndpoint, options.siteId);
+    }
+    catch (error) {
+        if (current === generation) {
+            initialized = false;
+            queued = [];
+        }
+        throw error;
+    }
+    if (current !== generation)
+        return;
     setCachedConfig(options.siteId, configData);
     startTracking(Object.assign(Object.assign({}, configData), { siteId: options.siteId, endpoint: ingestEndpoint }));
 }
+/** Sends a custom event. Calls made before init() has finished are queued and sent once it has. */
 function track(eventName, options) {
-    if (!instance)
-        throw new Error('pageviews.track() requires init() to be called first');
+    if (!instance) {
+        enqueue((tracker) => tracker.track(eventName, options));
+        return;
+    }
     instance.tracker.track(eventName, options);
 }
+/** Identifies the visitor. Calls made before init() has finished are queued and sent once it has. */
 function identify(data) {
-    if (!instance)
-        throw new Error('pageviews.identify() requires init() to be called first');
+    if (!instance) {
+        enqueue((tracker) => tracker.identify(data));
+        return;
+    }
     instance.tracker.identify(data);
 }
 function destroy() {
+    generation++;
+    queued = [];
+    initialized = false;
     if (!instance)
         return;
     instance.destroy();
     instance = null;
-    initialized = false;
 }
 
 exports.destroy = destroy;

package/dist/module/index.d.ts

@@ -38,7 +38,9 @@ interface InitOptions {
     configEndpoint?: string;
 }
 declare function init(options: InitOptions): Promise<void>;
+/** Sends a custom event. Calls made before init() has finished are queued and sent once it has. */
 declare function track(eventName: string, options?: TrackOptions): void;
+/** Identifies the visitor. Calls made before init() has finished are queued and sent once it has. */
 declare function identify(data: IdentifyData): void;
 declare function destroy(): void;
 

package/dist/module/index.mjs

@@ -34,7 +34,14 @@ function sendBeaconEvent(endpoint, payload, siteId) {
 
 // src/core/utils.ts
 const ALLOWED_QUERY_PARAMS = new Set([
+    // Attribution
     'utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'ref',
+    // Pagination
+    'page', 'p', 'offset', 'limit', 'per_page',
+    // Sorting & filtering
+    'sort', 'order', 'orderby', 'order_by', 'filter', 'category', 'cat', 'tag', 'type',
+    // Content identifiers
+    'id', 'v', 'tab', 'view', 'lang', 'locale', 'hl',
 ]);
 function sanitizeUrl(url) {
     try {
@@ -467,6 +474,23 @@ const CACHE_KEY = 'pageviews_config';
 const CACHE_TTL = 1000 * 60 * 60; // 1 hour
 let instance = null;
 let initialized = false;
+/** Bumped by destroy(), so a config fetch that resolves afterwards does not start tracking. */
+let generation = 0;
+const MAX_QUEUED_CALLS = 100;
+/** track()/identify() calls made before init() has finished, replayed once tracking starts. */
+let queued = [];
+function enqueue(call) {
+    if (queued.length < MAX_QUEUED_CALLS)
+        queued.push(call);
+}
+function replayQueued() {
+    if (!instance)
+        return;
+    const calls = queued;
+    queued = [];
+    for (const call of calls)
+        call(instance.tracker);
+}
 function getCachedConfig(siteId) {
     try {
         const raw = localStorage.getItem(`${CACHE_KEY}_${siteId}`);
@@ -497,6 +521,7 @@ async function fetchConfig(endpoint, siteId) {
 }
 function startTracking(config) {
     instance = initTracking(config);
+    replayQueued();
 }
 async function init(options) {
     if (initialized)
@@ -504,6 +529,7 @@ async function init(options) {
     initialized = true;
     const ingestEndpoint = (options.endpoint || 'https://data.pageviews.ai') + '/api/event';
     const cfgEndpoint = options.configEndpoint || 'https://pageviews.ai';
+    const current = generation;
     const cached = getCachedConfig(options.siteId);
     if (cached) {
         startTracking(Object.assign(Object.assign({}, cached), { siteId: options.siteId, endpoint: ingestEndpoint }));
@@ -513,26 +539,46 @@ async function init(options) {
         }).catch(() => { });
         return;
     }
-    const configData = await fetchConfig(cfgEndpoint, options.siteId);
+    let configData;
+    try {
+        configData = await fetchConfig(cfgEndpoint, options.siteId);
+    }
+    catch (error) {
+        if (current === generation) {
+            initialized = false;
+            queued = [];
+        }
+        throw error;
+    }
+    if (current !== generation)
+        return;
     setCachedConfig(options.siteId, configData);
     startTracking(Object.assign(Object.assign({}, configData), { siteId: options.siteId, endpoint: ingestEndpoint }));
 }
+/** Sends a custom event. Calls made before init() has finished are queued and sent once it has. */
 function track(eventName, options) {
-    if (!instance)
-        throw new Error('pageviews.track() requires init() to be called first');
+    if (!instance) {
+        enqueue((tracker) => tracker.track(eventName, options));
+        return;
+    }
     instance.tracker.track(eventName, options);
 }
+/** Identifies the visitor. Calls made before init() has finished are queued and sent once it has. */
 function identify(data) {
-    if (!instance)
-        throw new Error('pageviews.identify() requires init() to be called first');
+    if (!instance) {
+        enqueue((tracker) => tracker.identify(data));
+        return;
+    }
     instance.tracker.identify(data);
 }
 function destroy() {
+    generation++;
+    queued = [];
+    initialized = false;
     if (!instance)
         return;
     instance.destroy();
     instance = null;
-    initialized = false;
 }
 
 export { destroy, identify, init, track };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pageviews/tracker",
-  "version": "0.2.4",
+  "version": "0.4.1",
   "description": "Lightweight, cookie-free analytics tracker for PageViews.ai",
   "author": "Pageviews <hello@pageviews.ai>",
   "homepage": "https://pageviews.ai",