Skip to Content
SDKSending Custom Events

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 sometimes BookingCreated).
  • 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 call

Use 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

GoodWhy
booking_createdClear, consistent, snake_case
payment_successDescribes exactly what happened
AvoidWhy
event1, testMeaningless in your dashboard later
Personal data in the payloadBreaks privacy-first — keep to counts and types

Next: Uninstall Survey Setup →