Send Events Using the SDK
Send events to Gameball to power actions, campaigns, and rewards. Events represent significant customer actions within your app—such as purchases, product interactions, or engagement milestones.
val event = Event.builder()
.customerId("customer-123")
.eventName("purchase")
.eventMetaData("order_id", "ORD-12345")
.eventMetaData("amount", 149.99)
.eventMetaData("currency", "USD")
.eventMetaData("category", "electronics")
.eventMetaData("channel", "mobile_app")
.build()
GameballApp.getInstance(context).sendEvent(
event,
object : Callback<Boolean> {
override fun onSuccess(success: Boolean) {
// Event tracked successfully
}
override fun onError(error: Throwable) {
// Handle error
}
}
)
// With session token override
GameballApp.getInstance(context).sendEvent(
event,
callback,
sessionToken = "custom-token"
)
Event Parameters
Unique identifier for the customer performing the event.
Name of the event (e.g., "purchase", "review", "add_to_cart").
Extra contextual information about the event (amount, product details, category, etc.).
Optional session token to override the global token for this specific request.
Validation Rules
An event requires:
- Customer ID is not empty
- Event name must be provided
- Metadata values (if provided) must be valid primitive types or objects
Best Practices
Use Clear Event Names
Make event names human-readable and consistent (e.g., purchase_completed, review_submitted).
Send After Action Completion
Only send events when the action is fully completed (e.g., after successful payment confirmation).
Include Relevant Metadata
Add metadata that supports segmentation and campaign targeting.
Keep Metadata Keys Consistent
Use consistent naming across events (e.g., always amount, not sometimes price).
Common Event Examples
1. Purchase Event
val purchaseEvent = Event.builder()
.customerId("customer-123")
.eventName("purchase_completed")
.eventMetaData("order_id", "ORD-12345")
.eventMetaData("amount", 149.99)
.eventMetaData("currency", "USD")
.eventMetaData("category", "electronics")
.build()
2. Review Event
val reviewEvent = Event.builder()
.customerId("customer-123")
.eventName("review_submitted")
.eventMetaData("product_id", "PROD-789")
.eventMetaData("rating", 5)
.build()
3. Add to Cart Event
val cartEvent = Event.builder()
.customerId("customer-123")
.eventName("add_to_cart")
.eventMetaData("product_id", "PROD-456")
.eventMetaData("quantity", 2)
.build()
Events are the foundation of Gameball’s reward and engagement engine. Configure event triggers and reward rules from your Gameball dashboard.
Consider showing the profile widget immediately after a customer earns points or unlocks a reward to reinforce engagement.
