Skip to main content

​
Track Customer Events

Send events to Gameball when users perform important actions within your app. Events represent significant customer actions and can trigger rewards, campaigns, and engagement programs.
🔒
Secure API Access: To benefit from v4.1 secure API endpoints, pass the sessionToken parameter when sending events (required in upcoming SDK v4). This enables automatic routing to v4.1 secure endpoints. Learn more about v4.1 →
import 'package:gameball_sdk/gameball_sdk.dart';

final event = EventBuilder()
    .customerId("customer-123")
    .email("john@example.com")
    .mobile("+1234567890")
    .eventName("purchase")
    .eventMetaData("order_id", "ORD-12345")
    .eventMetaData("amount", 149.99)
    .eventMetaData("currency", "USD")
    .eventMetaData("category", "electronics")
    .eventMetaData("channel", "mobile_app")
    .build();

final gameballApp = GameballApp.getInstance();
gameballApp.sendEvent(event, (success, error) {
  if (error == null) {
    print("Event sent successfully");
  } else {
    print("Error sending event: $error");
  }
});

// With session token override
gameballApp.sendEvent(event, (success, error) {
  // Handle response
}, sessionToken: "customer-token");

​
Event Parameters

​
customerId
string
required
The unique identifier of the customer performing the event.
​
email
string
Customer’s email address.
​
mobile
string
Customer’s mobile number.
​
eventName
string
required
The name of the event (must be called before adding metadata).
​
eventMetaData
key-value
Metadata for the current event (can be String, Number, or Boolean values).
​
sessionToken
string
Optional session token to override the global token for this specific request. Required in upcoming SDK v4.
In Flutter SDK, passing a sessionToken parameter updates the global token. Pass null to clear, or omit to use the current global token.

​
Validation Rules

Event requires:
  • customerId cannot be null or empty
  • At least one event must be specified
  • Event names should be meaningful and descriptive
  • Event metadata values can be String, Number, or Boolean

​
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

Send events when an action is fully completed (e.g., after payment confirmation).
3

Include Relevant Metadata

Add metadata that will be useful for segmentation and campaign targeting.
4

Keep Keys Consistent

Use consistent metadata keys across similar events (e.g., always use amount not sometimes price).

​
Common Event Examples

​
Purchase Event

final purchaseEvent = EventBuilder()
    .customerId("customer-123")
    .email("john@example.com")
    .eventName("purchase_completed")
    .eventMetaData("order_id", "ORD-12345")
    .eventMetaData("amount", 149.99)
    .eventMetaData("currency", "USD")
    .eventMetaData("category", "electronics")
    .build();

GameballApp.getInstance().sendEvent(purchaseEvent, (success, error) {
  // Handle response
});

​
Review Event

final reviewEvent = EventBuilder()
    .customerId("customer-123")
    .eventName("review_submitted")
    .eventMetaData("product_id", "PROD-789")
    .eventMetaData("rating", 5)
    .build();
Events are the foundation of Gameball’s reward and engagement system. Configure how events trigger rewards and actions in your Gameball dashboard.

​
Next Steps