Web SDK

FlowAlive SDK integration guide for vanilla JavaScript, HTML, and web applications.

Installation

FlowAlive Web SDK can be integrated into your web application using script tags. No npm installation required.

Basic Setup

Add the following scripts to your HTML file:

<!-- Configuration Script -->
<script>
  window.FlowAliveConfig = {
    apiKey: "your_api_key_here",
    trackNavigation: true
  };
</script>

<!-- FlowAlive SDK -->
<script src="https://flowalive-sdk.s3.eu-central-1.amazonaws.com/dist/web.global.js"></script>

Next.js Setup

For Next.js applications, use the Script component:

import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {/* Configuration */}
        <Script id="flowalive-setup" strategy="afterInteractive">
          {`
            window.FlowAliveConfig = {
              apiKey: "your_api_key_here",
              trackNavigation: true
            };
          `}
        </Script>

        {/* SDK */}
        <Script
          src="https://flowalive-sdk.s3.eu-central-1.amazonaws.com/dist/web.global.js"
          strategy="lazyOnload"
        />

        {children}
      </body>
    </html>
  );
}

Configuration

Configure FlowAlive by setting window.FlowAliveConfig before loading the SDK script.

Configuration Options

Option	Type	Default	Description
`apiKey`	`string`	Required	Your FlowAlive API key
`trackNavigation`	`boolean`	`false`	Automatically track page navigation
`debug`	`boolean`	`false`	Enable debug logging
`endpoint`	`string`	Default endpoint	Custom API endpoint

Example Configuration

<script>
  window.FlowAliveConfig = {
    apiKey: "flowalive_a030764a-be6e-4261-97bb-13a3ffe7c2ff",
    trackNavigation: true,
    debug: true
  };
</script>

Usage

Once the SDK is loaded, you can access FlowAlive methods through the global window.FlowAlive object.

Track Events

Track custom events throughout your application:

window.FlowAlive.trackEvent({
  name: "button_clicked",
  properties: {
    button_id: "signup_button",
    page: "homepage"
  }
});

Identify Users

Associate events with specific users:

window.FlowAlive.identify({
  userId: "user_12345",
  traits: {
    email: "user@example.com",
    name: "John Doe",
    plan: "premium"
  }
});

Track Page Views

Manually track page views:

window.FlowAlive.trackPageView({
  page: "/products",
  title: "Products Page",
  properties: {
    category: "electronics"
  }
});

Track Sessions

Start and end user sessions:

// Start a session
window.FlowAlive.startSession();

// End a session
window.FlowAlive.endSession();

Set User Properties

Update user properties without triggering an identify event:

window.FlowAlive.setUserProperties({
  subscription_status: "active",
  last_login: new Date().toISOString()
});

Track Errors

Track application errors and exceptions:

window.FlowAlive.trackError({
  error: "Payment failed",
  stack: error.stack,
  properties: {
    payment_method: "credit_card",
    amount: 99.99
  }
});

Reset User

Clear user identification (useful for logout):

window.FlowAlive.reset();

Advanced Usage

Conditional Tracking

Check if FlowAlive is loaded before tracking:

function trackEvent(eventName, properties) {
  if (window.FlowAlive) {
    window.FlowAlive.trackEvent({
      name: eventName,
      properties: properties
    });
  }
}

Event Listeners

Track user interactions automatically:

document.addEventListener('DOMContentLoaded', function() {
  // Track all button clicks
  document.querySelectorAll('button').forEach(button => {
    button.addEventListener('click', function() {
      window.FlowAlive.trackEvent({
        name: 'button_clicked',
        properties: {
          button_text: this.textContent,
          button_id: this.id
        }
      });
    });
  });

  // Track form submissions
  document.querySelectorAll('form').forEach(form => {
    form.addEventListener('submit', function(e) {
      window.FlowAlive.trackEvent({
        name: 'form_submitted',
        properties: {
          form_id: this.id,
          form_action: this.action
        }
      });
    });
  });
});

E-commerce Tracking

Track product views and purchases:

// Track product view
window.FlowAlive.trackEvent({
  name: 'product_viewed',
  properties: {
    product_id: 'prod_123',
    product_name: 'Wireless Headphones',
    price: 99.99,
    currency: 'USD'
  }
});

// Track purchase
window.FlowAlive.trackEvent({
  name: 'purchase_completed',
  properties: {
    order_id: 'order_456',
    total: 199.98,
    currency: 'USD',
    items: [
      { product_id: 'prod_123', quantity: 2, price: 99.99 }
    ]
  }
});

A/B Testing

Track experiment variations:

window.FlowAlive.trackEvent({
  name: 'experiment_viewed',
  properties: {
    experiment_id: 'homepage_test_v1',
    variation: 'variant_b'
  }
});

TypeScript Support

For TypeScript projects, you can add type definitions:

declare global {
  interface Window {
    FlowAlive: {
      trackEvent: (params: { name: string; properties?: Record<string, any> }) => void;
      identify: (params: { userId: string; traits?: Record<string, any> }) => void;
      trackPageView: (params: { page: string; title?: string; properties?: Record<string, any> }) => void;
      startSession: () => void;
      endSession: () => void;
      setUserProperties: (properties: Record<string, any>) => void;
      trackError: (params: { error: string; stack?: string; properties?: Record<string, any> }) => void;
      reset: () => void;
    };
    FlowAliveConfig: {
      apiKey: string;
      trackNavigation?: boolean;
      debug?: boolean;
      endpoint?: string;
    };
  }
}

export {};

Best Practices

1. Load SDK Asynchronously

Always load the SDK asynchronously to avoid blocking page rendering:

<script src="https://flowalive-sdk.s3.eu-central-1.amazonaws.com/dist/web.global.js" async></script>

2. Handle SDK Loading

Wait for SDK to load before tracking:

function waitForFlowAlive(callback) {
  if (window.FlowAlive) {
    callback();
  } else {
    setTimeout(() => waitForFlowAlive(callback), 100);
  }
}

waitForFlowAlive(() => {
  window.FlowAlive.trackEvent({
    name: 'app_loaded'
  });
});

3. Error Handling

Wrap tracking calls in try-catch blocks:

try {
  window.FlowAlive.trackEvent({
    name: 'critical_action',
    properties: { action: 'checkout' }
  });
} catch (error) {
  console.error('FlowAlive tracking failed:', error);
}

4. Privacy Compliance

Respect user privacy preferences:

function initializeAnalytics() {
  const hasConsent = localStorage.getItem('analytics_consent') === 'true';
  
  if (hasConsent) {
    window.FlowAliveConfig = {
      apiKey: "your_api_key_here",
      trackNavigation: true
    };
    
    const script = document.createElement('script');
    script.src = 'https://flowalive-sdk.s3.eu-central-1.amazonaws.com/dist/web.global.js';
    document.head.appendChild(script);
  }
}

Troubleshooting

SDK Not Loading

Ensure the configuration script is placed before the SDK script:

<!-- ✅ Correct Order -->
<script>
  window.FlowAliveConfig = { apiKey: "your_key" };
</script>
<script src="https://flowalive-sdk.s3.eu-central-1.amazonaws.com/dist/web.global.js"></script>

<!-- ❌ Wrong Order -->
<script src="https://flowalive-sdk.s3.eu-central-1.amazonaws.com/dist/web.global.js"></script>
<script>
  window.FlowAliveConfig = { apiKey: "your_key" };
</script>

Events Not Tracking

Check if SDK is loaded: console.log(window.FlowAlive)
Enable debug mode: window.FlowAliveConfig = { apiKey: "...", debug: true }
Check browser console for errors
Verify API key is correct

CORS Issues

If you encounter CORS errors, ensure your domain is whitelisted in your FlowAlive dashboard settings.

Examples

Single Page Application

<!DOCTYPE html>
<html>
<head>
  <title>My App</title>
  <script>
    window.FlowAliveConfig = {
      apiKey: "flowalive_a030764a-be6e-4261-97bb-13a3ffe7c2ff",
      trackNavigation: true,
      debug: true
    };
  </script>
  <script src="https://flowalive-sdk.s3.eu-central-1.amazonaws.com/dist/web.global.js"></script>
</head>
<body>
  <button id="myButton">Click Me</button>

  <script>
    document.getElementById('myButton').addEventListener('click', function() {
      window.FlowAlive.trackEvent({
        name: 'button_clicked',
        properties: {
          button_id: 'myButton'
        }
      });
    });
  </script>
</body>
</html>

React Application

import { useEffect } from 'react';

function App() {
  useEffect(() => {
    // Track page view on mount
    if (window.FlowAlive) {
      window.FlowAlive.trackPageView({
        page: window.location.pathname,
        title: document.title
      });
    }
  }, []);

  const handleClick = () => {
    window.FlowAlive?.trackEvent({
      name: 'feature_used',
      properties: {
        feature: 'export_data'
      }
    });
  };

  return (
    <div>
      <button onClick={handleClick}>Export Data</button>
    </div>
  );
}

Support

Need help with integration? We're here to assist.

Email: support@flowalive.com
Documentation: https://flowalive-docs.esimfo.com/
Discord: FlowAlive Community

Web SDK

On this page