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

> Start sending your customer's events on your platform to Gameball

Send your customer's **events** on your platform to Gameball, along with any **metadata** that describes the event. Depending on your Gameball programs configuration, the customers can be rewarded based on the sent events.

Customer **events** can be sent to Gameball via the [Track Events API](https://docs.gameball.co/api-reference/events/send-events.md).

## What are Events?

Every `Track Event` call records a single user action. We call these "**events**". We recommend that you make your event names human-readable, so that everyone can know what they mean instantly.

**Event metadata** are extra pieces of information you can tie to events you track. They can be anything that will be useful while designing your program.

> [!NOTE]
>
> Tracked **events** can be UI events or server side events depending on how you would like to design your programs.

## Event Tracking Benefits

Tracking events allows you to:

1. **Gain insights** into what your customers are doing on your platform
2. **Reward actions** in real-time to drive more engagement
3. **Personalize experiences** based on customer interests and behaviors

## How Gameball Event Engine Works

Gameball listens to your system, takes note of your customers' actions, and uses that data to trigger rewards or personalized messages.

**1. Send Event Data**

Send customer events to Gameball via API calls with relevant metadata

**2. Gameball Processing**

Gameball processes the events and checks against your configured reward rules

**3. Trigger Rewards**

Based on your program configuration, rewards and notifications are triggered

## Example: E-commerce Event Tracking

Let's say you run an online store and want to reward customers when they add items to their carts.

### Basic Add to Cart Event

When a customer clicks "Add to Cart", you can send a simple event to Gameball:

```bash cURL theme={null}
curl -X POST 'https://api.gameball.co/v4.0/events' \
  -H 'Content-Type: application/json' \
  -H 'APIKey: YOUR_API_KEY' \
  -H 'TransactionKey: YOUR_TRANSACTION_KEY' \
  -d '{
    "events": {
      "add_to_cart": {}
    },
    "customerId": "CUST_ID"
  }'
```

### Enhanced Add to Cart Event

If you want to go further, add details like product ID, price, and category:

```bash cURL theme={null}
curl -X POST 'https://api.gameball.co/v4.0/events' \
  -H 'Content-Type: application/json' \
  -H 'APIKey: YOUR_API_KEY' \
  -H 'TransactionKey: YOUR_TRANSACTION_KEY' \
  -d '{
    "events": {
      "add_to_cart": {
        "product_id": "231402",
        "product_title": "iPhone 12",
        "price": 1350.00,
        "category": "Electronics",
        "quantity": 1
      }
    },
    "customerId": "CUST_ID"
  }'
```

## Common Event Types

> [card] E-commerce Events
>
> * `add_to_cart`
> * `view_product`
> * `purchase`
> * `wishlist_add`

> [card] User Engagement
>
> * `signup`
> * `login`
> * `profile_update`
> * `newsletter_subscribe`

> [card] Content Interaction
>
> * `video_watch`
> * `article_read`
> * `download`
> * `share`

> [card] Custom Events
>
> * Any custom event name
> * Business-specific actions
> * Platform-specific behaviors

## Event Metadata Best Practices

**1. Use Descriptive Names**

Make event names human-readable and descriptive:

✅ Good: `product_viewed`, `checkout_started`, `review_submitted`

❌ Bad: `evt1`, `action_a`, `click_btn`

**2. Include Relevant Metadata**

Add useful information that can be used for targeting and analytics:

```json theme={null}
{
  "events": {
    "product_viewed": {
      "product_id": "12345",
      "category": "Electronics",
      "price": 299.99,
      "brand": "Apple"
    }
  }
}
```

**3. Be Consistent**

Use consistent naming conventions and data structures across your events

## API Integration

> [!NOTE]
>
> For detailed API implementation, refer to the [Events API Reference](https://docs.gameball.co/api-reference/events/send-events.md) and [Tracking Customer Events tutorial](https://docs.gameball.co/tutorials/experiences/tracking-events.md).

## Related Resources

* [Events API Reference](https://docs.gameball.co/api-reference/events/send-events.md)
* [Tracking Customer Events Tutorial](https://docs.gameball.co/tutorials/experiences/tracking-events.md)
* [Build Custom UI Elements](https://docs.gameball.co/tutorials/experiences/more/build-your-own-ui/index.md)

## Next Steps

* [Track Orders & Cashback](https://docs.gameball.co/installation-guides/v4/web/track-orders.md)
* [Integrate Redemption](https://docs.gameball.co/installation-guides/v4/web/integrate-redemption.md)


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