shopkit-analytics 1.0.1 → 1.0.3

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, // Server-side CAPI backup (enabled by default)
       enableDebugLogs: true,
       enableAdvancedMatching: true,
     },
@@ -124,6 +216,14 @@ Track conversions and optimize Facebook ad campaigns.
 - InitiateCheckout, Search
 - Custom conversions
 
+**Server-Side Tracking (CAPI):**
+- **Enabled by default** for improved data reliability
+- Automatic server-side backup with event deduplication
+- Enhanced browser fingerprinting for better user matching
+- Fallback mechanism when client-side tracking fails
+- Requires `/api/events` endpoint for server-side processing
+- Set `enableCAPI: false` to disable if not needed
+
 ### 3. MoEngage
 
 Engage users with personalized campaigns and analytics.
@@ -196,7 +296,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 +322,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 +402,80 @@ 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.
+
+### Quick Setup
+
+1. **Set Environment Variables**:
+   ```bash
+   FACEBOOK_CAPI_ACCESS_TOKEN="your_facebook_access_token"
+   NEXT_PUBLIC_PIXEL_ID="123456789"
+   FACEBOOK_TEST_EVENT_CODE="TEST12345" # Optional: for testing
+   ```
+
+2. **Copy API Route Template**:
+   - Find the template in `node_modules/@shopkit/analytics/templates/nextjs/`
+   - Copy `api-events-route.ts` to your `app/api/events/route.ts` (App Router)
+   - Or follow the Pages Router example in the template README
+
+3. **CAPI Configuration** (enabled by default):
+   ```tsx
+   <ShopkitAnalytics
+     config={{
+       facebookPixel: {
+         pixelId: process.env.NEXT_PUBLIC_PIXEL_ID!,
+         // enableCAPI: true, // Default: enabled for better data reliability
+         // enableCAPI: false, // Uncomment to disable server-side tracking
+       },
+     }}
+   />
+   ```
+
+### 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
+
+### Detailed Setup Guide
+
+For complete setup instructions, including troubleshooting and testing, see:
+`node_modules/@shopkit/analytics/templates/nextjs/README.md`
+
+### Supported Events
+
+The CAPI service currently supports these events:
+
+- `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
+});
+```
+
+##  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,5 @@
-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-th6sBtE3.mjs';
 import '../types.mjs';
-import '../subscriber-sWesj_5p.mjs';
+import '../subscriber-BoyOlh9t.mjs';
+import '../types-C__2IBCj.mjs';
 import '@shopify/hydrogen-react';

package/dist/adapters/index.d.ts

@@ -1,4 +1,5 @@
-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-D_8w5bL_.js';
 import '../types.js';
-import '../subscriber-43gnCKWe.js';
+import '../subscriber-BDAm_BAi.js';
+import '../types-C__2IBCj.js';
 import '@shopify/hydrogen-react';