Website Integration (Client JS)

Integrate Appizer with any existing website form using the Web SDK

Integrate Appizer with any existing website form (e.g., newsletter signup) using your App ID. The Web SDK posts a user create/update to Appizer in the background and does not block your form's normal submit flow.

Setup

Set your website URL in App settings so Appizer can validate origin. Example: https://your-site.example. No API key is required in the browser.

Include the Web SDK

<script src="https://cdn.appizer.com/js/appizer-web.js"></script>

<script>
  AppizerWeb.init({
    appId: "YOUR_APP_ID",
    // Optional: override apiBase for custom environments
    // apiBase: "https://api.appizer.com",
    // Optional: disable auto-hooking (defaults to true)
    // autoHook: true,
    // Optional: enable verbose logging to console (defaults to false)
    // debug: true,
  });
</script>

Auto-hook Forms

Forms with an email field are auto-registered. You can explicitly flag forms with data-appizer="true" or set the App ID per form.

<form id="newsletter" data-appizer="true" data-appizer-app-id="YOUR_APP_ID" action="/subscribe" method="post">
  <input type="email" name="email" placeholder="you@example.com" required />
  <input type="text" name="firstName" placeholder="First name" />
  <input type="text" name="lastName" placeholder="Last name" />
  <button type="submit">Subscribe</button>
</form>

<script>
  // Your existing submit handler continues to work; SDK posts to Appizer in parallel.
  document.getElementById('newsletter').addEventListener('submit', function (e) {
    // ... your existing logic (e.g., analytics, server post)
  });
</script>

Advanced: Explicit Send via AppizerWeb.sendUser

Use this when your site uses custom AJAX or SPA flows that don't trigger a native form submit. It sends a user create/update directly to Appizer.

<!-- Ensure the SDK is loaded -->
<script src="https://cdn.appizer.com/js/appizer-web.js"></script>
<script>
  // Optional: init to keep defaults in sync
  AppizerWeb.init({ appId: "YOUR_APP_ID" });

  // In your AJAX flow or button handler
  const appId = "YOUR_APP_ID";
  const websiteUrl = window.location.origin;
  const email = document.querySelector("#email").value;
  const firstName = document.querySelector("#firstName")?.value;
  const lastName = document.querySelector("#lastName")?.value;

  AppizerWeb.sendUser(
    { appId, websiteUrl },
    { appId, websiteUrl, email, firstName, lastName }
  ).then((resp) => {
    console.log("AppizerWeb: user send result", resp);
  });
</script>

The AppizerWeb.sendUser(options, payload) method is provided by the SDK and posts in the background.

Custom Email Variable Name

If your form uses a custom email input name (like user[email] or contactEmail), configure the SDK for reliable email discovery.

Option 1: Single Email Field Name

<script>
  AppizerWeb.init({
    appId: "YOUR_APP_ID",
    // Tell the SDK exactly which input name holds the email
    emailField: "user[email]" // or "contactEmail"
  });
</script>

Option 2: Multiple Email Selectors

<script>
  AppizerWeb.init({
    appId: "YOUR_APP_ID",
    emailSelectors: [
      'input[name="email"]',
      'input[name="user[email]"]',
      'input[name="contactEmail"]',
      'input[type="email"]'
    ]
  });
</script>

Option 3: Per-Form Override

<script>
  const form = document.querySelector('#newsletter');
  AppizerWeb.registerForm(form, {
    appId: "YOUR_APP_ID",
    emailField: "contactEmail" // overrides discovery for this specific form
  });
</script>

Manual Hook (Advanced)

Prefer explicit control? Register a form manually:

<script>
  const form = document.querySelector('#newsletter');
  AppizerWeb.registerForm(form, {
    appId: "YOUR_APP_ID",
    // Optional: apiBase and endpoint overrides
    // apiBase: "https://api.appizer.com",
    // endpoint: "/v1/website/users",
    // Optional: websiteUrl override (defaults to window.location.origin)
    // websiteUrl: "https://your-site.example",
  });
</script>

What Gets Sent

The SDK sends a background request to POST /v1/website/users with fields it detects:

{
  "appId": "YOUR_APP_ID",
  "websiteUrl": "https://your-site.example",
  "email": "you@example.com",
  // optional fields if present
  "firstName": "Ada",
  "lastName": "Lovelace",
  // or a single name field when first/last not provided
  "name": "Ada Lovelace",
  // optional externalId if your form provides it
  "externalId": "user-123"
}

Security

  • No API keys in the browser. Origin is validated against your configured website URL.
  • SDK does not block form submission; network issues do not affect your UX.
  • Use server-side APIs for privileged operations; the website endpoint is limited to user create/update.

Configuration Options

OptionTypeDefaultDescription
appIdstringrequiredYour Appizer App ID
apiBasestringhttps://api.appizer.comAPI base URL
autoHookbooleantrueAutomatically register forms with email fields
autoEventsbooleantrueEnable automatic page view tracking
userIdStorageKeystringappizer_user_idlocalStorage key for user ID
eventsEndpointstring/v1/website/eventsOverride events API endpoint
debugbooleanfalseEnable console logging
emailFieldstring-Specific email input name to use
emailSelectorsarray-Array of CSS selectors for email inputs

Automatic Event Tracking

The Web SDK includes automatic event tracking capabilities. When enabled, it automatically tracks page views and provides an easy API for custom event tracking with automatic user identification.

Enabled by Default

Automatic event tracking is enabled by default. The SDK will automatically generate and persist user IDs, track page views, and provide a simple API for custom events. No API keys needed - authentication is done via domain validation.

Setup with Event Tracking

To enable automatic event tracking, simply initialize the SDK with your App ID:

<script src="https://cdn.appizer.com/js/appizer-web.js"></script>

<script>
  AppizerWeb.init({
    appId: "YOUR_APP_ID",
    autoEvents: true,  // Automatic page view tracking (including SPAs)
    autoHook: true,    // Automatic form submission tracking
    // Optional: customize localStorage key for user ID
    // userIdStorageKey: "appizer_user_id",
    // Optional: enable debug logging
    // debug: false,
  });
</script>

Domain-Based Security

Event tracking uses domain validation instead of API keys. Configure your authorized domains in App Settings to control which websites can track events. This is more secure as no sensitive credentials are exposed in your client-side code.

How It Works

  1. User ID Generation: The SDK checks localStorage for an existing user ID. If not found, it generates a unique ID based on browser fingerprinting (user agent, screen properties, timezone, etc.) and stores it in localStorage.

  2. Automatic Page Views: When autoEvents: true (default), the SDK automatically tracks a page_view event on page load with the current URL, path, title, and referrer.

  3. SPA Navigation Detection: For Single Page Applications (React, Vue, Angular, Next.js, etc.), the SDK automatically detects route changes by intercepting the History API and tracking page views on navigation—no manual calls needed.

  4. Custom Events: Use the trackEvent() API to track custom events with the same automatically-generated user ID.

User ID Management

The SDK provides methods to get and set user IDs:

// Get the current user ID (auto-generated or previously set)
const userId = AppizerWeb.getUserId();
console.log('Current user ID:', userId);

// Set a custom user ID (e.g., after user login)
AppizerWeb.setUserId('user_12345');

// Now all events will use this custom user ID
AppizerWeb.trackEvent('user_logged_in', { method: 'email' });

Track Custom Events

Track any custom event with optional properties:

// Track a simple event
AppizerWeb.trackEvent('button_clicked');

// Track an event with properties
AppizerWeb.trackEvent('product_viewed', {
  product_id: 'prod_123',
  product_name: 'Premium Plan',
  price: 29.99,
  currency: 'USD'
});

// Track an event with a specific user ID (overrides auto-generated ID)
AppizerWeb.trackEvent('purchase_completed', {
  order_id: 'order_789',
  total: 99.99
}, {
  userId: 'custom_user_id'
});

Automatic Page View Event

When automatic tracking is enabled, the SDK sends a page_view event on every page load:

{
  "event_name": "page_view",
  "user_id": "anon_abc123_xyz789",
  "properties": {
    "url": "https://yoursite.com/products",
    "path": "/products",
    "title": "Products - Your Site",
    "referrer": "https://google.com"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..."
}

Complete Example

Here's a complete example combining form tracking and event tracking:

<!DOCTYPE html>
<html>
<head>
  <title>My Website</title>
  <script src="https://cdn.appizer.com/js/appizer-web.js"></script>
  <script>
    // Initialize SDK with both form tracking and event tracking
    AppizerWeb.init({
      appId: "YOUR_APP_ID",
      autoEvents: true, // Track page views automatically
      debug: false
    });
  </script>
</head>
<body>
  <!-- Form will be auto-tracked for user creation -->
  <form id="newsletter">
    <input type="email" name="email" required />
    <button type="submit">Subscribe</button>
  </form>

  <!-- Track custom events on user interactions -->
  <button id="cta-button">Get Started</button>

  <script>
    // Track button clicks
    document.getElementById('cta-button').addEventListener('click', function() {
      AppizerWeb.trackEvent('cta_clicked', {
        button_text: 'Get Started',
        page: window.location.pathname
      });
    });

    // Track when user scrolls to bottom
    window.addEventListener('scroll', function() {
      if ((window.innerHeight + window.scrollY) >= document.body.offsetHeight) {
        AppizerWeb.trackEvent('page_scrolled_to_bottom');
      }
    });
  </script>
</body>
</html>

Privacy & Compliance

Privacy Considerations

  • User IDs are generated from browser properties, not personal information
  • No cookies are used; data is stored in localStorage only
  • Users can clear their localStorage to reset their ID
  • IP addresses are captured server-side for analytics but not stored in the fingerprint
  • Ensure your privacy policy discloses analytics tracking

Best Practices

  • Initialize the SDK once in your page header
  • Let auto-hooking handle most forms automatically
  • Use manual registration for complex forms or SPAs
  • Test with debug: true during development
  • Verify origin URL is correctly configured in App settings
  • Handle form submission normally; SDK works in parallel
  • Use setUserId() to link anonymous users with known identities after login
  • Track meaningful events that help you understand user behavior
Previous
Rate Limits
Next
Events