> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gameball.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Track Customer Events

> Send events to power actions, campaigns and rewards

# 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.

<div className="security-banner">
  <div className="security-banner-icon">🔒</div>

  <div className="security-banner-content">
    <strong>Secure API Access:</strong> To benefit from v4.1 secure API endpoints, pass the <code>sessionToken</code> parameter when sending events (required in upcoming SDK v4). This enables automatic routing to v4.1 secure endpoints. <a href="/api-reference/introduction-v4.1">Learn more about v4.1 →</a>
  </div>
</div>

```dart theme={null}
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

<ParamField body="customerId" type="string" required>
  The unique identifier of the customer performing the event.
</ParamField>

<ParamField body="email" type="string">
  Customer's email address.
</ParamField>

<ParamField body="mobile" type="string">
  Customer's mobile number.
</ParamField>

<ParamField body="eventName" type="string" required>
  The name of the event (must be called before adding metadata).
</ParamField>

<ParamField body="eventMetaData" type="key-value">
  Metadata for the current event (can be String, Number, or Boolean values).
</ParamField>

<ParamField body="sessionToken" type="string">
  Optional session token to override the global token for this specific request. Required in upcoming SDK v4.
</ParamField>

<Info>
  In Flutter SDK, passing a sessionToken parameter updates the global token. Pass `null` to clear, or omit to use the current global token.
</Info>

### 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

<Steps>
  <Step title="Use Clear Event Names">
    Make event names human-readable and consistent (e.g., `purchase_completed`, `review_submitted`).
  </Step>

  <Step title="Send After Action Completion">
    Send events when an action is fully completed (e.g., after payment confirmation).
  </Step>

  <Step title="Include Relevant Metadata">
    Add metadata that will be useful for segmentation and campaign targeting.
  </Step>

  <Step title="Keep Keys Consistent">
    Use consistent metadata keys across similar events (e.g., always use `amount` not sometimes `price`).
  </Step>
</Steps>

## Common Event Examples

### Purchase Event

```dart theme={null}
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

```dart theme={null}
final reviewEvent = EventBuilder()
    .customerId("customer-123")
    .eventName("review_submitted")
    .eventMetaData("product_id", "PROD-789")
    .eventMetaData("rating", 5)
    .build();
```

<Info>
  Events are the foundation of Gameball's reward and engagement system. Configure how events trigger rewards and actions in your Gameball dashboard.
</Info>

## Next Steps

* [Show Profile Widget](/installation-guides/v3/flutter/show-profile)
* [Go-Live Checklist](/installation-guides/v3/flutter/go-live-checklist)