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

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

> Send events to power actions, campaigns and rewards

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

🔒

**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 →](https://docs.gameball.co/api-reference/introduction-v4.1.md)

```kotlin Kotlin theme={null}
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"
)
```

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

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

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

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

```kotlin theme={null}
val reviewEvent = Event.builder()
    .customerId("customer-123")
    .eventName("review_submitted")
    .eventMetaData("product_id", "PROD-789")
    .eventMetaData("rating", 5)
    .build()
```

### 3. Add to Cart Event

```kotlin theme={null}
val cartEvent = Event.builder()
    .customerId("customer-123")
    .eventName("add_to_cart")
    .eventMetaData("product_id", "PROD-456")
    .eventMetaData("quantity", 2)
    .build()
```

> [!NOTE]
>
> Events are the foundation of Gameball’s reward and engagement engine. Configure event triggers and reward rules from your Gameball dashboard.

> [!TIP]
>
> Consider showing the profile widget immediately after a customer earns points or unlocks a reward to reinforce engagement.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.