Appearance

useAnalytics Composable ​

File Information ​

  • Path: app/composables/core/common/useAnalytics.ts
  • Purpose: Analytics tracking and event dispatching
  • Type: Core Common Composable

Overview ​

The useAnalytics composable provides analytics tracking functionality for user actions and events. It collects user agent and location data, obfuscates transaction data, and sends analytics events to the backend.

Features ​

  • Event Tracking: Track user actions and events
  • User Agent & Location: Collect browser and location data
  • Data Obfuscation: Obfuscates transaction data for security
  • Share Analytics: Special analytics for sharing events
  • Workspace Context: Automatically includes workspace ID

Return Type ​

typescript
{
  dispatchAnalytics: (payload: AnalyticsPayload) => Promise<void>
  dispatchAnalyticsShare: (payload: AnalyticsPayload) => Promise<void>
}

Methods ​

dispatchAnalytics(payload) ​

Dispatches an analytics event with user agent and location data.

typescript
const { dispatchAnalytics } = useAnalytics()

await dispatchAnalytics({
  asset_id: [123],
  event: 'asset',
  sub_event: 'viewed',
  environment: 'dealer'
})

dispatchAnalyticsShare(payload) ​

Dispatches analytics specifically for sharing events.

typescript
await dispatchAnalyticsShare({
  asset_id: [123],
  event: 'share',
  sub_event: 'created',
  environment: 'dealer'
})

AnalyticsPayload ​

typescript
{
  asset_id?: number[]        // Asset IDs
  category_id?: number[]     // Category/Folder IDs
  collection_id?: string     // Collection/Collage ID
  event: string             // Event type (e.g., 'asset', 'folder', 'collage')
  sub_event: string         // Sub-event (e.g., 'viewed', 'downloaded', 'shared')
  environment: string       // Environment ('dealer' or 'anonymous')
  workspace_id?: string     // Workspace ID (optional, auto-filled)
}

Implementation Details ​

Data Collection ​

  • Fetches user agent and location from /api/browser-os endpoint
  • Caches user agent and location in analytics store
  • Only runs on client side (import.meta.client)

Data Obfuscation ​

  • Converts payload to JSON string
  • Base64 encodes the data
  • Reverses the encoded string for obfuscation
  • Sends obfuscated data to backend

Backend Endpoint ​

  • POST to digital/add-transaction-activity
  • Includes workspace_id in query and body
  • Handles errors silently (logs to console)

Usage Example ​

typescript
import { useAnalytics } from '~/composables/core/common/useAnalytics'

const { dispatchAnalytics } = useAnalytics()

// Track asset view
const trackAssetView = async (assetId: number) => {
  await dispatchAnalytics({
    asset_id: [assetId],
    event: 'asset',
    sub_event: 'viewed',
    environment: 'dealer'
  })
}

// Track download
const trackDownload = async (assetIds: number[]) => {
  await dispatchAnalytics({
    asset_id: assetIds,
    event: 'asset',
    sub_event: 'downloaded',
    environment: 'dealer'
  })
}

// Track folder view
const trackFolderView = async (folderId: number) => {
  await dispatchAnalytics({
    category_id: [folderId],
    event: 'folder',
    sub_event: 'viewed',
    environment: 'dealer'
  })
}

Dependencies ​

  • useAnalyticStore() - Analytics store for caching user agent/location
  • useAuthStore() - Auth store for workspace ID
  • useNuxtApp().$api - API client
  • useHelpers - Helper functions including workspace ID