diff --git a/package-lock.json b/package-lock.json index 97d933f..8959b5f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -5083,7 +5083,7 @@ }, "packages/core": { "name": "@hacktoolkit/nextjs-htk", - "version": "0.1.0", + "version": "0.2.0", "license": "MIT", "dependencies": { "@fortawesome/fontawesome-svg-core": "^6.5.1", diff --git a/packages/core/src/components/MetaPixel.tsx b/packages/core/src/components/MetaPixel.tsx new file mode 100644 index 0000000..16faa81 --- /dev/null +++ b/packages/core/src/components/MetaPixel.tsx @@ -0,0 +1,111 @@ +'use client' + +import Script from 'next/script' + +export interface MetaPixelProps { + /** Meta (Facebook) Pixel ID (e.g., '1234567890123456') */ + pixelId: string + /** Load strategy (default: 'afterInteractive') */ + strategy?: 'afterInteractive' | 'lazyOnload' | 'beforeInteractive' + /** Disable automatic PageView tracking (default: false) */ + disablePageView?: boolean +} + +const PIXEL_ID_PATTERN = /^\d{15,16}$/ + +export function MetaPixel({ + pixelId, + strategy = 'afterInteractive', + disablePageView = false +}: MetaPixelProps) { + // Don't render if no pixel ID or invalid format + if (!pixelId || !PIXEL_ID_PATTERN.test(pixelId)) { + return null + } + + const pageViewScript = disablePageView ? '' : `fbq('track', 'PageView');` + + return ( + <> + + {!disablePageView && ( + + )} + + ) +} + +/** + * Track a standard Meta Pixel event + * Use this for Facebook's predefined standard events + * + * @see https://developers.facebook.com/docs/meta-pixel/reference#standard-events + * + * @example + * trackMetaEvent('Lead') + * trackMetaEvent('Purchase', { value: 99.99, currency: 'USD' }) + * trackMetaEvent('AddToCart', { content_ids: ['SKU123'], value: 29.99 }) + */ +export function trackMetaEvent( + eventName: string, + params?: Record +) { + if (typeof window !== 'undefined' && typeof window.fbq === 'function') { + window.fbq('track', eventName, params) + } +} + +/** + * Track a custom Meta Pixel event + * Use this for your own custom events (not Facebook's standard events) + * + * @see https://developers.facebook.com/docs/meta-pixel/reference#custom-events + * + * @example + * trackMetaCustomEvent('StartTrial') + * trackMetaCustomEvent('ShareContent', { content_type: 'article' }) + */ +export function trackMetaCustomEvent( + eventName: string, + params?: Record +) { + if (typeof window !== 'undefined' && typeof window.fbq === 'function') { + window.fbq('trackCustom', eventName, params) + } +} + +// Extend Window interface for TypeScript +declare global { + interface Window { + fbq: { + (action: 'init', pixelId: string, options?: Record): void + ( + action: 'track' | 'trackCustom', + eventName: string, + params?: Record + ): void + (action: string, ...args: unknown[]): void + } + } +} diff --git a/packages/core/src/components/index.ts b/packages/core/src/components/index.ts index 8402adc..16a4156 100644 --- a/packages/core/src/components/index.ts +++ b/packages/core/src/components/index.ts @@ -1,3 +1,4 @@ export * from './BasicPageLayout' export * from './GoogleAnalytics' +export * from './MetaPixel' export * from './ScrollToTop'