= mixpanel-ruby: The official Mixpanel Ruby library

mixpanel-ruby is a library for tracking events and sending \Mixpanel profile updates to \Mixpanel from your ruby applications.

== Installation

gem install mixpanel-ruby

== Getting Started

require 'mixpanel-ruby'

tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)

# Track an event on behalf of user "User1"
tracker.track('User1', 'A Mixpanel Event')

# Send an update to User1's profile
tracker.people.set('User1', {
    '$first_name' => 'David',
    '$last_name' => 'Bowie',
    'Best Album' => 'The Rise and Fall of Ziggy Stardust and the Spiders from Mars'
})

The primary class you will use to track events is Mixpanel::Tracker. An instance of Mixpanel::Tracker is enough to send events directly to \Mixpanel, and get you integrated right away.

== Additional Information

For more information please visit:

• Our Ruby API Integration page[https://mixpanel.com/help/reference/ruby#introduction]
• The usage demo[https://github.com/mixpanel/mixpanel-ruby/tree/master/demo]
• The documentation[http://mixpanel.github.io/mixpanel-ruby/]

The official Mixpanel gem is built with simplicity and broad applicability in mind, but there are also third party Ruby libraries that can work with the library to provide useful features in common situations, and support different development points of view.

In particular, for Rails apps, the following projects are currently actively maintained:

• MetaEvents[https://github.com/swiftype/meta_events]
• Mengpaneel[https://github.com/DouweM/mengpaneel]

== Changes

== 2.2.2

• Add Group Analytics support with Mixpanel::Groups

== 2.2.1

• Fix buffer clearing on partially successful writes in BufferedConsumer.

== 2.2.0

• Add Mixpanel::ErrorHandler to simplify custom error handling.
• Modify Mixpanel::People#fix_property_dates to handle ActiveSupport::TimeWithZone.
• Increase open and ssl timeouts from 2s to 10s.
• Fix Doc inconsistancy: always pass token on Mixpanel::tracker.new.

== 2.1.0

• Add Mixpanel::Tracker#generate_tracking_url, which generates {pixel tracking urls}[https://mixpanel.com/docs/api-documentation/pixel-based-event-tracking].
• Rescue JSONErrors in the consumer and raise Mixpanel::ServerError in Mixpanel::Consumer#send!.
• Make it clear how to import events with custom timestamp.
• Update dependancies in gemspec

== 2.0.1

• Add Deprecated version of Mixpanel::BufferedConsumer#send

== 2.0.0

• Raise mixpanel server and connection errors in Mixpanel::Consumer.
• All public methods in Mixpanel::Event, Mixpanel::People, and subsequently Mixpanel::Tracker rescue Mixpanel errors and return false in the case of an error, return true otherwise
• Deprecate Mixpanel::Consumer#send, replace with Mixpanel::Consumer#send!
• Require ruby version minimum of 2.0.0

== 1.4.0

• Allow unset to unset multiple properties

== 1.3.0

• Added Consumer#request method, demo with Faraday integration

== 1.2.0

• All objects with a "strftime" method will be formatted as dates in people updates.

== 1.1.0

• The default consumer now sends requests (and expects responses) in verbose, JSON mode, which may improve error reporting.

=== 1.0.2

• Allow ip and optional_params arguments to be accepted by all Mixpanel::People methods (except #destroy_user)

=== 1.0.1

• Compatibility with earlier versions of ruby. Library development will continue to target 1.9, so later versions may not be compatible with Ruby 1.8, but we love patches!

=== 1.0.0

• tracker#import added
• Change to internal tracking message format. Messages written by earlier versions of the library will not work with 1.0.0 consumer classes.
• alias bugfixed
• Fixes to tests to allow for different timezones
• Support for optional/experimental people api properties in people calls