shopkit-analytics 1.0.2 → 1.0.3

package/README.md

@@ -203,7 +203,7 @@ Track conversions and optimize Facebook ad campaigns with both client-side and s
   config={{
     facebookPixel: {
       pixelId: "123456789",
-      enableCAPI: true, // Enable server-side CAPI backup
+      enableCAPI: true, // Server-side CAPI backup (enabled by default)
       enableDebugLogs: true,
       enableAdvancedMatching: true,
     },
@@ -217,11 +217,12 @@ Track conversions and optimize Facebook ad campaigns with both client-side and s
 - Custom conversions
 
 **Server-Side Tracking (CAPI):**
-- Automatic server-side backup for improved data reliability
-- Event deduplication using unique event IDs
+- **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
 
@@ -405,6 +406,33 @@ NEXT_PUBLIC_STORE_ID="your-store-id"
 
 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
@@ -413,88 +441,14 @@ The Facebook Pixel adapter supports server-side tracking through the Conversions
 - **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
+### Detailed Setup Guide
 
-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 }
-    );
-  }
-}
-```
+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 (matching the PixelAdapter implementation):
+The CAPI service currently supports these events:
 
 - `PAGE_VIEW` → Facebook `PageView`
 - `PRODUCT_VIEW` → Facebook `ViewContent`
@@ -521,25 +475,6 @@ publishEvent({
 });
 ```
 
-### 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,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-Bym1_EAp.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-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-DS9OI5Mz.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-BDAm_BAi.js';
+import '../types-C__2IBCj.js';
 import '@shopify/hydrogen-react';