---
title: Installation
description: Add Pulse to your application and send the events that start it
---

Pulse uses the same Churnkey script and HMAC authentication as Cancel Flows. If the Churnkey script is already loaded, you do not need to add it again.

## Load the Churnkey script and identify the customer

1. Load the [Churnkey script](/cancel-flows/quick-start-guide#step-one-place-script-element) once in your application.
2. Generate an [HMAC hash on your backend](/cancel-flows/quick-start-guide#step-two-generate-secure-hmac-hash) for the signed-in customer's ID in your billing provider.
3. Wait for the Churnkey script to load before you call `checkPulse` or `track`. Until it loads, `window.churnkey.checkPulse` is undefined. To call it as soon as the script loads, add `a.onload = () => { ... }` to the loader snippet, before the line that inserts the script.
4. Call `checkPulse` once the customer is identified. Call it on every page load. In a single-page application, call it again after each route change.

```javascript
window.churnkey.checkPulse({
  appId: 'YOUR_APP_ID',
  customerId: 'STRIPE_CUSTOMER_ID',
  authHash: 'SERVER_GENERATED_HMAC',
  mode: 'live',
});
```

`checkPulse` asks Churnkey which Pulses this customer can see. It does not show a question immediately. The script waits for the timing you set on the Pulse.

Calling `checkPulse` often is safe. The script remembers Churnkey's answer for up to a day and reuses it. While a Pulse is waiting for an event, the script asks Churnkey again on each page load. Within a page, a later `checkPulse` call asks again at most once a minute. The script does not ask in the day after the customer answers or closes a question. In test mode the script asks Churnkey on every page load.

| Option | Purpose |
| --- | --- |
| `appId` | Your Churnkey App ID. |
| `customerId` | The signed-in customer's ID in your billing provider. With Paddle Classic, pass the subscription ID, which is the ID you sign for Cancel Flows. |
| `authHash` | Server-generated HMAC for that customer. |
| `mode` | Billing environment. `'live'` is the default. |
| `onPulseResponded` | Called with the customer and their answer after they respond. |
| `onPulseDismissed` | Called with the customer when they close the question, including when they close it after answering. |
| `onError` | Called with an error message when a request from `track` or `event` fails. |

If the page already calls `window.churnkey.check()` for the same customer, call `window.churnkey.checkPulse()` after it without `appId`, `customerId` or `authHash`. It reuses that customer. You can still pass the callbacks.

Keep your Churnkey API key on the server. Your backend should verify that the signed-in user can access the customer being signed.

## Send the event that starts a Pulse

A Pulse set to **After an Event** waits for an event you send to Churnkey. The event's name must match the name on the Pulse, including capital letters. In the Pulse editor, the Event list shows the events Churnkey has received from you in the last 30 days and how many customers sent each one in the last 7 days.

How you send the event decides how soon the question can show.

| How you send it | When the question can show |
| --- | --- |
| With the Churnkey script, on the page | During the same visit, unless another Pulse is already waiting to show |
| Any other way, such as from your server | The next time the script asks Churnkey, usually the customer's next page load |

### With the Churnkey script

```javascript
window.churnkey.track('Report Exported');
```

`track` records the event for the customer you passed to `checkPulse` and can start a Pulse that is waiting on it. It is the short form of [`window.churnkey.event()`](/data-integrations/event-tracking#client-side). Use `event()` when you need to send properties with the event. It can start a waiting Pulse too.

Call `track` after `checkPulse`. Before the page has identified a customer, `track` records nothing. While the check is in progress, a returning customer can start a Pulse the browser already knows is waiting for that event. On a first visit, wait for the promise from `checkPulse` so the script knows which Pulse to start:

```javascript
const pulseReady = window.churnkey.checkPulse({
  appId: 'YOUR_APP_ID',
  customerId: 'STRIPE_CUSTOMER_ID',
  authHash: 'SERVER_GENERATED_HMAC',
});

// Later, when the customer finishes the action.
pulseReady.then(() => window.churnkey.track('Report Exported'));
```

Wait for the promise from the first call. A second `checkPulse` call made while the first is still waiting returns immediately.

Leaving the page can interrupt the request before Churnkey records the event. If the action redirects the customer, send the event from your server or call `track` on the destination page after `checkPulse` finishes.

### From your server

Send the event with the [events API or `@churnkey/node`](/data-integrations/event-tracking#server-side), with the customer's ID in your billing provider as `customerId`. With Paddle Classic, use the subscription ID. The next time the script asks, the Pulse can start if Churnkey received the event in the last 7 days and after the last time that customer was asked this Pulse. The script does not ask in the day after the customer answers or closes a question, so the Pulse waits until that day is over.

Send each event one way. If your server and the Churnkey script both send it, Churnkey counts it twice.

## Check it on your site

Sign in to your application as a customer. Then add `?churnkey_debug=1` to the page address, or run this in the browser console:

```javascript
window.churnkey.debug();
```

A panel opens on the page. It shows:

- the customer Churnkey identified and whether Churnkey accepted the last check
- each Pulse that is turned on, and why it is or is not showing for this customer
- each event the Churnkey script sends from the page while the panel is open

**Show It Now** previews the first Pulse this customer can see, without waiting. Nothing is sent or saved, and your callbacks are not called. **Check Again** clears what the browser remembers and asks Churnkey again. Press it after a preview to go back to the real question. If you opened the panel from the console, press it to see Churnkey's current answer.

Anyone who knows the address or the command can open the panel. It shows them their own customer ID, the text of your questions, the event each one waits for and why it is not showing for them. It does not show a Pulse's name or its audience conditions.

## Why a Pulse might not show

The test panel names the reason for the customer you are signed in as. These are the common ones.

| Reason | What to do |
| --- | --- |
| Churnkey has not received the event. | Check the event's name in the Pulse editor. The editor says whether the event has arrived. |
| The customer was already asked. | Check the Pulse's Frequency setting. |
| The customer is not in the audience. | Check the Pulse's Audience conditions. |
| Churnkey could not check the audience. | The panel says why. Most often Churnkey found no subscription for the customer. Check that you passed their ID in your billing provider. |
| Another Pulse is already waiting to show on this page. | The script watches one Pulse at a time, so the event does not start its Pulse on this page. Churnkey keeps the event, so the Pulse can start on a later page. In the day after the customer answers or closes a question, it can start only if the page sends the event again. If the other Pulse's timing is never met, such as exit intent on a phone, the Pulse waiting on your event can stay blocked on every page. The test panel's event list shows when this happens. |
| The timing has not been met. | Keep using the page. **A pause** shows the question after the active time you set and a short pause. **Exit intent** needs a mouse, so it never shows on a phone or tablet. **Scroll depth** needs the page itself to scroll halfway down. No question shows while the tab is in the background or the customer is typing in a field. |
| The browser is using an earlier answer from Churnkey. | The script remembers Churnkey's answer for up to a day. Open the page with `?churnkey_debug=1` to get a fresh check. If automatic checks are paused, the panel shows when they resume. **Check Again** clears that pause for this browser. |
| A Failed Payment Wall, a Pause Wall or an Annual Upsell offer is on screen. | Pulse does not show on top of them. It can show on a later page. |
