Sprig Integration for Experiments

.github/workflows/vercel-preview.yaml

@@ -17,5 +17,7 @@ jobs:
         run: vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }}
       - name: Build Project Artifacts
         run: vercel build --token=${{ secrets.VERCEL_TOKEN }}
+        env:
+          NEXT_PUBLIC_SPRIG_ENVIRONMENT_ID: ${{ secrets.SPRIG_ENVIRONMENT_ID }}
       - name: Deploy Project Artifacts to Vercel
         run: vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }}

SPRIG_SETUP.md

@@ -0,0 +1,48 @@
+# Sprig Survey Setup
+
+## Overview
+Sprig surveys are configured to trigger on the experimentation docs page to gather user feedback.
+
+## Setup Instructions
+
+### 1. Environment Variables
+To enable Sprig surveys, you need to set the following environment variable:
+
+```
+NEXT_PUBLIC_SPRIG_ENVIRONMENT_ID=your-sprig-environment-id
+```
+
+### 2. Local Development
+For local development, create a `.env.local` file in the root directory:
+
+```bash
+# .env.local
+NEXT_PUBLIC_SPRIG_ENVIRONMENT_ID=your-sprig-environment-id
+```
+
+### 3. Production Deployment
+For production, set the environment variable in your deployment platform:
+
+- **Vercel**: Add the environment variable in your project settings
+- **GitHub Actions**: Add as a repository secret and reference in your deployment workflow
+- **Other platforms**: Follow your platform's documentation for setting environment variables
+
+### 4. Survey Configuration
+The survey is triggered when users visit the `/docs/experiments` page. The tracking event name is `viewed_experimentation_docs`.
+
+In your Sprig dashboard:
+1. Create a survey
+2. Set up targeting based on the `viewed_experimentation_docs` event
+3. Configure your survey questions and appearance
+
+### 5. Security Notes
+- The environment variable is prefixed with `NEXT_PUBLIC_` because it needs to be available in the browser
+- The Sprig Environment ID is not sensitive like an API key, but should still be managed securely
+- If the environment variable is not set, Sprig will not initialize and no surveys will be shown
+
+## Testing
+To test the integration:
+1. Set up your local environment with the Sprig Environment ID
+2. Navigate to `/docs/experiments`
+3. Check your Sprig dashboard for the tracking event
+4. Verify that surveys are displayed according to your targeting rules

hooks/useSprig.ts

@@ -0,0 +1,99 @@
+import { useEffect } from 'react';
+import { useRouter } from 'next/router';
+
+// Types for Sprig global interface
+declare global {
+  interface Window {
+    Sprig: {
+      (method: string, ...args: any[]): void;
+      appId?: string;
+      _API_URL?: string;
+      _queue?: any[];
+    };
+  }
+}
+
+// Track last event time to prevent duplicates
+let lastEventTime = 0;
+const EVENT_DEBOUNCE_MS = 1000; // 1 second
+
+export const useSprig = () => {
+  const router = useRouter();
+  const sprigEnvironmentId = process.env.NEXT_PUBLIC_SPRIG_ENVIRONMENT_ID;
+
+  // Early return for server-side rendering
+  if (typeof window === 'undefined') {
+    return;
+  }
+
+  // Initialize Sprig script
+  useEffect(() => {
+    if (!sprigEnvironmentId || typeof window === 'undefined') return;
+
+    // Check if Sprig is already initialized
+    if (window.Sprig) return;
+
+    try {
+      // Official Sprig initialization pattern
+      window.Sprig = function(method: string, ...args: any[]) {
+        (window.Sprig._queue = window.Sprig._queue || []).push([method, ...args]);
+      };
+
+      // Configure with environment ID
+      window.Sprig.appId = sprigEnvironmentId;
+      window.Sprig._API_URL = 'https://api.sprig.com';
+
+      // Load the Sprig script
+      const script = document.createElement('script');
+      script.async = true;
+      script.src = 'https://cdn.sprig.com/shim.js';
+
+      script.onerror = () => {
+        console.error('Failed to load Sprig script');
+      };
+
+      document.head.appendChild(script);
+    } catch (error) {
+      console.error('Sprig initialization failed:', error);
+    }
+  }, [sprigEnvironmentId]);
+
+  // Track experimentation page visits
+  useEffect(() => {
+    if (!sprigEnvironmentId || typeof window === 'undefined') return;
+
+    const trackExperimentView = () => {
+      const now = Date.now();
+
+      // Prevent duplicate events within debounce period
+      if (now - lastEventTime < EVENT_DEBOUNCE_MS) {
+        return;
+      }
+
+      if (!window.Sprig) {
+        return;
+      }
+
+      try {
+        lastEventTime = now;
+        window.Sprig('track', 'viewed_experimentation_docs');
+      } catch (error) {
+        console.error('Sprig track failed:', error);
+      }
+    };
+
+    const handleRouteChange = (url: string) => {
+      if (url.includes('/docs/experiments')) {
+        trackExperimentView();
+      }
+    };
+
+    // Track if already on experimentation page
+    if (router.asPath.includes('/docs/experiments')) {
+      trackExperimentView();
+    }
+
+    router.events.on('routeChangeComplete', handleRouteChange);
+    return () => router.events.off('routeChangeComplete', handleRouteChange);
+  }, [router, sprigEnvironmentId]);
+};