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.

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

string

required

The unique identifier of the customer performing the event.

string

Customer’s email address.

string

Customer’s mobile number.

string

required

The name of the event (must be called before adding metadata).

key-value

Metadata for the current event (can be String, Number, or Boolean values).

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

Use Clear Event Names

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

Send After Action Completion

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

Include Relevant Metadata

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

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.

Overview

Web & POS Integration

Mobile Integration

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

Track Customer Events

Event Parameters

Validation Rules

Best Practices

Common Event Examples

Purchase Event

Review Event

Next Steps

​Track Customer Events

​Event Parameters

​Validation Rules

​Best Practices

​Common Event Examples

​Purchase Event

​Review Event

​Next Steps

Track Customer Events

Event Parameters

Validation Rules

Best Practices

Common Event Examples

Purchase Event

Review Event

Next Steps