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 = "customer-token"
)

Event 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,
    new Callback<Boolean>() {
        @Override
        public void onSuccess(Boolean success) {
            // Event tracked successfully
        }
        
        @Override
        public void onError(Throwable error) {
            // Handle error
        }
    }
);

Event Parameters

string

required

Unique identifier for the customer performing the event.

string

required

Name of the event (e.g., "purchase", "review", "add_to_cart").

Map<String, Any>

Extra contextual information about the event (amount, product details, category, etc.).

string

Optional session token to override the global token for this specific request. Required in upcoming SDK v4.

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.

Overview

Web & POS Integration

Mobile Integration

How Do I Track Customer Events with the Android SDK (v3)?

Send Events Using the SDK

Event Parameters

Validation Rules

Best Practices

Common Event Examples

1. Purchase Event

2. Review Event

3. Add to Cart Event

​Send Events Using the SDK

​Event Parameters

​Validation Rules

​Best Practices

​Common Event Examples

​1. Purchase Event

​2. Review Event

​3. Add to Cart Event

Send Events Using the SDK

Event Parameters

Validation Rules

Best Practices

Common Event Examples

1. Purchase Event

2. Review Event

3. Add to Cart Event