Installation

Add Pulse to your application and send the events that start it
View Markdown

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 once in your application.
  2. Generate an HMAC hash on your backend 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.
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.

OptionPurpose
appIdYour Churnkey App ID.
customerIdThe 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.
authHashServer-generated HMAC for that customer.
modeBilling environment. 'live' is the default.
onPulseRespondedCalled with the customer and their answer after they respond.
onPulseDismissedCalled with the customer when they close the question, including when they close it after answering.
onErrorCalled 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 itWhen the question can show
With the Churnkey script, on the pageDuring the same visit, unless another Pulse is already waiting to show
Any other way, such as from your serverThe next time the script asks Churnkey, usually the customer's next page load

With the Churnkey script

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(). 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:

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, 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:

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.

ReasonWhat 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.