shopkit-analytics 1.0.2 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shopkit-analytics",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "A comprehensive analytics package combining event tracking and affiliate tracking for e-commerce applications with multiple platform adapters",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -21,11 +21,26 @@
       "import": "./dist/affiliate/index.mjs",
       "require": "./dist/affiliate/index.js"
     },
+    "./experiment": {
+      "types": "./dist/experiment/index.d.ts",
+      "import": "./dist/experiment/index.mjs",
+      "require": "./dist/experiment/index.js"
+    },
     "./adapters": {
       "types": "./dist/adapters/index.d.ts",
       "import": "./dist/adapters/index.mjs",
       "require": "./dist/adapters/index.js"
     },
+    "./services": {
+      "types": "./dist/services/index.d.ts",
+      "import": "./dist/services/index.mjs",
+      "require": "./dist/services/index.js"
+    },
+    "./utils": {
+      "types": "./dist/utils/index.d.ts",
+      "import": "./dist/utils/index.mjs",
+      "require": "./dist/utils/index.js"
+    },
     "./types": {
       "types": "./dist/types.d.ts",
       "import": "./dist/types.mjs",
@@ -34,6 +49,7 @@
   },
   "files": [
     "dist",
+    "templates",
     "README.md",
     "LICENSE"
   ],
@@ -55,6 +71,8 @@
     "tracking",
     "events",
     "affiliate",
+    "experiment",
+    "ab-testing",
     "utm",
     "google-analytics",
     "facebook-pixel",

package/templates/nextjs/README.md

@@ -0,0 +1,206 @@
+# Facebook CAPI Setup Guide for Next.js
+
+This guide helps you set up Facebook Conversions API (CAPI) server-side tracking with the @shopkit/analytics package.
+
+## Quick Setup
+
+### 1. Environment Variables
+
+Add these to your `.env.local` file:
+
+```bash
+# Required for Facebook CAPI
+FACEBOOK_CAPI_ACCESS_TOKEN="your_facebook_access_token"
+NEXT_PUBLIC_PIXEL_ID="123456789"
+
+# Optional (for testing)
+FACEBOOK_TEST_EVENT_CODE="TEST12345"
+```
+
+### 2. Create API Route
+
+**For Next.js App Router (app directory):**
+
+Create `app/api/events/route.ts` and copy the contents from `api-events-route.ts` in this directory.
+
+**For Next.js Pages Router (pages directory):**
+
+Create `pages/api/events.ts`:
+
+```typescript
+import { createFacebookCAPIService } from "@shopkit/analytics/services";
+import { TEvent } from "@shopkit/analytics/types";
+import type { NextApiRequest, NextApiResponse } from "next";
+
+function getClientIpAddress(req: NextApiRequest): string | undefined {
+  const forwarded = req.headers["x-forwarded-for"];
+  const realIp = req.headers["x-real-ip"];
+  const cfConnectingIp = req.headers["cf-connecting-ip"];
+
+  if (typeof forwarded === "string") {
+    return forwarded.split(",")[0];
+  }
+  if (typeof realIp === "string") {
+    return realIp;
+  }
+  if (typeof cfConnectingIp === "string") {
+    return cfConnectingIp;
+  }
+  return undefined;
+}
+
+export default async function handler(
+  req: NextApiRequest,
+  res: NextApiResponse
+) {
+  if (req.method !== "POST") {
+    return res.status(405).json({ error: "Method not allowed" });
+  }
+
+  try {
+    const { events, userInfo } = req.body;
+
+    if (!Array.isArray(events) || events.length === 0) {
+      return res.status(400).json({ error: "Invalid events data" });
+    }
+
+    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 res.status(500).json({ error: "CAPI service not configured" });
+    }
+
+    const enhancedUserInfo = {
+      ...userInfo,
+      clientIpAddress: getClientIpAddress(req),
+    };
+
+    await capiService.sendEvents(events as TEvent[], enhancedUserInfo);
+
+    return res.json({
+      success: true,
+      message: `Successfully sent ${events.length} events to Facebook CAPI`,
+    });
+  } catch (error) {
+    console.error("API Events Error:", error);
+    return res.status(500).json({ error: "Failed to process events" });
+  }
+}
+```
+
+### 3. CAPI Configuration (Enabled by Default)
+
+```typescript
+import { ShopkitAnalytics } from "@shopkit/analytics";
+
+<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
+    },
+  }}
+>
+  <YourApp />
+</ShopkitAnalytics>
+```
+
+**Important**: CAPI is **enabled by default** to provide better data reliability and privacy compliance. The system will gracefully handle cases where the API endpoint is not set up - client-side tracking will continue to work normally.
+
+## Getting Facebook Access Token
+
+1. Go to [Facebook Business Manager](https://business.facebook.com/)
+2. Navigate to **Business Settings** → **System Users**
+3. Create a new system user or select existing one
+4. Generate an access token with these permissions:
+   - `ads_management`
+   - `business_management`
+5. Copy the access token to your environment variables
+
+## Testing
+
+### Development Testing
+
+1. Set the test event code in your environment:
+   ```bash
+   FACEBOOK_TEST_EVENT_CODE="TEST12345"
+   ```
+
+2. Trigger some events in your app
+
+3. Check Facebook Events Manager → Test Events to see if events are received
+
+### Production Verification
+
+1. Remove or comment out `FACEBOOK_TEST_EVENT_CODE`
+2. Monitor Facebook Events Manager for real events
+3. Check your server logs for any CAPI errors
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"CAPI service not configured"**
+   - Ensure `FACEBOOK_CAPI_ACCESS_TOKEN` and `NEXT_PUBLIC_PIXEL_ID` are set
+   - Verify environment variables are loaded correctly
+
+2. **"Method not allowed" (Pages Router)**
+   - Ensure you're using POST requests
+   - Check the API route is created correctly
+
+3. **Events not appearing in Facebook**
+   - Verify your access token has correct permissions
+   - Check if test event code is set (events go to Test Events tool)
+   - Monitor server logs for error messages
+
+4. **CORS errors**
+   - API route should be on the same domain as your app
+   - Next.js API routes handle CORS automatically
+
+### Debug Logging
+
+Enable debug logging to see detailed information:
+
+```typescript
+<ShopkitAnalytics
+  config={{
+    logger: {
+      enabled: true,
+      level: "debug",
+      prettyPrint: true,
+    },
+    facebookPixel: {
+      pixelId: process.env.NEXT_PUBLIC_PIXEL_ID!,
+      enableCAPI: true,
+    },
+  }}
+/>
+```
+
+## How It Works
+
+1. **Event Triggered**: User performs an action (add to cart, etc.)
+2. **Dual Tracking**: Event sent to both client-side pixel and server-side CAPI (enabled by default)
+3. **Event ID**: Unique ID prevents double counting
+4. **Enhanced Data**: Automatically includes experiment and affiliate data
+5. **Deduplication**: Facebook uses event ID to merge client/server events
+6. **Graceful Fallback**: If API endpoint is missing, only client-side tracking runs (no errors)
+
+### Default Behavior
+
+- **CAPI is enabled by default** for all Facebook Pixel configurations
+- **No setup required** for basic client-side tracking
+- **API endpoint optional** - system works without it (client-side only)
+- **Better data quality** when API endpoint is properly configured
+
+## Support
+
+- Check the main package README for more details
+- Monitor browser console and server logs for errors
+- Use Facebook's Test Events tool during development

package/templates/nextjs/api-events-route.ts

@@ -0,0 +1,62 @@
+import { createFacebookCAPIService } from "@shopkit/analytics/services";
+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 }
+    );
+  }
+}