shopkit-analytics 1.0.0 → 1.0.2

package/README.md

@@ -7,6 +7,8 @@ A comprehensive analytics package for e-commerce applications with support for m
 - **Multiple Analytics Platforms**: Support for 7+ analytics adapters
 - **Event-Driven Architecture**: Publisher-subscriber pattern for flexible event handling
 - **TypeScript Support**: Full type safety and IntelliSense
+- **Adapter-Specific Parameters**: Customize event names and parameters per adapter
+- **Server-Side Tracking**: Facebook CAPI integration with event deduplication
 - **Affiliate Tracking**: Built-in UTM parameter and attribution tracking
 - **React Integration**: Easy-to-use React components
 - **Selective Adapter Routing**: Route events to specific adapters
@@ -77,6 +79,95 @@ publishEvent({
 });
 ```
 
+## 🎯 Adapter-Specific Parameters
+
+All 7 adapters now support adapter-specific parameter customization, allowing you to override event names and add custom parameters per adapter while maintaining a single event call.
+
+### Basic Usage
+
+```tsx
+import { publishEvent, EventType } from "@shopkit/analytics";
+
+// Standard event (works with all adapters)
+publishEvent({
+  type: EventType.ADD_TO_CART,
+  productId: "123",
+  productName: "Cool Product",
+  price: 29.99,
+});
+
+// Advanced usage with adapter-specific parameters
+publishEvent({
+  type: EventType.ADD_TO_CART,
+  productId: "123",
+  productName: "Cool Product",
+  price: 29.99,
+}, {
+  // Customize for each adapter
+  GoogleAnalytics: {
+    event_name: "custom_add_to_cart",
+    custom_dimension_1: "premium_user",
+    campaign_id: "summer_campaign"
+  },
+  FacebookPixel: {
+    event_name: "CustomAddToCart",
+    custom_parameter: "special_value",
+    pixel_specific_data: { campaign: "summer2024" }
+  },
+  PostHog: {
+    event_name: "add_to_cart_premium",
+    feature_flag: "new_checkout_flow"
+  },
+  MoEngage: {
+    event_name: "cart_item_added",
+    user_segment: "premium_customers"
+  },
+  KwikCheckout: {
+    event_name: "gokwik_add_to_cart",
+    checkout_flow: "express"
+  },
+  KwikPass: {
+    event_name: "kwikpass_cart_add",
+    pass_type: "premium"
+  },
+  ShopifyAnalytics: {
+    event_name: "shopify_add_to_cart",
+    pageType: "product",
+    custom_shopify_param: "value"
+  }
+});
+```
+
+### TypeScript Support
+
+Full TypeScript support with IntelliSense for all adapter names:
+
+```tsx
+import type { IAdapterParams } from "@shopkit/analytics";
+
+const customParams: IAdapterParams = {
+  GoogleAnalytics: {
+    event_name: "custom_event",
+    // Full type safety for parameters
+  },
+  FacebookPixel: {
+    event_name: "CustomEvent",
+    // Adapter-specific parameters
+  },
+  // ... other adapters
+};
+
+publishEvent(eventData, customParams);
+```
+
+### Key Benefits
+
+- **🎯 Flexibility**: Customize event names and parameters per adapter
+- **🔄 Backward Compatibility**: Optional parameters maintain existing API
+- **🛡️ Type Safety**: Full TypeScript support with proper interfaces
+- **⚡ Performance**: No overhead when not using custom parameters
+- **🧹 Clean API**: Single event call handles all adapters
+
 ## 🔧 Analytics Adapters
 
 ### 1. Google Analytics 4
@@ -105,13 +196,14 @@ Track events to Google Analytics 4 with enhanced e-commerce support.
 
 ### 2. Facebook Pixel
 
-Track conversions and optimize Facebook ad campaigns.
+Track conversions and optimize Facebook ad campaigns with both client-side and server-side tracking support.
 
 ```tsx
 <ShopkitAnalytics
   config={{
     facebookPixel: {
       pixelId: "123456789",
+      enableCAPI: true, // Enable server-side CAPI backup
       enableDebugLogs: true,
       enableAdvancedMatching: true,
     },
@@ -124,6 +216,13 @@ Track conversions and optimize Facebook ad campaigns.
 - InitiateCheckout, Search
 - Custom conversions
 
+**Server-Side Tracking (CAPI):**
+- Automatic server-side backup for improved data reliability
+- Event deduplication using unique event IDs
+- Enhanced browser fingerprinting for better user matching
+- Fallback mechanism when client-side tracking fails
+- Requires `/api/events` endpoint for server-side processing
+
 ### 3. MoEngage
 
 Engage users with personalized campaigns and analytics.
@@ -196,7 +295,7 @@ NEXT_PUBLIC_POSTHOG_KEY="phc_xxxxxxxxxx"
 
 ### 5. Shopify Analytics
 
-Native Shopify Admin Analytics integration.
+Native Shopify Admin Analytics integration with full adapter parameter support.
 
 ```tsx
 <ShopkitAnalytics
@@ -222,6 +321,23 @@ NEXT_PUBLIC_SHOPIFY_CURRENCY="USD"
 - Add to cart, checkout events
 - Session tracking with Shopify cookies
 
+**Adapter Parameter Support:**
+```tsx
+publishEvent({
+  type: EventType.ADD_TO_CART,
+  productId: "123",
+  productName: "Product",
+  price: 29.99,
+}, {
+  ShopifyAnalytics: {
+    event_name: "custom_shopify_event",
+    pageType: "product",
+    collectionHandle: "featured-products",
+    custom_shopify_param: "value"
+  }
+});
+```
+
 ### 6. KwikPass Analytics
 
 Custom analytics adapter for KwikPass platform integration.
@@ -285,7 +401,146 @@ NEXT_PUBLIC_STORE_ID="your-store-id"
 - `ORDER_SUCCESS` - Order success confirmation
 - `ORDER_COMPLETED` - Order fulfillment
 
-## 📝 Professional Logging System
+## 🔄 Server-Side Tracking (CAPI)
+
+The Facebook Pixel adapter supports server-side tracking through the Conversions API (CAPI) for improved data reliability and privacy compliance.
+
+### Features
+
+- **Automatic Fallback**: Server-side tracking runs as a backup to client-side tracking
+- **Event Deduplication**: Unique event IDs prevent duplicate tracking across client/server
+- **Enhanced Matching**: Browser fingerprinting for better user matching
+- **Privacy Compliant**: Respects user privacy while improving data quality
+- **Built-in CAPI Service**: Uses the integrated `FacebookCAPIService` for server-side processing
+
+### Environment Variables
+
+Set up the required environment variables for CAPI:
+
+```bash
+# Facebook CAPI Configuration
+FACEBOOK_CAPI_ACCESS_TOKEN="your_facebook_access_token"
+NEXT_PUBLIC_PIXEL_ID="123456789"
+FACEBOOK_TEST_EVENT_CODE="TEST12345" # Optional: for testing
+```
+
+### Server-Side Endpoint Implementation
+
+Create an `/api/events` endpoint to handle server-side tracking:
+
+```tsx
+// app/api/events/route.ts
+import { createFacebookCAPIService } from "@shopkit/analytics/services/facebook-capi";
+import { TEvent } from "@shopkit/analytics/types";
+
+/**
+ * Get client IP address from request headers
+ */
+function getClientIpAddress(request: Request): string | undefined {
+  // Try different headers for IP address
+  const forwarded = request.headers.get("x-forwarded-for");
+  const realIp = request.headers.get("x-real-ip");
+  const cfConnectingIp = request.headers.get("cf-connecting-ip");
+
+  return forwarded?.split(",")[0] || realIp || cfConnectingIp || undefined;
+}
+
+export async function POST(request: Request) {
+  try {
+    const { events, userInfo } = await request.json();
+
+    // Validate events array
+    if (!Array.isArray(events) || events.length === 0) {
+      return Response.json({ error: "Invalid events data" }, { status: 400 });
+    }
+
+    // Create CAPI service with explicit configuration
+    const capiService = createFacebookCAPIService({
+      accessToken: process.env.FACEBOOK_CAPI_ACCESS_TOKEN!,
+      pixelId: process.env.NEXT_PUBLIC_PIXEL_ID!,
+      testEventCode: process.env.FACEBOOK_TEST_EVENT_CODE,
+    });
+
+    if (!capiService) {
+      console.warn("Facebook CAPI service not available - missing configuration");
+      return Response.json(
+        { error: "CAPI service not configured" },
+        { status: 500 }
+      );
+    }
+
+    // Enhance user info with server-side data
+    const enhancedUserInfo = {
+      ...userInfo,
+      clientIpAddress: getClientIpAddress(request),
+    };
+
+    // Send events to Facebook CAPI
+    await capiService.sendEvents(events as TEvent[], enhancedUserInfo);
+
+    return Response.json({
+      success: true,
+      message: `Successfully sent ${events.length} events to Facebook CAPI`,
+    });
+  } catch (error) {
+    console.error("API Events Error:", error);
+    return Response.json(
+      { error: "Failed to process events" },
+      { status: 500 }
+    );
+  }
+}
+```
+
+### Supported Events
+
+The CAPI service currently supports these events (matching the PixelAdapter implementation):
+
+- `PAGE_VIEW` → Facebook `PageView`
+- `PRODUCT_VIEW` → Facebook `ViewContent`
+- `ADD_TO_CART` → Facebook `AddToCart`
+- `SEARCH` → Facebook `Search`
+
+### Event ID Generation
+
+Events automatically receive unique IDs for deduplication:
+
+```tsx
+// Automatic ID generation
+publishEvent({
+  type: EventType.ADD_TO_CART,
+  productId: "123",
+  // eventId is automatically generated if not provided
+});
+
+// Manual ID specification
+publishEvent({
+  type: EventType.ADD_TO_CART,
+  productId: "123",
+  eventId: "custom_event_id_123", // Custom event ID
+});
+```
+
+### Browser Information Collection
+
+The system automatically collects browser information for enhanced server-side matching:
+
+- Client user agent
+- Facebook click ID (fbc) from URL parameters or cookies
+- Facebook browser ID (fbp) from cookies
+- Client IP address (server-side)
+
+### Testing
+
+Use the test event code for development:
+
+```bash
+FACEBOOK_TEST_EVENT_CODE="TEST12345"
+```
+
+This allows you to test CAPI events without affecting production data.
+
+##  Professional Logging System
 
 The analytics package includes a comprehensive logging system built on [Pino](https://github.com/pinojs/pino), a high-performance JSON logger for Node.js and browsers.
 

package/dist/adapters/index.d.mts

@@ -1,4 +1,4 @@
-export { B as BaseAdapter, d as GoogleAdapter, G as GoogleAdapterConfig, i as KwikCheckoutAdapter, b as KwikCheckoutConfig, h as KwikPassAdapter, K as KwikPassConfig, e as MoengageAdapter, M as MoengageAdapterConfig, c as PixelAdapter, P as PixelAdapterConfig, f as PostHogAdapter, a as PostHogAdapterConfig, g as ShopifyAdapter, S as ShopifyAdapterConfig } from '../index-GODWc1s6.mjs';
+export { B as BaseAdapter, d as GoogleAdapter, G as GoogleAdapterConfig, i as KwikCheckoutAdapter, b as KwikCheckoutConfig, h as KwikPassAdapter, K as KwikPassConfig, e as MoengageAdapter, M as MoengageAdapterConfig, c as PixelAdapter, P as PixelAdapterConfig, f as PostHogAdapter, a as PostHogAdapterConfig, g as ShopifyAdapter, S as ShopifyAdapterConfig } from '../index-Bym1_EAp.mjs';
 import '../types.mjs';
-import '../subscriber-sWesj_5p.mjs';
+import '../subscriber-BoyOlh9t.mjs';
 import '@shopify/hydrogen-react';

package/dist/adapters/index.d.ts

@@ -1,4 +1,4 @@
-export { B as BaseAdapter, d as GoogleAdapter, G as GoogleAdapterConfig, i as KwikCheckoutAdapter, b as KwikCheckoutConfig, h as KwikPassAdapter, K as KwikPassConfig, e as MoengageAdapter, M as MoengageAdapterConfig, c as PixelAdapter, P as PixelAdapterConfig, f as PostHogAdapter, a as PostHogAdapterConfig, g as ShopifyAdapter, S as ShopifyAdapterConfig } from '../index-BnNRgdUv.js';
+export { B as BaseAdapter, d as GoogleAdapter, G as GoogleAdapterConfig, i as KwikCheckoutAdapter, b as KwikCheckoutConfig, h as KwikPassAdapter, K as KwikPassConfig, e as MoengageAdapter, M as MoengageAdapterConfig, c as PixelAdapter, P as PixelAdapterConfig, f as PostHogAdapter, a as PostHogAdapterConfig, g as ShopifyAdapter, S as ShopifyAdapterConfig } from '../index-DS9OI5Mz.js';
 import '../types.js';
-import '../subscriber-43gnCKWe.js';
+import '../subscriber-BDAm_BAi.js';
 import '@shopify/hydrogen-react';