77 lines
1.8 KiB
TypeScript
77 lines
1.8 KiB
TypeScript
/**
|
|
* Type definition for analytics event properties.
|
|
*
|
|
* @example
|
|
* ```typescript
|
|
* const properties: AnalyticsEventProperties = {
|
|
* product_id: '123',
|
|
* product_name: 'Cable',
|
|
* price: 99.99,
|
|
* quantity: 1,
|
|
* in_stock: true,
|
|
* };
|
|
* ```
|
|
*/
|
|
export type AnalyticsEventProperties = Record<
|
|
string,
|
|
string | number | boolean | null | undefined
|
|
>;
|
|
|
|
/**
|
|
* Interface for analytics service implementations.
|
|
*
|
|
* This interface defines the contract for all analytics services,
|
|
* allowing for different implementations (Umami, Google Analytics, etc.)
|
|
* while maintaining a consistent API.
|
|
*
|
|
* @example
|
|
* ```typescript
|
|
* // Using the service directly
|
|
* const service = new UmamiAnalyticsService({ enabled: true });
|
|
* service.track('button_click', { button_id: 'cta' });
|
|
* service.trackPageview('/products/123');
|
|
* ```
|
|
*
|
|
* @example
|
|
* ```typescript
|
|
* // Using the useAnalytics hook (recommended)
|
|
* const { trackEvent, trackPageview } = useAnalytics();
|
|
* trackEvent('button_click', { button_id: 'cta' });
|
|
* trackPageview('/products/123');
|
|
* ```
|
|
*/
|
|
export interface AnalyticsService {
|
|
/**
|
|
* Track a custom event with optional properties.
|
|
*
|
|
* @param eventName - The name of the event to track
|
|
* @param props - Optional event properties (metadata)
|
|
*
|
|
* @example
|
|
* ```typescript
|
|
* track('product_add_to_cart', {
|
|
* product_id: '123',
|
|
* product_name: 'Cable',
|
|
* price: 99.99,
|
|
* });
|
|
* ```
|
|
*/
|
|
track(eventName: string, props?: AnalyticsEventProperties): void;
|
|
|
|
/**
|
|
* Track a pageview.
|
|
*
|
|
* @param url - The URL to track (defaults to current location)
|
|
*
|
|
* @example
|
|
* ```typescript
|
|
* // Track current page
|
|
* trackPageview();
|
|
*
|
|
* // Track custom URL
|
|
* trackPageview('/products/123?category=cables');
|
|
* ```
|
|
*/
|
|
trackPageview(url?: string): void;
|
|
}
|