Sending Custom Events
Heartbeats tell you a site is active. Custom events tell you what people actually do inside your plugin — the real product insight.
Unlike consent and heartbeats (which are automatic), custom events are
fully manual: nothing is tracked unless you call track() yourself.
Sending an event
Call track() on your SDK object (the one bootstrap() returned):
$sdk->track( 'booking_created', [
'ticket_type' => 'vip',
'quantity' => 2,
]);- First argument — the event name. Keep names consistent
(
booking_created, always — not sometimesBookingCreated). - Second argument — an optional array of extra detail. Keep it to counts, types, and settings — never personal data (no names, emails, order contents).
Tracking errors
There’s a dedicated method for error signals:
$sdk->track_error( 'Payment gateway timeout', [
'gateway' => 'stripe',
]);Same shape as track() — a message plus optional context.
Events are queued, not sent immediately
track() and track_error() do not make a network call. They add the
event to a local queue on the site. The queue is flushed (sent to Appneck)
automatically on the SDK’s heartbeat cycle. This is deliberate — it means
calling track() is cheap and safe even in high-frequency code paths (e.g.
every time a shortcode renders); you never slow down a page load.
Forcing an immediate send
If you genuinely need an event sent right now (rare — e.g. right before a
redirect where the cron might not fire), call flush():
$sdk->flush(); // this DOES make an immediate API callUse this sparingly. For almost all events, let the automatic flush handle it — that’s the whole point of the queue.
Controlling the flush interval (advanced)
The flush timing is adjustable via a filter, if you need it:
add_filter( 'appneck_sdk_flush_interval', function ( $seconds ) {
return 300; // flush every 5 minutes
});Most integrations never need to touch this.
Good vs. bad event names
| Good | Why |
|---|---|
booking_created | Clear, consistent, snake_case |
payment_success | Describes exactly what happened |
| Avoid | Why |
|---|---|
event1, test | Meaningless in your dashboard later |
| Personal data in the payload | Breaks privacy-first — keep to counts and types |
Next: Uninstall Survey Setup →