feat: new interface tracking functions

Author: JeanMeijer

examples/nuxt-v3/server/api/track-event.post.ts

@@ -2,12 +2,9 @@ import { defineEventHandler, createError } from "h3";
 
 export default defineEventHandler(async (event) => {
   try {
-    await trackEvent("button_clicked", {
-      event,
-      metadata: {
-        source: "test_page",
-      },
-    });
+    await trackEvent(event, "button_clicked", {
+      external_id: "1234",
+    }); 
 
     return {
       success: true,

examples/nuxt-v4/server/api/track-event.post.ts

@@ -2,11 +2,8 @@ import { defineEventHandler, createError } from "h3";
 
 export default defineEventHandler(async (event) => {
   try {
-    await trackEvent("button_clicked", {
-      event,
-      metadata: {
-        source: "test_page",
-      },
+    await trackEvent(event, "button_clicked", {
+      external_id: "1234",
     });
 
     return {

packages/nuxt/README.md

@@ -18,13 +18,14 @@ export default defineNuxtConfig({
   simpleAnalytics: {
     hostname: "your-domain.com",
     enabled: true,
-    proxy: true,
   },
 });
 ```
 
 ## Usage
 
+Adding the module will automatically enable client-side page view collection though the Simple Analytics script.
+
 ### Server-side Pageview Tracking
 
 Track pageviews automatically on the server:
@@ -34,10 +35,7 @@ Track pageviews automatically on the server:
 // This will run on the server and track the pageview
 if (import.meta.server) {
   await trackPageview({
-    hostname: "your-domain.com",
-    metadata: {
-      source: "homepage",
-    },
+    some_extra_metadata: "homepage"
   });
 }
 </script>
@@ -48,14 +46,11 @@ if (import.meta.server) {
 Track custom events from API routes or server-side code:
 
 ```ts
-// In a server API route
+// In a (Nitro) server API route
 export default defineEventHandler(async (event) => {
-  await trackEvent("user_signup", {
-    event,
-    metadata: {
-      source: "registration_form",
-      user_type: "new",
-    },
+  await trackEvent(event, "user_signup", {
+    source: "registration_form",
+    user_type: "new",
   });
 
   return { success: true };
@@ -75,9 +70,6 @@ export default defineNuxtConfig({
     // Enable/disable the module
     enabled: true,
 
-    // Enable/disable proxy
-    proxy: true,
-
     // Auto-collect events
     autoCollect: true,
 
@@ -99,6 +91,9 @@ export default defineNuxtConfig({
       screensize: false,
       viewportsize: false,
       language: false,
+
+      // Use vendor specific timezone headers to the determine the visitors location (server only)
+      timezone: false
     },
 
     // Ignore specific pages
@@ -112,6 +107,9 @@ export default defineNuxtConfig({
 
     // Strict UTM parameter parsing
     strictUtm: true,
+
+    // Enable enhanced bot detection during server tracking (server only)
+    enhancedBotDetection: false
   },
 });
 ```
@@ -131,7 +129,7 @@ Track a pageview on the server.
 
 **Parameters:**
 
-- `options` (object): Additional metadata to track (optional)
+- `metadata` (object): Additional metadata to track (optional)
 
 ### `trackEvent(eventName, options)`
 
@@ -140,40 +138,28 @@ Track a custom event on the server.
 **Parameters:**
 
 - `eventName` (string): Name of the event to track
-- `options` (object): Additional metadata to track (option)
+- `metadata` (object): Additional metadata to track (optional)
 
 ## API Reference (Nitro)
 
-### `trackPageview(requestEvent, options)`
+### `trackPageview(event, options)`
 
 Track a pageview on the server.
 
 **Parameters:**
 
-- `options` (object): Additional metadata to track (optional)
+- `event` (H3Event): Nitro request event
+- `metadata` (object): Additional metadata to track (optional)
 
-### `trackEvent(requestEvent, eventName, options)`
+### `trackEvent(event, eventName, options)`
 
 Track a custom event on the server.
 
 **Parameters:**
 
-- `options` (object):
-  - `hostname` (string): Your Simple Analytics hostname
-  - `metadata` (object): Additional metadata to track
-  - `ignoreMetrics` (object): Metrics to ignore for this pageview
-  - `collectDnt` (boolean): Whether to collect data when DNT is enabled
-  - `strictUtm` (boolean): Whether to use strict UTM parameter parsing
-
-## Migration to v2.0
-
-## Do Not Track (DNT)
-
-### Client-side analytics
-
-### Server-side analytics
-
-## Ignoring metrics To also record DNT visitors you can add data-collect-dnt="true" to the script tag
+- `event` (H3Event): Nitro request event
+- `eventName` (string): Name of the event to track
+- `metadata` (object): Additional metadata to track (optional)
 
 ## License
 

packages/nuxt/playground/nuxt.config.ts

@@ -1,4 +1,7 @@
 export default defineNuxtConfig({
   modules: ["../src/module"],
   devtools: { enabled: true },
+  simpleAnalytics: {
+    hostname: "playground.example.com",
+  },
 });

packages/nuxt/playground/server/api/track-event.post.ts

@@ -5,10 +5,8 @@ export default defineEventHandler(async (event) => {
     const { eventName, metadata } = await readBody(event);
 
     // Track the custom event using server-side function
-    await trackEvent(eventName, {
-      event,
-      metadata,
-      hostname: "playground.example.com",
+    await trackEvent(event, eventName, {
+      ...metadata,
     });
 
     return {

packages/nuxt/src/runtime/interfaces.ts

@@ -19,9 +19,15 @@ export interface SimpleAnalyticsOptions {
     screensize?: boolean;
     viewportsize?: boolean;
     language?: boolean;
+    // server-side only
+    timezone?: boolean;
   };
   ignorePages?: string[];
   allowParams?: string[];
   nonUniqueParams?: string[];
   strictUtm?: boolean;
+  // server-side only
+  enhancedBotDetection?: boolean;
 }
+
+export type IgnoredMetrics = SimpleAnalyticsOptions['ignoreMetrics'];

packages/nuxt/src/runtime/nitro/interface.ts

@@ -1,53 +1,48 @@
-import type { AnalyticsEvent, TrackingOptions } from "../server/lib/interfaces";
+import type { AnalyticsEvent } from "../server/lib/interfaces";
 import {
   isProduction,
   isDoNotTrackEnabled,
-  isEnhancedBotDetectionEnabled,
 } from "../server/lib/utils";
 import { parseHeaders } from "../server/lib/headers";
 import { useRuntimeConfig } from "#imports";
-import type { NitroContext } from "./interface";
-
-type TrackEventOptions = TrackingOptions & NitroContext;
+import type { H3Event } from "h3";
 
 export async function trackEvent(
+  event: H3Event,
   eventName: string,
-  options: TrackEventOptions
+  metadata?: Record<string, string | boolean | number | Date>
 ) {
   if (!isProduction()) {
     return;
   }
 
-  const hostname =
-    options?.hostname ?? useRuntimeConfig().public.simpleAnalytics.hostname;
+  const config = useRuntimeConfig().public.simpleAnalytics;
+  const hostname = config.hostname;
 
   if (!hostname) {
     console.warn("No hostname provided for Simple Analytics");
     return;
   }
 
-  const { headers } = options.event;
-
-  if (isDoNotTrackEnabled(headers) && !options?.collectDnt) {
+  if (isDoNotTrackEnabled(event.headers) && !config.collectDnt) {
     return;
   }
 
   const payload: AnalyticsEvent = {
     type: "event",
     hostname,
     event: eventName,
-    metadata: options?.metadata,
-    ...parseHeaders(headers, options?.ignoreMetrics),
+    metadata,
+    ...parseHeaders(event.headers, config.ignoreMetrics),
   };
 
   const response = await fetch("https://queue.simpleanalyticscdn.com/events", {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
-      ...(headers.has("X-Forwarded-For") &&
-        options &&
-        isEnhancedBotDetectionEnabled(options) && {
-          "X-Forwarded-For": headers.get("X-Forwarded-For")!,
+      ...(event.headers.has("X-Forwarded-For") &&
+        config.enhancedBotDetection && {
+          "X-Forwarded-For": event.headers.get("X-Forwarded-For")!,
         }),
     },
     body: JSON.stringify(payload),

packages/nuxt/src/runtime/nitro/track-event.ts

@@ -1,49 +1,44 @@
 import type {
   AnalyticsPageview,
-  TrackingOptions,
 } from "../server/lib/interfaces";
 import {
   isProduction,
   isDoNotTrackEnabled,
-  isEnhancedBotDetectionEnabled,
 } from "../server/lib/utils";
 import { parseHeaders } from "../server/lib/headers";
 import { parseUtmParameters } from "../server/lib/utm";
 import { useRuntimeConfig } from "#imports";
-import type { NitroContext } from "./interface";
+import type { H3Event } from "h3";
 
 // eslint-disable-next-line regexp/no-unused-capturing-group
 const PROXY_PATHS = /^\/(proxy\.js|auto-events\.js|simple\/.*)$/;
 
-type TrackPageviewOptions = TrackingOptions & NitroContext;
-
-export async function trackPageview(options: TrackPageviewOptions) {
+export async function trackPageview(event: H3Event, metadata?: Record<string, string | boolean | number | Date>) {
   if (!isProduction()) {
     return;
   }
 
-  const hostname =
-    options?.hostname ?? useRuntimeConfig().public.simpleAnalytics.hostname;
+  const config = useRuntimeConfig().public.simpleAnalytics;
+  const hostname = config.hostname;
 
   if (!hostname) {
     console.warn("No hostname provided for Simple Analytics");
     return;
   }
 
   // We don't record non-GET requests
-  if (options.event.method !== "GET") {
+  if (event.method !== "GET") {
     return;
   }
 
-  const { headers } = options.event;
-  const { path, query } = options.event.context.route;
+  const { path, query } = event.context.route;
 
   // We don't record non-navigation requests
-  if (headers.get("Sec-Fetch-Mode") !== "navigate") {
+  if (event.headers.get("Sec-Fetch-Mode") !== "navigate") {
     return;
   }
 
-  if (isDoNotTrackEnabled(headers) && !options?.collectDnt) {
+  if (isDoNotTrackEnabled(event.headers) && !config.collectDnt) {
     return;
   }
 
@@ -56,10 +51,11 @@ export async function trackPageview(options: TrackPageviewOptions) {
     hostname,
     event: "pageview",
     path,
-    ...parseHeaders(headers, options?.ignoreMetrics),
-    ...(query && !options?.ignoreMetrics?.utm
+    metadata,
+    ...parseHeaders(event.headers, config.ignoreMetrics),
+    ...(query && !config.ignoreMetrics?.utm
       ? parseUtmParameters(query, {
-          strictUtm: options?.strictUtm ?? true,
+          strictUtm: config.strictUtm ?? true,
         })
       : {}),
   };
@@ -68,10 +64,9 @@ export async function trackPageview(options: TrackPageviewOptions) {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
-      ...(headers.has("X-Forwarded-For") &&
-        options &&
-        isEnhancedBotDetectionEnabled(options) && {
-          "X-Forwarded-For": headers.get("X-Forwarded-For")!,
+      ...(event.headers.has("X-Forwarded-For") &&
+        config.enhancedBotDetection && {
+          "X-Forwarded-For": event.headers.get("X-Forwarded-For")!,
         }),
     },
     body: JSON.stringify(payload),

packages/nuxt/src/runtime/nitro/track-pageview.ts

@@ -10,14 +10,26 @@ type SimpleAnalyticsPlugin = Plugin & {
   install(app: App, options?: SimpleAnalyticsOptions): void;
 };
 
+function removeServerOnlyOptions(options: SimpleAnalyticsOptions) {
+  return {
+    ...options,
+    ignoreMetrics: {
+      ...options.ignoreMetrics ?? {},
+      timezone: undefined,
+    },
+    enhancedBotDetection: undefined,
+  };
+}
+
 export default defineNuxtPlugin((nuxtApp) => {
   const config = useRuntimeConfig();
 
+  // TODO: add proxy support Vue plugin
   const { enabled, proxy, ...options } = config.public.simpleAnalytics;
 
   // We have to cast the plugin here because the forced .mjs import
   nuxtApp.vueApp.use(SimpleAnalytics as SimpleAnalyticsPlugin, {
     skip: config.public.simpleAnalytics.enabled === false,
-    ...options,
+    ...removeServerOnlyOptions(options),
   });
 });