Gleap JavaScript SDK

Common errors

• ReferenceError: Gleap is not defined

  cause The Gleap SDK was not imported correctly, or the script tag for the SDK was not loaded before its usage in a non-module context.
  fix Ensure `import Gleap from 'gleap';` is at the top of your module, or if using a script tag, place it before any code that references `Gleap`.

• Gleap.initialize is not a function

  cause This usually indicates that `Gleap` was imported incorrectly (e.g., as a named import instead of default) or that the imported object does not expose an `initialize` method.
  fix Verify that you are using `import Gleap from 'gleap';` and then calling `Gleap.initialize(...)` directly on the default-imported object.

• No Gleap feedback button or widget is visible on the page.

  cause The SDK might not have been initialized or the provided SDK token is incorrect/inactive, or the widget is hidden by configuration.
  fix Check if `Gleap.initialize('YOUR_SDK_TOKEN')` is called with the correct token. Confirm the Gleap dashboard settings don't have the widget disabled or restricted by page rules.

Warnings

• gotcha As of v15.2.2, Gleap enabled cookie mode by default. This change affects session management, particularly on shared subdomains, potentially altering existing behavior if you had specific cookie configurations.
  Fix: Review your session management and subdomain strategies if you were relying on previous non-cookie-based defaults. Consult Gleap documentation for explicit control over cookie behavior if needed.
• gotcha Failing to initialize the SDK with a valid `SDK-TOKEN` will prevent the Gleap widget and associated functionality from appearing or working correctly.
  Fix: Ensure you replace 'SDK-TOKEN' with the actual token obtained from your Gleap dashboard during initialization. Verify the token is correct and that `Gleap.initialize()` is called once, early in your application's lifecycle.
• gotcha The Gleap SDK is designed for client-side environments (browsers). Attempting to run its initialization or core functionality directly in a Node.js server-side environment without proper mocking or conditional loading can lead to errors.
  Fix: Ensure Gleap is only initialized and used within browser contexts. For server-rendered applications (SSR), use conditional checks like `if (typeof window !== 'undefined')` before initializing Gleap.

Install

• npm install gleap npm
• yarn add gleap yarn
• pnpm add gleap pnpm

Imports

• Gleap
  wrong:

  const Gleap = require('gleap');

  correct:

  import Gleap from 'gleap';

  Gleap is exported as a default module. CommonJS require() is not the primary way to import in modern applications.
• initialize
  wrong:

  import { initialize } from 'gleap';

  correct:

  import Gleap from 'gleap'; Gleap.initialize('YOUR_SDK_TOKEN');

  The initialize method is a static method of the default exported Gleap object, not a named export.
• Gleap (type)

  import Gleap from 'gleap'; type GleapInstance = typeof Gleap;

  The package ships with TypeScript types. The default export 'Gleap' itself represents the main API surface.

Quickstart

Demonstrates how to install, import, and initialize the Gleap SDK with an SDK token, including an example of user identification.

import Gleap from 'gleap';

// Replace 'YOUR_SDK_TOKEN' with your actual token from the Gleap dashboard.
// For production, consider using environment variables for security.
const SDK_TOKEN = process.env.GLEAP_SDK_TOKEN || 'YOUR_SDK_TOKEN_HERE';

if (SDK_TOKEN === 'YOUR_SDK_TOKEN_HERE') {
  console.warn('Gleap SDK: SDK_TOKEN is a placeholder. Please replace it with your actual token.');
}

try {
  Gleap.initialize(SDK_TOKEN);
  console.log('Gleap SDK initialized successfully.');
  
  // Example of identifying a user (optional, but common practice)
  Gleap.identify('user-123', {
    name: 'John Doe',
    email: 'john.doe@example.com',
    plan: 'premium'
  });

  // To open the Gleap widget programmatically (e.g., from a custom button)
  // Gleap.open();

} catch (error) {
  console.error('Failed to initialize Gleap SDK:', error);
}