fix(UmamiAnalytics): v2.18 compatibility

Fixes #459

Author: harlan-zw

docs/content/scripts/analytics/umami-analytics.md

@@ -100,7 +100,7 @@ useScriptUmamiAnalytics({
 ```ts
 export interface UmamiAnalyticsApi {
   track: ((payload?: Record<string, any>) => void) &((event_name: string, event_data: Record<string, any>) => void)
-  identify: (session_data?: Record<string, any>) => void
+  identify: (session_data?: Record<string, any> | string) => void
 }
 ```
 
@@ -133,6 +133,75 @@ export const UmamiAnalyticsOptions = object({
    * Events can be filtered in the dashboard by a specific tag.
    */
   tag: optional(string()),
+  /**
+   * Function that will be called before data is sent to Umami.
+   * The function takes two parameters: type and payload.
+   * Return the payload to continue sending, or return a falsy value to cancel.
+   */
+  beforeSend: optional(union([
+    custom<(type: string, payload: Record<string, any>) => Record<string, any> | null | false>(input => typeof input === 'function'),
+    string(),
+  ])),
+})
+```
+
+## Advanced Features
+
+### Session Identification
+
+Umami v2.18.0+ supports setting unique session IDs using the `identify` function. You can pass either a string (unique ID) or an object with session data:
+
+```ts
+const { proxy } = useScriptUmamiAnalytics({
+  websiteId: 'YOUR_WEBSITE_ID'
+})
+
+// Using a unique string ID
+proxy.identify('user-12345')
+
+// Using session data object
+proxy.identify({
+  userId: 'user-12345',
+  plan: 'premium'
+})
+```
+
+### Data Filtering with beforeSend
+
+The `beforeSend` option allows you to inspect, modify, or cancel data before it's sent to Umami. This is useful for implementing custom privacy controls or data filtering:
+
+```ts
+useScriptUmamiAnalytics({
+  websiteId: 'YOUR_WEBSITE_ID',
+  beforeSend: (type, payload) => {
+    // Log what's being sent (for debugging)
+    console.log('Sending to Umami:', type, payload)
+    
+    // Filter out sensitive data
+    if (payload.url && payload.url.includes('private')) {
+      return false // Cancel send
+    }
+    
+    // Modify payload before sending
+    return {
+      ...payload,
+      referrer: '' // Remove referrer for privacy
+    }
+  }
+})
+```
+
+You can also provide a string with the name of a globally defined function:
+
+```ts
+// Define function globally
+window.myBeforeSendHandler = (type, payload) => {
+  return checkPrivacyRules(payload) ? payload : false
+}
+
+useScriptUmamiAnalytics({
+  websiteId: 'YOUR_WEBSITE_ID',
+  beforeSend: 'myBeforeSendHandler'
 })
 ```
 

src/runtime/registry/umami-analytics.ts

@@ -1,5 +1,5 @@
 import { useRegistryScript } from '../utils'
-import { object, optional, string, boolean, array } from '#nuxt-scripts-validator'
+import { object, optional, string, boolean, array, union, custom } from '#nuxt-scripts-validator'
 import type { RegistryScriptInput } from '#nuxt-scripts/types'
 
 export const UmamiAnalyticsOptions = object({
@@ -26,13 +26,22 @@ export const UmamiAnalyticsOptions = object({
    * Events can be filtered in the dashboard by a specific tag.
    */
   tag: optional(string()),
+  /**
+   * Function that will be called before data is sent to Umami.
+   * The function takes two parameters: type and payload.
+   * Return the payload to continue sending, or return a falsy value to cancel.
+   */
+  beforeSend: optional(union([
+    custom<(type: string, payload: Record<string, any>) => Record<string, any> | null | false>(input => typeof input === 'function'),
+    string(),
+  ])),
 })
 
 export type UmamiAnalyticsInput = RegistryScriptInput<typeof UmamiAnalyticsOptions, false>
 
 export interface UmamiAnalyticsApi {
   track: ((payload?: Record<string, any>) => void) & ((event_name: string, event_data: Record<string, any>) => void)
-  identify: (session_data?: Record<string, any>) => void
+  identify: (session_data?: Record<string, any> | string) => void
 }
 
 declare global {
@@ -44,6 +53,21 @@ declare global {
 export function useScriptUmamiAnalytics<T extends UmamiAnalyticsApi>(_options?: UmamiAnalyticsInput) {
   return useRegistryScript<T, typeof UmamiAnalyticsOptions>('umamiAnalytics', (options) => {
     const domains = Array.isArray(options?.domains) ? options.domains.join(',') : options?.domains
+
+    let beforeSendFunctionName: string | undefined
+    if (import.meta.client) {
+      // Handle beforeSend function
+      if (options?.beforeSend && typeof options.beforeSend === 'function') {
+        // Generate a random function name
+        beforeSendFunctionName = `__umamiBeforeSend_${Math.random().toString(36).substring(2, 15)}`
+        // Add function to window global scope
+        ;(window as any)[beforeSendFunctionName] = options.beforeSend
+      }
+      else if (typeof options.beforeSend === 'string') {
+        // If it's a string, assume it's a function name already defined in the global scope
+        beforeSendFunctionName = options.beforeSend
+      }
+    }
     return {
       scriptInput: {
         'src': 'https://cloud.umami.is/script.js',
@@ -52,6 +76,7 @@ export function useScriptUmamiAnalytics<T extends UmamiAnalyticsApi>(_options?:
         'data-auto-track': typeof options?.autoTrack === 'boolean' ? options.autoTrack : true,
         'data-domains': domains || undefined,
         'data-tag': options?.tag || undefined,
+        'data-before-send': beforeSendFunctionName || undefined,
       },
       schema: import.meta.dev ? UmamiAnalyticsOptions : undefined,
       scriptOptions: {

src/runtime/validation/mock.ts

@@ -21,3 +21,4 @@ export const any = noop
 export const minLength = noop
 
 export const pipe = noop
+export const custom = noop