@behindthescenes/analytics 0.0.9 → 0.0.10

package/docs/frameworks.md

@@ -0,0 +1,936 @@
+# Framework Setup Guide
+
+This guide covers setting up the BTS Analytics SDK in popular frontend frameworks.
+
+## Table of Contents
+
+- [Plain JavaScript / HTML](#plain-javascript--html)
+- [React](#react)
+- [Next.js](#nextjs)
+- [Remix](#remix)
+- [Vue](#vue)
+- [Svelte](#svelte)
+- [Angular](#angular)
+- [SolidJS](#solidjs)
+
+---
+
+## Plain JavaScript / HTML
+
+The simplest way to get started - no build tools required.
+
+### Browser Bundle (CDN)
+
+```html
+<script async src="https://api.bts.it.com/v2/website/analytics/sdk/analytics/latest/browser/browser.js"></script>
+<script>
+  window.btsDataLayer = window.btsDataLayer || [];
+  function bts(){window.btsDataLayer.push(arguments);}
+  bts("js", new Date());
+  bts("config", "your-public-site-key", {
+    autoPageviews: true
+  });
+</script>
+```
+
+### ES Module Import
+
+```html
+<script type="module">
+  import { createBTSAnalytics } from "https://app.behindthescenes.com/sdk/analytics/latest/browser/browser.js";
+
+  window.btsAnalytics = createBTSAnalytics({
+    siteKey: "your-public-site-key"
+  });
+</script>
+```
+
+### Usage Examples
+
+```javascript
+// Track a custom event
+document.querySelector("#watch-preview")?.addEventListener("click", () => {
+  window.btsAnalytics.track("watch_preview_clicked", {
+    placement: "hero",
+    contentId: "intro-preview",
+  });
+});
+
+// Track a standard conversion
+window.btsAnalytics.trackStandard("lead", {
+  formId: "newsletter",
+  placement: "footer",
+});
+
+// Identify a visitor
+window.btsAnalytics.identify("user_123", {
+  email: "fan@example.com",
+  plan: "pro",
+});
+
+// Track page views manually
+window.btsAnalytics.page("/pricing");
+
+// Start a funnel and decorate links
+async function goToCheckout() {
+  const { journeyToken } = await window.btsAnalytics.startFunnel("/landing");
+  const checkoutUrl = window.btsAnalytics.decorateUrl(
+    "https://behindthescenes.com/checkout/your-offer",
+    journeyToken,
+  );
+  window.location.assign(checkoutUrl);
+}
+
+// Flush before redirecting
+async function trackAndRedirect() {
+  window.btsAnalytics.track("checkout_cta_clicked", {
+    placement: "hero",
+  });
+  await window.btsAnalytics.flushNow();
+  window.location.assign("/checkout");
+}
+```
+
+---
+
+## React
+
+### Setup: Provider Pattern
+
+Create `BTSAnalyticsProvider.tsx`:
+
+```tsx
+import {
+  BTSAnalytics,
+  createBTSAnalytics,
+} from "@behindthescenes/analytics";
+import {
+  createContext,
+  PropsWithChildren,
+  useContext,
+  useMemo,
+} from "react";
+
+const BTSAnalyticsContext = createContext<BTSAnalytics | null>(null);
+
+export function BTSAnalyticsProvider({ children }: PropsWithChildren) {
+  const analytics = useMemo(
+    () =>
+      createBTSAnalytics({
+        siteKey: "your-public-site-key",
+        autoPageviews: true,
+      }),
+    [],
+  );
+
+  return (
+    <BTSAnalyticsContext.Provider value={analytics}>
+      {children}
+    </BTSAnalyticsContext.Provider>
+  );
+}
+
+export function useBTSAnalytics() {
+  const analytics = useContext(BTSAnalyticsContext);
+  if (!analytics) {
+    throw new Error("useBTSAnalytics must be used inside BTSAnalyticsProvider");
+  }
+  return analytics;
+}
+```
+
+Wrap your app:
+
+```tsx
+import { BTSAnalyticsProvider } from "./BTSAnalyticsProvider";
+
+function App() {
+  return (
+    <BTSAnalyticsProvider>
+      <YourApp />
+    </BTSAnalyticsProvider>
+  );
+}
+```
+
+### Usage Examples
+
+```tsx
+import { useBTSAnalytics } from "./BTSAnalyticsProvider";
+
+// Track a custom event
+function TrackEventExample() {
+  const analytics = useBTSAnalytics();
+
+  function trackPreviewClick() {
+    analytics.track("watch_preview_clicked", {
+      placement: "hero",
+      contentId: "intro-preview",
+    });
+  }
+
+  return <button onClick={trackPreviewClick}>Watch Preview</button>;
+}
+
+// Track a standard conversion
+function LeadEventExample() {
+  const analytics = useBTSAnalytics();
+
+  function trackLead() {
+    analytics.trackStandard("lead", {
+      formId: "newsletter",
+      placement: "footer",
+    });
+  }
+
+  return <button onClick={trackLead}>Subscribe</button>;
+}
+
+// Identify a visitor
+function IdentifyExample() {
+  const analytics = useBTSAnalytics();
+
+  function identifyUser() {
+    analytics.identify("user_123", {
+      email: "fan@example.com",
+      plan: "pro",
+    });
+  }
+
+  return <button onClick={identifyUser}>Sign In</button>;
+}
+
+// Track page views manually
+function ManualPageView() {
+  const analytics = useBTSAnalytics();
+
+  function trackCurrentPage() {
+    analytics.page(window.location.pathname + window.location.search);
+  }
+
+  return <button onClick={trackCurrentPage}>Track Page</button>;
+}
+
+// Start a funnel and decorate links
+function JourneyExample() {
+  const analytics = useBTSAnalytics();
+
+  async function goToCheckout() {
+    const { journeyToken } = await analytics.startFunnel("/landing");
+    const checkoutUrl = analytics.decorateUrl(
+      "https://behindthescenes.com/checkout/your-offer",
+      journeyToken,
+    );
+    window.location.assign(checkoutUrl);
+  }
+
+  return <button onClick={goToCheckout}>Checkout</button>;
+}
+
+// Flush before redirecting
+function FlushExample() {
+  const analytics = useBTSAnalytics();
+
+  async function trackAndRedirect() {
+    analytics.track("checkout_cta_clicked", {
+      placement: "hero",
+    });
+    await analytics.flushNow();
+    window.location.assign("/checkout");
+  }
+
+  return <button onClick={trackAndRedirect}>Go to Checkout</button>;
+}
+```
+
+---
+
+## Next.js
+
+### Setup: App Router
+
+Create `app/providers.tsx`:
+
+```tsx
+"use client";
+
+import {
+  BTSAnalytics,
+  createBTSAnalytics,
+} from "@behindthescenes/analytics";
+import {
+  createContext,
+  PropsWithChildren,
+  useContext,
+  useMemo,
+} from "react";
+
+const BTSAnalyticsContext = createContext<BTSAnalytics | null>(null);
+
+export function Providers({ children }: PropsWithChildren) {
+  const analytics = useMemo(
+    () =>
+      createBTSAnalytics({
+        siteKey: "your-public-site-key",
+        autoPageviews: true,
+      }),
+    [],
+  );
+
+  return (
+    <BTSAnalyticsContext.Provider value={analytics}>
+      {children}
+    </BTSAnalyticsContext.Provider>
+  );
+}
+
+export function useBTSAnalytics() {
+  const analytics = useContext(BTSAnalyticsContext);
+  if (!analytics) {
+    throw new Error("useBTSAnalytics must be used inside Providers");
+  }
+  return analytics;
+}
+```
+
+Update `app/layout.tsx`:
+
+```tsx
+import { Providers } from "./providers";
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+```
+
+### Setup: Pages Router
+
+Create a custom `_app.tsx`:
+
+```tsx
+import type { AppProps } from "next/app";
+import { BTSAnalyticsProvider } from "../components/BTSAnalyticsProvider";
+
+export default function MyApp({ Component, pageProps }: AppProps) {
+  return (
+    <BTSAnalyticsProvider>
+      <Component {...pageProps} />
+    </BTSAnalyticsProvider>
+  );
+}
+```
+
+### Usage Examples
+
+Same as the React examples above, using `useBTSAnalytics()` from `@/app/providers`.
+
+---
+
+## Remix
+
+### Setup: Root Provider
+
+Update `app/root.tsx`:
+
+```tsx
+import { createBTSAnalytics } from "@behindthescenes/analytics";
+import { useEffect, useMemo } from "react";
+import { Outlet, useLocation } from "react-router";
+
+// Create singleton instance
+const analytics = createBTSAnalytics({
+  siteKey: "your-public-site-key",
+  autoPageviews: false, // Handle manually for Remix
+});
+
+export function Layout() {
+  const location = useLocation();
+  const path = useMemo(
+    () => location.pathname + location.search,
+    [location.pathname, location.search],
+  );
+
+  useEffect(() => {
+    analytics.page(path);
+  }, [path]);
+
+  return <Outlet />;
+}
+
+export { analytics };
+```
+
+### Usage Examples
+
+```tsx
+import { analytics } from "~/root";
+
+// Track a custom event
+export function TrackEventExample() {
+  function trackPreviewClick() {
+    analytics.track("watch_preview_clicked", {
+      placement: "hero",
+      contentId: "intro-preview",
+    });
+  }
+
+  return <button onClick={trackPreviewClick}>Watch Preview</button>;
+}
+
+// Track a standard conversion
+export function LeadEventExample() {
+  function trackLead() {
+    analytics.trackStandard("lead", {
+      formId: "newsletter",
+      placement: "footer",
+    });
+  }
+
+  return <button onClick={trackLead}>Subscribe</button>;
+}
+
+// Identify a visitor
+export function IdentifyExample() {
+  function identifyUser() {
+    analytics.identify("user_123", {
+      email: "fan@example.com",
+      plan: "pro",
+    });
+  }
+
+  return <button onClick={identifyUser}>Sign In</button>;
+}
+
+// Track page views manually
+export function ManualPageView() {
+  function trackCurrentPage() {
+    analytics.page(window.location.pathname + window.location.search);
+  }
+
+  return <button onClick={trackCurrentPage}>Track Page</button>;
+}
+
+// Start a funnel and decorate links
+export function JourneyExample() {
+  async function goToCheckout() {
+    const { journeyToken } = await analytics.startFunnel("/landing");
+    const checkoutUrl = analytics.decorateUrl(
+      "https://behindthescenes.com/checkout/your-offer",
+      journeyToken,
+    );
+    window.location.assign(checkoutUrl);
+  }
+
+  return <button onClick={goToCheckout}>Checkout</button>;
+}
+
+// Flush before redirecting
+export function FlushExample() {
+  async function trackAndRedirect() {
+    analytics.track("checkout_cta_clicked", {
+      placement: "hero",
+    });
+    await analytics.flushNow();
+    window.location.assign("/checkout");
+  }
+
+  return <button onClick={trackAndRedirect}>Go to Checkout</button>;
+}
+```
+
+---
+
+## Vue
+
+### Setup: Plugin Pattern
+
+Create `src/plugins/bts-analytics.ts`:
+
+```typescript
+import { createBTSAnalytics } from "@behindthescenes/analytics";
+import type { App } from "vue";
+
+const analytics = createBTSAnalytics({
+  siteKey: "your-public-site-key",
+  autoPageviews: true,
+});
+
+export function installBTSAnalytics(app: App) {
+  app.provide("btsAnalytics", analytics);
+}
+
+export { analytics };
+```
+
+Register in `main.ts`:
+
+```typescript
+import { createApp } from "vue";
+import App from "./App.vue";
+import { installBTSAnalytics } from "./plugins/bts-analytics";
+
+const app = createApp(App);
+app.use(installBTSAnalytics);
+app.mount("#app");
+```
+
+### Composable
+
+Create `src/composables/useAnalytics.ts`:
+
+```typescript
+import { inject } from "vue";
+import type { BTSAnalytics } from "@behindthescenes/analytics";
+
+export function useAnalytics(): BTSAnalytics {
+  const analytics = inject<BTSAnalytics>("btsAnalytics");
+  if (!analytics) {
+    throw new Error("useAnalytics must be called inside a Vue app with BTS Analytics installed");
+  }
+  return analytics;
+}
+```
+
+### Usage Examples
+
+```vue
+<script setup lang="ts">
+import { useAnalytics } from "@/composables/useAnalytics";
+
+const analytics = useAnalytics();
+
+// Track a custom event
+function trackPreviewClick() {
+  analytics.track("watch_preview_clicked", {
+    placement: "hero",
+    contentId: "intro-preview",
+  });
+}
+
+// Track a standard conversion
+function trackLead() {
+  analytics.trackStandard("lead", {
+    formId: "newsletter",
+    placement: "footer",
+  });
+}
+
+// Identify a visitor
+function identifyUser() {
+  analytics.identify("user_123", {
+    email: "fan@example.com",
+    plan: "pro",
+  });
+}
+
+// Track page views manually
+function trackCurrentPage() {
+  analytics.page(window.location.pathname + window.location.search);
+}
+
+// Start a funnel and decorate links
+async function goToCheckout() {
+  const { journeyToken } = await analytics.startFunnel("/landing");
+  const checkoutUrl = analytics.decorateUrl(
+    "https://behindthescenes.com/checkout/your-offer",
+    journeyToken,
+  );
+  window.location.assign(checkoutUrl);
+}
+
+// Flush before redirecting
+async function trackAndRedirect() {
+  analytics.track("checkout_cta_clicked", {
+    placement: "hero",
+  });
+  await analytics.flushNow();
+  window.location.assign("/checkout");
+}
+</script>
+
+<template>
+  <button @click="trackPreviewClick">Watch Preview</button>
+  <button @click="trackLead">Subscribe</button>
+  <button @click="identifyUser">Sign In</button>
+  <button @click="trackCurrentPage">Track Page</button>
+  <button @click="goToCheckout">Checkout</button>
+  <button @click="trackAndRedirect">Go to Checkout</button>
+</template>
+```
+
+---
+
+## Svelte
+
+### Setup: Store Pattern
+
+Create `src/lib/analytics.ts`:
+
+```typescript
+import { createBTSAnalytics } from "@behindthescenes/analytics";
+
+export const analytics = createBTSAnalytics({
+  siteKey: "your-public-site-key",
+  autoPageviews: true,
+});
+```
+
+### Usage in Components
+
+```svelte
+<script lang="ts">
+  import { analytics } from "$lib/analytics";
+
+  // Track a custom event
+  function trackPreviewClick() {
+    analytics.track("watch_preview_clicked", {
+      placement: "hero",
+      contentId: "intro-preview",
+    });
+  }
+
+  // Track a standard conversion
+  function trackLead() {
+    analytics.trackStandard("lead", {
+      formId: "newsletter",
+      placement: "footer",
+    });
+  }
+
+  // Identify a visitor
+  function identifyUser() {
+    analytics.identify("user_123", {
+      email: "fan@example.com",
+      plan: "pro",
+    });
+  }
+
+  // Start a funnel and decorate links
+  async function goToCheckout() {
+    const { journeyToken } = await analytics.startFunnel("/landing");
+    const checkoutUrl = analytics.decorateUrl(
+      "https://behindthescenes.com/checkout/your-offer",
+      journeyToken,
+    );
+    window.location.assign(checkoutUrl);
+  }
+
+  // Flush before redirecting
+  async function trackAndRedirect() {
+    analytics.track("checkout_cta_clicked", {
+      placement: "hero",
+    });
+    await analytics.flushNow();
+    window.location.assign("/checkout");
+  }
+</script>
+
+<button on:click={trackPreviewClick}>Watch Preview</button>
+<button on:click={trackLead}>Subscribe</button>
+<button on:click={identifyUser}>Sign In</button>
+<button on:click={goToCheckout}>Checkout</button>
+<button on:click={trackAndRedirect}>Go to Checkout</button>
+```
+
+### SvelteKit Setup
+
+For SvelteKit with SSR, create a client-side only module:
+
+```typescript
+// src/lib/analytics.client.ts
+import { browser } from "$app/environment";
+import { createBTSAnalytics } from "@behindthescenes/analytics";
+
+export const analytics = browser
+  ? createBTSAnalytics({
+      siteKey: "your-public-site-key",
+      autoPageviews: true,
+    })
+  : null;
+```
+
+Use in components:
+
+```svelte
+<script lang="ts">
+  import { analytics } from "$lib/analytics.client";
+
+  function trackEvent() {
+    analytics?.track("button_clicked", { buttonId: "cta" });
+  }
+</script>
+```
+
+---
+
+## Angular
+
+### Setup: Service Pattern
+
+Create `src/app/services/bts-analytics.service.ts`:
+
+```typescript
+import { Injectable } from "@angular/core";
+import { createBTSAnalytics, BTSAnalytics } from "@behindthescenes/analytics";
+
+@Injectable({
+  providedIn: "root",
+})
+export class BTSAnalyticsService {
+  private analytics: BTSAnalytics;
+
+  constructor() {
+    this.analytics = createBTSAnalytics({
+      siteKey: "your-public-site-key",
+      autoPageviews: true,
+    });
+  }
+
+  track(eventName: string, properties?: Record<string, unknown>) {
+    this.analytics.track(eventName, properties);
+  }
+
+  trackStandard(eventName: string, properties?: Record<string, unknown>) {
+    this.analytics.trackStandard(eventName as any, properties);
+  }
+
+  identify(userId: string, traits?: Record<string, unknown>) {
+    this.analytics.identify(userId, traits);
+  }
+
+  page(path?: string) {
+    this.analytics.page(path);
+  }
+
+  async startFunnel(entryPath?: string) {
+    return this.analytics.startFunnel(entryPath);
+  }
+
+  decorateUrl(url: string, journeyToken?: string) {
+    return this.analytics.decorateUrl(url, journeyToken);
+  }
+
+  async flushNow() {
+    return this.analytics.flushNow();
+  }
+}
+```
+
+### Usage in Components
+
+```typescript
+import { Component } from "@angular/core";
+import { BTSAnalyticsService } from "./services/bts-analytics.service";
+
+@Component({
+  selector: "app-example",
+  template: `
+    <button (click)="trackPreviewClick()">Watch Preview</button>
+    <button (click)="trackLead()">Subscribe</button>
+    <button (click)="identifyUser()">Sign In</button>
+    <button (click)="goToCheckout()">Checkout</button>
+  `,
+})
+export class ExampleComponent {
+  constructor(private analytics: BTSAnalyticsService) {}
+
+  trackPreviewClick() {
+    this.analytics.track("watch_preview_clicked", {
+      placement: "hero",
+      contentId: "intro-preview",
+    });
+  }
+
+  trackLead() {
+    this.analytics.trackStandard("lead", {
+      formId: "newsletter",
+      placement: "footer",
+    });
+  }
+
+  identifyUser() {
+    this.analytics.identify("user_123", {
+      email: "fan@example.com",
+      plan: "pro",
+    });
+  }
+
+  async goToCheckout() {
+    const { journeyToken } = await this.analytics.startFunnel("/landing");
+    const checkoutUrl = this.analytics.decorateUrl(
+      "https://behindthescenes.com/checkout/your-offer",
+      journeyToken,
+    );
+    window.location.assign(checkoutUrl);
+  }
+}
+```
+
+---
+
+## SolidJS
+
+### Setup: Context Pattern
+
+Create `src/context/BTSAnalyticsContext.tsx`:
+
+```tsx
+import { createBTSAnalytics, BTSAnalytics } from "@behindthescenes/analytics";
+import { createContext, useContext, ParentComponent } from "solid-js";
+
+const BTSAnalyticsContext = createContext<BTSAnalytics>();
+
+export const BTSAnalyticsProvider: ParentComponent = (props) => {
+  const analytics = createBTSAnalytics({
+    siteKey: "your-public-site-key",
+    autoPageviews: true,
+  });
+
+  return (
+    <BTSAnalyticsContext.Provider value={analytics}>
+      {props.children}
+    </BTSAnalyticsContext.Provider>
+  );
+};
+
+export function useBTSAnalytics() {
+  const analytics = useContext(BTSAnalyticsContext);
+  if (!analytics) {
+    throw new Error("useBTSAnalytics must be used inside BTSAnalyticsProvider");
+  }
+  return analytics;
+}
+```
+
+### Usage in Components
+
+```tsx
+import { useBTSAnalytics } from "../context/BTSAnalyticsContext";
+
+export function TrackEventExample() {
+  const analytics = useBTSAnalytics();
+
+  function trackPreviewClick() {
+    analytics.track("watch_preview_clicked", {
+      placement: "hero",
+      contentId: "intro-preview",
+    });
+  }
+
+  return <button onClick={trackPreviewClick}>Watch Preview</button>;
+}
+
+export function LeadEventExample() {
+  const analytics = useBTSAnalytics();
+
+  function trackLead() {
+    analytics.trackStandard("lead", {
+      formId: "newsletter",
+      placement: "footer",
+    });
+  }
+
+  return <button onClick={trackLead}>Subscribe</button>;
+}
+
+export function IdentifyExample() {
+  const analytics = useBTSAnalytics();
+
+  function identifyUser() {
+    analytics.identify("user_123", {
+      email: "fan@example.com",
+      plan: "pro",
+    });
+  }
+
+  return <button onClick={identifyUser}>Sign In</button>;
+}
+
+export function JourneyExample() {
+  const analytics = useBTSAnalytics();
+
+  async function goToCheckout() {
+    const { journeyToken } = await analytics.startFunnel("/landing");
+    const checkoutUrl = analytics.decorateUrl(
+      "https://behindthescenes.com/checkout/your-offer",
+      journeyToken,
+    );
+    window.location.assign(checkoutUrl);
+  }
+
+  return <button onClick={goToCheckout}>Checkout</button>;
+}
+
+export function FlushExample() {
+  const analytics = useBTSAnalytics();
+
+  async function trackAndRedirect() {
+    analytics.track("checkout_cta_clicked", {
+      placement: "hero",
+    });
+    await analytics.flushNow();
+    window.location.assign("/checkout");
+  }
+
+  return <button onClick={trackAndRedirect}>Go to Checkout</button>;
+}
+```
+
+---
+
+## Server-Side Rendering (SSR) Considerations
+
+When using frameworks with SSR (Next.js, Remix, SvelteKit), keep these points in mind:
+
+### 1. Client-Only Initialization
+
+The SDK requires browser APIs (`window`, `document`, `localStorage`). Always initialize on the client:
+
+```typescript
+// Good
+const analytics = typeof window !== "undefined"
+  ? createBTSAnalytics({ siteKey: "..." })
+  : null;
+
+// Or use framework utilities
+import { browser } from "$app/environment"; // SvelteKit
+```
+
+### 2. Disable Auto-Pageviews for Manual Control
+
+```typescript
+const analytics = createBTSAnalytics({
+  siteKey: "your-public-site-key",
+  autoPageviews: false, // Handle manually for SSR frameworks
+});
+```
+
+### 3. Router Integration
+
+Integrate with your framework's router for accurate page tracking:
+
+- **Next.js**: Use `usePathname()` in a client component
+- **Remix**: Use `useLocation()` in `root.tsx`
+- **SvelteKit**: Use `$page.url` in `+layout.svelte`
+
+### 4. Cleanup on Navigation
+
+The SDK handles most cleanup automatically, but call `destroy()` when unmounting:
+
+```typescript
+import { onCleanup } from "solid-js";
+
+onCleanup(() => {
+  analytics?.destroy();
+});
+```