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

# Ruby SDK

> Track events from Ruby servers with the Mixpanel server-side SDK

## Installation

```bash theme={null}
gem install mixpanel-ruby
```

## Initialize

```ruby theme={null}
require 'mixpanel-ruby'

tracker = Mixpanel::Tracker.new("YOUR_PROJECT_TOKEN")
```

## Track Events

<Warning>
  You must provide a `distinct_id` for all events.
</Warning>

```ruby theme={null}
tracker.track('12345', 'Purchase', {
  'product' => 'Premium Subscription',
  'amount' => 49.99,
  'currency' => 'USD'
})
```

## Import Historical Events

For events older than 5 days:

```ruby theme={null}
tracker.import(
  "API_KEY",
  "12345",
  "Old Purchase",
  {
    'amount' => 100,
    'time' => 1369353600
  }
)
```

## User Profiles

```ruby theme={null}
tracker.people.set('12345', {
  'name' => 'John Doe',
  '$email' => 'john@example.com',
  'plan' => 'Premium'
}, ip = 0) # Disable geolocation
```

<Tabs>
  <Tab title="set_once()">
    ```ruby theme={null}
    tracker.people.set_once('12345', {
      'First Purchase' => '2024-01-01'
    }, ip = 0)
    ```
  </Tab>

  <Tab title="increment()">
    ```ruby theme={null}
    tracker.people.increment('12345', {
      'login_count' => 1,
      'age' => 1
    }, ip = 0)
    ```
  </Tab>

  <Tab title="append()">
    ```ruby theme={null}
    tracker.people.append('12345', {
      'transactions' => 'purchase_123'
    }, ip = 0)
    ```
  </Tab>

  <Tab title="union()">
    ```ruby theme={null}
    tracker.people.union('12345', {
      'skills' => ['Ruby', 'Rails']
    }, ip = 0)
    ```
  </Tab>
</Tabs>

## Group Analytics

### Send Events

```ruby theme={null}
tracker.track('12345', 'Feature Used', {
  'company' => 'Acme Inc',
  'feature' => 'Reports'
})
```

### Set Group Properties

```ruby theme={null}
tracker.groups.set('company', 'Acme Inc', {
  'name' => 'Acme Inc',
  'industry' => 'Technology',
  'employees' => 500
})
```

<Tabs>
  <Tab title="set_once()">
    ```ruby theme={null}
    tracker.groups.set_once('company', 'Acme Inc', {
      'founded' => '2010-01-01'
    })
    ```
  </Tab>

  <Tab title="unset()">
    ```ruby theme={null}
    tracker.groups.unset('company', 'Acme Inc', 'temp_property')
    ```
  </Tab>

  <Tab title="union()">
    ```ruby theme={null}
    tracker.groups.union('company', 'Acme Inc', {
      'features' => ['Reports', 'Analytics']
    })
    ```
  </Tab>

  <Tab title="remove()">
    ```ruby theme={null}
    tracker.groups.remove('company', 'Acme Inc', {
      'features' => ['Beta Feature']
    })
    ```
  </Tab>
</Tabs>

## Privacy Controls

### EU Data Residency

```ruby theme={null}
require 'mixpanel-ruby'

eu_consumer = Mixpanel::Consumer.new(
  'https://api-eu.mixpanel.com/track',
  'https://api-eu.mixpanel.com/engage',
  'https://api-eu.mixpanel.com/groups'
)

tracker = Mixpanel::Tracker.new(YOUR_PROJECT_TOKEN) do |type, message|
  eu_consumer.send!(type, message)
end
```

### India Data Residency

```ruby theme={null}
in_consumer = Mixpanel::Consumer.new(
  'https://api-in.mixpanel.com/track',
  'https://api-in.mixpanel.com/engage',
  'https://api-in.mixpanel.com/groups'
)

tracker = Mixpanel::Tracker.new(YOUR_PROJECT_TOKEN) do |type, message|
  in_consumer.send!(type, message)
end
```

### Disable Geolocation

```ruby theme={null}
# Set ip to 0 for events
tracker.track('12345', 'event', {
  'property' => 'value'
}, ip = 0)

# Set ip to 0 for profiles
tracker.people.set('12345', {
  'name' => 'John'
}, ip = 0)
```

## Platform Considerations

<Warning>
  All server-side calls originate from your server's IP. Set `ip = 0` to disable geolocation.
</Warning>

* You manage `distinct_id` yourself
* No automatic identity management
* Use `.import()` for historical events
* Custom consumers for data routing
* Designed for scripting and server environments

## Resources

* [Full API Reference](http://mixpanel.github.io/mixpanel-ruby)
* [GitHub Repository](https://github.com/mixpanel/mixpanel-ruby)
* [Example Script](https://github.com/mixpanel/mixpanel-ruby/tree/master/demo)