Events and screens

Events are product facts, not delivery commands. One event can update analytics, segment membership, automation entry, conversion attribution, experiments, and local in-app trigger evaluation.

Track an event

Engage.events.track("order_completed") {
    value = 149.90
    transactionId = order.id
    put("currency", "EUR")
    put("item_count", order.items.size)
}

await Engage.events.track('order_completed', (event) {
  event.value = 149.90;
  event.transactionId = order.id;
  event.put('currency', 'EUR');
  event.put('item_count', order.items.length);
});

try await Engage.events.track("purchase_completed") {
    $0.set("sku", "annual_pro")
    $0.setValue(99.99)
    $0.setTransactionId("order_123")
}

Use stable snake_case names and consistent property types. Generate the transaction ID in your order domain so retries describe the same business event.

Track the active screen

Engage.events.trackScreen("checkout.payment")
Engage.events.clearScreen()

await Engage.events.trackScreen('checkout.payment');
await Engage.events.clearScreen();

try await Engage.events.trackScreen("checkout.payment")
try await Engage.events.clearScreen()

Screen state is explicit. Update it when the logical screen changes and clear it when no screen is active. This keeps screen-duration analytics and screen-triggered experiences coherent.

Flush behavior

Events use the durable SDK operation queue and normally synchronize automatically. flush() is an explicit synchronization boundary, not a requirement after every event.

Engage.events.flush()

await Engage.events.flush();

try await Engage.events.flush()

Use it for diagnostics, tests, or a product transition that must await pending work. Excessive flushing reduces batching efficiency.

Privacy and feature state

Analytics-disabled or privacy-opted-out installations do not produce normal audience and analytics operations. Design your application so core behavior never depends on event upload succeeding.