@behindthescenes/analytics 0.0.9 → 0.0.11

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "@behindthescenes/analytics",
-  "version": "0.0.9",
-  "generatedAt": "2026-04-30T04:20:35.752Z",
+  "version": "0.0.11",
+  "generatedAt": "2026-04-30T04:31:52.621Z",
   "artifacts": {
     "browser": "browser/browser.js",
     "cjs": "cjs/index.js",

package/docs/advanced-setup.md

@@ -0,0 +1,499 @@
+# Advanced Setup Guide
+
+Advanced configuration and use cases for the BTS Analytics SDK.
+
+## Table of Contents
+
+- [Custom Endpoint](#custom-endpoint)
+- [Request Signing](#request-signing)
+- [Google Analytics Integration](#google-analytics-integration)
+- [Attribution Control](#attribution-control)
+- [SPA Configuration](#spa-configuration)
+- [Custom Auto-Tracking](#custom-auto-tracking)
+- [Error Handling](#error-handling)
+- [Performance Optimization](#performance-optimization)
+- [Privacy and Compliance](#privacy-and-compliance)
+
+---
+
+## Custom Endpoint
+
+Override the default analytics endpoint for local development or custom proxies.
+
+```typescript
+const analytics = createBTSAnalytics({
+  siteKey: "your-public-site-key",
+  endpoint: "https://your-proxy.com/v2/website/analytics",
+});
+```
+
+**Note:** Production use should use the default endpoint. Only override for specific development or proxy scenarios.
+
+---
+
+## Request Signing
+
+Add custom headers for request validation and security.
+
+### Basic Header Addition
+
+```typescript
+const analytics = createBTSAnalytics({
+  siteKey: "your-public-site-key",
+  requestHeaders: {
+    "X-Custom-Header": "value",
+    "X-Source": "my-website",
+  },
+});
+```
+
+**Important:** When `requestHeaders` is configured, the SDK uses `fetch(..., { keepalive: true })` instead of `sendBeacon` for page-unload events.
+
+---
+
+## Google Analytics Integration
+
+### Detection Mode (Default)
+
+The SDK automatically detects existing GA4 installations:
+
+```typescript
+const analytics = createBTSAnalytics({
+  siteKey: "your-public-site-key",
+  // GA detection is automatic, no configuration needed
+});
+```
+
+Detected GA data is included with every event:
+
+```json
+{
+  "ga_client_id": "123456789.987654321",
+  "ga_tag_installed": true,
+  "googleAnalytics": {
+    "tagInstalled": true,
+    "clientId": "123456789.987654321",
+    "measurementId": "G-ABC123"
+  }
+}
+```
+
+### Proxy Mode
+
+Load GA tag for scanner visibility while forwarding events through BTS:
+
+```typescript
+const analytics = createBTSAnalytics({
+  siteKey: "your-public-site-key",
+  googleAnalytics: {
+    loadTag: true,
+    measurementId: "G-XXXXXXXXXX",
+  },
+});
+```
+
+This:
+1. Loads the Google tag script with `send_page_view: false`
+2. Allows GA scanners to detect an installed tag
+3. Forwards all events server-side through BTS
+
+### Disable GA Detection
+
+```typescript
+const analytics = createBTSAnalytics({
+  siteKey: "your-public-site-key",
+  googleAnalytics: false,
+});
+```
+
+---
+
+## Attribution Control
+
+### Understanding Attribution
+
+The SDK automatically captures and persists:
+
+**UTM Parameters:**
+- `utm_source`, `utm_medium`, `utm_campaign`
+- `utm_term`, `utm_content`
+
+**Click IDs:**
+- `fbclid`, `gclid`, `gbraid`, `wbraid`
+- `li_fat_id`, `msclkid`, `ttclid`
+
+**Cookies:**
+- `_fbp`, `_fbc`
+
+### Attribution Data Structure
+
+Attribution data is automatically attached to every event:
+
+```json
+{
+  "attribution": {
+    "utm": {
+      "utm_source": "facebook",
+      "utm_medium": "paid",
+      "utm_campaign": "summer_sale"
+    },
+    "clickIds": {
+      "fbclid": "abc123",
+      "fbp": "fb.1.1234567890.987654321"
+    },
+    "landingUrl": "https://yoursite.com/landing?utm_source=facebook",
+    "referrer": "https://facebook.com"
+  }
+}
+```
+
+### Custom Attribution
+
+Add custom attribution data to specific events:
+
+```typescript
+analytics.track("custom_campaign_click", {
+  attribution: {
+    utm: {
+      utm_source: "newsletter",
+      utm_medium: "email",
+    },
+    customCampaignId: "campaign_123",
+  },
+});
+```
+
+---
+
+## SPA Configuration
+
+### React Router / Vue Router / etc.
+
+For frameworks with client-side routing, disable automatic pageviews and handle manually:
+
+```typescript
+const analytics = createBTSAnalytics({
+  siteKey: "your-public-site-key",
+  autoPageviews: false,
+});
+```
+
+#### React Router v6
+
+```tsx
+import { useEffect } from "react";
+import { useLocation } from "react-router-dom";
+
+function AnalyticsRouteTracker() {
+  const location = useLocation();
+
+  useEffect(() => {
+    analytics.page(location.pathname + location.search);
+  }, [location]);
+
+  return null;
+}
+```
+
+#### Vue Router
+
+```typescript
+import { watch } from "vue";
+import { useRoute } from "vue-router";
+
+const route = useRoute();
+
+watch(
+  () => route.fullPath,
+  (fullPath) => {
+    analytics.page(fullPath);
+  },
+  { immediate: true }
+);
+```
+
+### Selective Auto-Tracking
+
+Enable only specific auto-tracking features:
+
+```typescript
+const analytics = createBTSAnalytics({
+  siteKey: "your-public-site-key",
+  autoTrack: {
+    pageviews: false,        // Disable - handle manually
+    history: false,          // Disable SPA hooks
+    outboundLinks: true,     // Enable external link tracking
+    buttonClicks: true,      // Enable button tracking
+    formSubmissions: true,   // Enable form tracking
+    search: true,            // Enable search tracking
+    viewContent: true,       // Enable content view tracking
+  },
+});
+```
+
+---
+
+## Custom Auto-Tracking
+
+### Track Specific Elements Only
+
+Use CSS selectors or data attributes for precise tracking:
+
+```typescript
+// Track only specific buttons
+analytics.track("cta_clicked", {
+  buttonId: "buy-now",
+  section: "pricing",
+});
+
+// Track with custom attributes
+document.querySelectorAll("[data-track-custom]").forEach((el) => {
+  el.addEventListener("click", () => {
+    const eventName = el.getAttribute("data-track-custom");
+    analytics.track(eventName, {
+      elementId: el.id,
+      context: el.getAttribute("data-context"),
+    });
+  });
+});
+```
+
+### Dynamic Content Views
+
+For dynamically loaded content (infinite scroll, etc.):
+
+```typescript
+// The SDK automatically observes DOM changes via MutationObserver
+// Just add the data attribute to new elements:
+const newCard = document.createElement("article");
+newCard.setAttribute("data-bts-view-content", `video_${videoId}`);
+newCard.setAttribute("data-bts-content-type", "video");
+newCard.setAttribute("data-bts-content-title", videoTitle);
+container.appendChild(newCard);
+// SDK will automatically start tracking visibility
+```
+
+---
+
+## Error Handling
+
+### Request Errors
+
+The SDK automatically handles network errors:
+
+1. Failed batches are requeued
+2. Retry is scheduled
+3. Events are preserved in memory
+
+### Custom Error Handling
+
+```typescript
+// For contact form submissions
+try {
+  await analytics.submitContactForm({
+    locationId: "loc-123",
+    email: "fan@example.com",
+  });
+} catch (error) {
+  console.error("Form submission failed:", error);
+  // Show user-friendly error message
+}
+
+// For journey operations
+try {
+  const { journeyToken } = await analytics.startFunnel();
+} catch (error) {
+  console.error("Failed to start funnel:", error);
+  // Continue without attribution
+}
+```
+
+### Debug Mode
+
+Enable debug logging to troubleshoot:
+
+```typescript
+const analytics = createBTSAnalytics({
+  siteKey: "your-public-site-key",
+  debug: true, // Logs all events and network requests
+});
+```
+
+---
+
+## Performance Optimization
+
+### Batch Size
+
+Events are batched automatically (flush every 300ms or 50 events). For high-traffic sites:
+
+```typescript
+const analytics = createBTSAnalytics({
+  siteKey: "your-public-site-key",
+  flushIntervalMs: 500, // Increase interval for more batching
+});
+```
+
+### Lazy Loading
+
+Load the SDK only when needed:
+
+```typescript
+// Dynamic import for code splitting
+async function initAnalytics() {
+  const { createBTSAnalytics } = await import("@behindthescenes/analytics");
+  return createBTSAnalytics({
+    siteKey: "your-public-site-key",
+  });
+}
+```
+
+### Conditional Tracking
+
+Skip tracking for bots or specific conditions:
+
+```typescript
+const isBot = /bot|crawler|spider/i.test(navigator.userAgent);
+const isPrerender = navigator.userAgent.includes("Prerender");
+
+if (!isBot && !isPrerender) {
+  const analytics = createBTSAnalytics({
+    siteKey: "your-public-site-key",
+  });
+}
+```
+
+---
+
+## Privacy and Compliance
+
+### GDPR / CCPA Compliance
+
+The SDK respects user privacy preferences:
+
+```typescript
+// Check for consent before initializing
+const hasConsent = localStorage.getItem("analytics_consent") === "true";
+
+if (hasConsent) {
+  const analytics = createBTSAnalytics({
+    siteKey: "your-public-site-key",
+  });
+} else {
+  // Load with minimal tracking or don't load at all
+  const analytics = createBTSAnalytics({
+    siteKey: "your-public-site-key",
+    autoTrack: false, // Disable all auto-tracking
+  });
+}
+```
+
+### Consent Management
+
+Integrate with your consent management platform:
+
+```typescript
+// Example: OneTrust integration
+function onConsentChange(consent) {
+  if (consent.analytics) {
+    // Initialize or re-enable analytics
+    window.analytics = createBTSAnalytics({
+      siteKey: "your-public-site-key",
+    });
+  } else {
+    // Destroy analytics instance
+    window.analytics?.destroy();
+    window.analytics = null;
+  }
+}
+```
+
+### Data Minimization
+
+Send only necessary data:
+
+```typescript
+analytics.track("purchase", {
+  orderId: "order_123",
+  monetaryValue: 99,
+  currency: "USD",
+  // Don't include: user email, full name, address, etc.
+});
+```
+
+### PII Handling
+
+Never send personally identifiable information in tracking calls:
+
+```typescript
+// ❌ Bad - includes PII
+analytics.track("form_submit", {
+  email: "john@example.com",
+  phone: "+1234567890",
+});
+
+// ✅ Good - use userId only
+analytics.identify("user_123", {
+  // Optional traits - keep minimal
+  plan: "pro",
+  country: "US",
+});
+```
+
+---
+
+## Best Practices
+
+### 1. Initialize Once
+
+Create a singleton instance and reuse:
+
+```typescript
+// analytics.ts
+import { createBTSAnalytics } from "@behindthescenes/analytics";
+
+export const analytics = createBTSAnalytics({
+  siteKey: "your-public-site-key",
+});
+```
+
+### 2. Handle Navigation Properly
+
+For SPAs, always track route changes:
+
+```typescript
+// In your router
+router.afterEach((to) => {
+  analytics.page(to.fullPath);
+});
+```
+
+### 3. Test Your Implementation
+
+```typescript
+// Development testing
+if (process.env.NODE_ENV === "development") {
+  window.testAnalytics = () => {
+    analytics.track("test_event", { timestamp: Date.now() });
+    analytics.flushNow();
+    console.log("Test event sent - check the network tab");
+  };
+}
+```
+
+### 4. Monitor Event Volume
+
+Track your event volume to avoid unexpected costs:
+
+```typescript
+let eventCount = 0;
+
+const originalTrack = analytics.track.bind(analytics);
+analytics.track = (...args) => {
+  eventCount++;
+  if (eventCount % 100 === 0) {
+    console.log(`Analytics events this session: ${eventCount}`);
+  }
+  return originalTrack(...args);
+};
+```