Quickstart

Install the SDK, identify a user, and open your first survey in under 5 minutes.

This guide gets ChirpBack running on your site end-to-end. By the end, you'll have:

The SDK installed
A signed-in user identified
Your first survey triggered

1. Grab your Client ID

Open the ChirpBack dashboard at app.chirpback.io, pick your project, and go to Project Settings → Developer. Copy your Client ID — it's a UUID, safe to ship in client-side code.

The Client ID identifies your project, not your account. The matching Client Secret on the same page is backend-only — never put it in client code.

2. Drop in the script tag

The fastest way to install — paste this just before </head> on every page where you want ChirpBack to run:

<script>
  !function(c,d){if(!c.Chirp){c.Chirp=new Proxy({q:[]},{get:(t,k)=>k==="q"?t.q:
  new Proxy(()=>{},{apply:(_,__,a)=>t.q.push({path:[k],args:a}),
  get:(_,k2)=>(...a)=>t.q.push({path:[k,k2],args:a})})});
  var s=d.createElement("script");s.async=1;
  s.src="https://cdn.chirpback.io/v1/sdk.js";d.head.appendChild(s);}}(window,document);

  Chirp.init({
    clientId: "your-client-id",
    consent: { state: "granted" },
  });
</script>

Replace your-client-id with the value you copied in step 1.

Using React, Next.js, Vite, or another bundler? See Install via npm instead. Same SDK, just imported as a module.

The snippet sets up window.Chirp as a queue so calls you make before the SDK script finishes loading are recorded and replayed automatically.

3. Identify the signed-in user

After your user logs in, tell ChirpBack who they are:

<script>
  Chirp.identify({
    email: "jane@acme.io",
    fullName: "Jane Doe",
    additionalData: {
      plan: "pro",
      signedUpAt: "2026-01-12",
    },
  });
</script>

Email is the only required field — it's what ChirpBack uses for segment targeting and frequency capping. Everything else is optional but powerful for segmenting later.

4. Trigger a survey

In the dashboard, create a survey under Survey → Campaigns, publish it, and copy its public ID from the Overview tab. Then trigger it from your code:

<script>
  Chirp.survey.open("nps_q2_check");
</script>

The survey appears in the layout you configured in the builder (Banner, Toast, Modal, or Slideout). When the user dismisses or submits it, ChirpBack records the response and respects your frequency rules.

5. Listen for events

Hook into key moments to track engagement or fire your own analytics:

<script>
  Chirp.on("survey:completed", function (payload) {
    console.log("Survey done:", payload.surveyId, payload.response);
  });
</script>

See the full list on the Events page.

Verify it's working

Open the browser dev tools console on your page. The SDK logs when it boots; survey, announcement, and feedback events log as they happen.

If nothing happens, check:

Your Client ID matches the one in Project Settings → Developer
The page's domain matches an entry in Allowed domains (or that list is empty)
The page isn't blocked by a Content Security Policy that omits cdn.chirpback.io

What's next

Install via npm — for React / Next.js / Vite projects
Identify users — pass custom traits for segmenting
Surveys — variables, theming, force mode
Announcements — broadcast product updates
Feedback widget — capture unstructured feedback
Consent — GDPR / CCPA / GPC compliance