In-app survey trigger events: show a survey after an action
To trigger an in-app survey from an event, set the survey trigger to event in the builder, enter an event name, and call track() with that exact name in your code. The next matching call shows the survey once. You can also send the event from your server with the Secret key.
An event trigger lets you ask right after something happens, such as finishing onboarding or completing a purchase. The code on this page comes from the surveys guide and the server events API.
What is an event trigger?
A survey can open in three ways: on page load, after scrolling, or when your code sends a specific event. The event option ties the survey to a moment in your product. The person has just done something, so the question is fresh.
Your event names are your own. You choose a name such as completed_onboarding and use the same string in the builder and in your code.
How do you trigger a survey from track()?
- Open Surveys and create or edit a survey.
- Set the trigger to event.
- Enter the event name, for example
completed_onboarding. - Publish the survey.
- Call
track()in your code when the action happens.
import { track } from "@justonecx/sdk";
track("completed_onboarding");
The next track() call with that exact name shows the survey once. The name must match exactly, so check spelling and case.
track() runs after init(). Its signature is track(eventName: string, properties?: Traits): void. See identify, group, track for details.
How do you show a survey once per order, ticket or purchase?
By default a person sees a survey once, or again after a throttle period. To ask after every order instead, set Show once per (event property) in the Delivery panel of the survey builder. This option is for event triggers only. Enter a property name, for example order_id, and send that property with the event:
track("purchase_completed", { order_id: "A-1042" });
The survey now shows at most once for each different order_id, for each person. A second track() with the same order does nothing, whether the person answered or dismissed.
Every order is a new chance to ask. For that reason, the Frequency setting and the throttle between surveys do not apply to a survey with this option.
How do you trigger a survey from your server?
Some events never reach the browser: a payment webhook, a finished job, a shipped order. You can send these from your backend with the Secret key. Use the same property as in the browser call, and send a userId.
The endpoint is POST /ingest/events/track. The fields are:
| Field | Notes |
|---|---|
userId |
Your own user id, the one you pass to identify(). Recommended. |
visitorId |
One browser's visitor id. Use only if you have it. |
accountId |
Optional. Links the person to an account, like group(). |
eventName |
For example purchase_completed. |
properties |
Optional. Strings, numbers, booleans or null. |
Example with curl, adapted from the docs:
curl -X POST https://api.justonecx.com/ingest/events/track \
-H "Authorization: Bearer $JUSTONECX_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"userId": "user-123", "eventName": "purchase_completed", "properties": {"order_id": "A-1042"}}'
The call returns 204 and no body. The survey then shows on that person's next page load, once for that order.
Keep the Secret key on the server. Set it as JUSTONECX_SECRET_KEY in your server environment and never put it in browser code. See Keys. More on this approach is in server-side event tracking for SaaS.
Why does the person need to be identified?
A server event with userId goes to that person's profile across all their browsers. If the person has never opened your app, a profile is created and joins the later identify() for the same id. So call identify() with the same id in your app:
identify("user-42", { role: "admin", plan: "growth" });
For identity and trust, see identify users with the SDK.
What if the event fires on a different page?
You can add page rules to the survey in its Settings tab. A survey with page rules only opens when the visitor is on a matching page. An event trigger that fires on another page waits and shows when the person reaches a matching page.
What errors can the server call return?
| Status | Meaning |
|---|---|
400 |
The body has neither userId nor visitorId, or a field is too long or the wrong type. |
401 |
The Secret key is missing, wrong or was rotated. |
429 |
Too many calls for this key (3000 per minute). Slow down and retry. |
Frequently asked questions
Does the event name have to match exactly?
Yes. The next track() call with that exact name shows the survey once.
How do I ask after every order?
Set Show once per (event property) in the Delivery panel, for example order_id, and send that property with track(). The survey shows at most once for each different value.
Can I trigger a survey without the browser?
Yes. Send the event from your server with the Secret key, using userId and the same property. The survey shows on the person's next page load.
Does the Frequency setting apply to once-per-order surveys?
No. The Frequency setting and the throttle between surveys do not apply when you use Show once per (event property).
See how it works in the live demo.