Script & Initialization

The Pulseahead SDK is a lightweight JavaScript library that loads and manages in-product surveys. It handles targeting, session management, and response collection with minimal performance impact.

If you are adding Pulseahead from a rollout checklist (copy snippet, confirm Project ID), use Install the script for the same steps in product language.

Installation

To initialize Pulseahead, add the following script to the <head> of your application. This snippet creates a global window.pulseahead function and asynchronously loads the main SDK (embed.js).

<script type="text/javascript">
  // 1. Initialize the command queue
  window.pulseahead =
    window.pulseahead ||
    function () {
      (window.pulseahead.q = window.pulseahead.q || []).push(arguments);
    };

  // 2. Configure with your Project ID
  window.pulseahead("config", { projectId: "YOUR_PROJECT_ID" });

  // 3. Load the SDK asynchronously
  (function () {
    var script = document.createElement("script");
    script.src = "https://www.pulseahead.com/embed.js";
    script.async = true;
    document.head.appendChild(script);
  })();
</script>

Placement

For best results, place the script as high as possible in the <head> of your document. Early initialization allows the SDK to:

Capture early user interactions.
Evaluate targeting rules before the page fully renders.
Reduce layout shift if a survey is triggered immediately.

Configuration

The config command is the entry point for the SDK. It must be called with a projectId.

window.pulseahead("config", {
  projectId: "uuid-string",
});

Parameter	Type	Description
`projectId`	`string`	Required. The unique identifier for your Pulseahead project.

Environment Support

The SDK supports all modern browsers (Chrome, Firefox, Safari, Edge) and works out of the box with Single Page Applications (SPAs).

Single Page Applications (SPAs)

The SDK listens for URL changes via the popstate and pushState events. You only need to initialize the script once in your global layout (e.g., _document.js in Next.js or index.html in React). It will automatically re-evaluate targeting rules on every route change.

Content Security Policy (CSP)

If your app uses a strict CSP, you must allow scripts and connections to the Pulseahead domain:

script-src https://www.pulseahead.com;
connect-src https://www.pulseahead.com;

Identifying users — identify, traits, and logout.
Manual trigger — open a specific survey with showSurvey.