Skip to main content

​
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("product_id", "12345")
  .eventMetaData("amount", 99.99)
  .eventMetaData("currency", "USD")
  .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

​
customerId
string
required
Unique identifier for the customer performing the event.
​
eventName
string
required
Name of the event (e.g., "purchase", "review", "add_to_cart").
​
eventMetaData
Map<String, Any>
Extra contextual information about the event (amount, product details, category, etc.).
​
sessionToken
string
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
  • At least one metadata entry
  • Metadata values must be valid primitive types or objects

​
Best Practices

1

Use Clear Event Names

Make event names human-readable and consistent (e.g., purchase_completed, review_submitted).
2

Send After Action Completion

Only send events when the action is fully completed (e.g., after successful payment confirmation).
3

Include Relevant Metadata

Add metadata that supports segmentation and campaign targeting.
4

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.