> ## 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 iOS SDK (v4)?

> Send customer events from the Gameball iOS SDK

# Send Customer Events

Use events to record customer actions (purchases, visits, interactions) and trigger Gameball automations and rewards.

***

## Basic Usage

🔒

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

```swift Swift (Completion Handler) theme={null}
import Gameball

do {
    let event = try Event(
        events: [
            "purchase": [
                "amount": 120.50,
                "currency": "USD",
                "order_id": "order-123",
                "items": 3,
                "channel": "ios_app"
            ]
        ],
        customerId: "customer-123"
    )

    GameballApp.getInstance().sendEvent(event) { success, errorMessage in
        if success {
            print("Event sent")
        } else if let errorMessage = errorMessage {
            print("Gameball event error: \(errorMessage)")
        }
    }
} catch {
    print("Validation error: \(error.localizedDescription)")
}
```

```swift Swift (Async/Await) theme={null}
import Gameball

Task {
    do {
        let event = try Event(
            events: [
                "opened_app": [
                    "platform": "iOS",
                    "version": "1.3.0"
                ]
            ],
            customerId: "customer-123"
        )

        let sent = try await GameballApp.getInstance().sendEvent(event)
        print("Event sent: \(sent)")
    } catch {
        print("Validation/API error: \(error.localizedDescription)")
    }
}
```

***

## Event Parameters

**customerId** `String` *required*

Permanent identifier for the customer.

**events** `[String: [String: Any]]` *required*

Dictionary of event names and metadata payloads.

**email** `String`

Customer email (optional).

**mobile** `String`

Customer mobile number (optional).

**sessionToken** `String`

Optional session token override for this request. Required in upcoming SDK v4.

***

## Best Practices

**1. Keep names consistent**

Standardize event names and keys (e.g., snake\_case).

**2. Send after init**

Call `sendEvent` only after the SDK and customer are initialized.

**3. Include identifiers**

Add order IDs, amounts, and channels to improve targeting.

**4. Handle errors**

Surface validation and API errors for quick debugging.


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