Python

Contents: [ Installing the Library , Sending Events , Combining Anonymous and Identifiable User Data , Storing User Profiles , Group Analytics , Tracking Revenue , Scaling your Server-Side Tracking ]
[NOTE , Setting Profile Properties, NOTE , Appending to List Properties, Other Types of Profile Updates, Creating a Group Key, Sending Group Identifiers With Events, Adding Group Identifiers to Individual Users, Creating Group Profiles, Setting Group Properties, set, set once, unset, remove, union, delete, update]

Visit the Dev Docs

A better version of this page exists at https://developer.mixpanel.com/docs/python.

The Mixpanel Python library is designed to be used for scripting, or in circumstances when a user isn't directly interacting with your application on the web or a mobile device.

Mixpanel also provides a powerful and easy to use client-side JavaScript library for web applications. This library offers platform-specific features and conveniences that can make Mixpanel implementations much simpler, and can scale naturally to an unlimited number of clients. The client-side JavaScript library is the preferred way to add Mixpanel to user-facing web applications.

Installing the Library

You can get the library using pip.

pip install mixpanel

Once the library is installed, use the Mixpanel library in your applications with:

import mixpanel

Sending Events

Mixpanel events are sent using an instance of the Mixpanel class.

You can instantiate an instance of Mixpanel with a String containing your Mixpanel project token. You can find your project token in the settings dialog of the Mixpanel web application.

Once you have an instance of the tracker, you can track events by providing the event name and properties to Mixpanel.track().

from mixpanel import Mixpanel

mp = Mixpanel(PROJECT_TOKEN)

# Tracks an event, 'Sent Message',
# with distinct_id user_id
mp.track(user_id, 'Sent Message')

# You can also include properties to describe
# the circumstances of the event
mp.track(user_id, 'Plan Upgraded', {
    'Old Plan': 'Business',
    'New Plan': 'Premium'
})

Mixpanel can determine default geolocation data ($city, $region, mp_country_code) using the IP address on the incoming request. As all server-side calls will likely originate from the same IP (that is, the IP of your server), this can have the unintended effect of setting the location of all of your users to the location of your datacenter. Read about best practices for geolocation with server-side implementations.

Combining Anonymous and Identifiable User Data

It's important to send the same distinct_id with each event that an individual user triggers. Events recorded with different distinct_ids will be treated in Mixpanel as if they were performed by different users.

There are times when it can be convenient to start referring to a user by a different identifier in your implementation. The most common case is after registration, when a user switches from being an anonymous user (with an anonymous distinct_id) to an authenticated user with an (authenticated id). In this case, you can create an alias() for the user to keep the distinct_id consistent. An alias is a string stored in a Mixpanel lookup table that is associated with an anonymous distinct_id. Once written, aliases are not editable. Any data sent to Mixpanel with an alias as the distinct_id will be remapped and written to disk using the alias's corresponding anonymous distinct_id. This allows you to start identifying a user by an authenticated id without changing the distinct_id that is ultimately written in Mixpanel.

# This call will send a request to Mixpanel to
# associate all future events with new_internal_id
# with existing events associated with
# original_anonymous_id
mp.alias(new_internal_id, original_anonymous_id)

Typically, you will call Mixpanel.alias() once in a user's lifetime, when the user first signs up and is assigned an internal id.

NOTE

Aliases don't take effect until the alias request hits the Mixpanel server. Because of this, you'll need to take special care if you're using Mixpanel.alias() with a custom consumer, so you can be sure that your alias message arrives before any events or updates associated with the new alias.

Storing User Profiles

In addition to events, you can send user profile updates to Mixpanel. Mixpanel can maintain a profile of each of your users, storing information you know about them. An update is a message that changes the properties of a user profile.

You can use profiles to explore and segment users by who they are, rather than what they did. You can also use profiles to send messages, such as emails, SMS, or push notifications.

Mixpanel determines default geolocation data ($city, $region, mp_country_code) using the IP address on the incoming request. As all server-side calls will likely originate from the same IP (that is, the IP of your server), this can have the unintended effect of setting the location of all of your users to the location of your datacenter. Read about best practices for geolocation with server-side implementations.

Setting Profile Properties

Instances of Mixpanel have a method to send profile updates.

# create or update a profile with First Name, Last Name,
# E-Mail Address, Phone Number, and Favorite Color
# without updating geolocation data or $last_seen
mp.people_set('12345', {
    '$first_name'    : 'John',
    '$last_name'     : 'Doe',
    '$email'         : 'john.doe@example.com',
    '$phone'         : '5555555555',
    'Favorite Color' : 'red'
}, meta = {'$ignore_time' : 'true', '$ip' : 0})

This call to people_set() will change the value of properties on user 12345's profile. If there isn't a profile with distinct_id 12345 in Mixpanel already, a new profile will be created. If user 12345 already has has any of these properties set on their profile, the old values will be overwritten with the new ones.

NOTE

Pick your property names wisely. Once you've sent them to Mixpanel, there is no way to change them. Feel free to use capitalization and spaces in between words.
There are a few limitations:

  • Your property names should not begin with $ or mp_. These properties are reserved for special properties sent by Mixpanel.
  • Your property names cannot begin or end with a space as they will automatically be trimmed.
  • Your property names and values cannot be longer than 255 characters. In practice they should be much shorter than that. Property names get cut off by our user interface at about 20 characters.

Click here to see a list of Mixpanel's reserved user profile properties.

Appending to List Properties

Use people_append() to add an item to an existing list-valued property. The values you send with the append will be added to the end of the list for each named property. If the property doesn't exist, it will be created with a one element list as its value.

mp.people_append('12345', {
    'Favorite Fruits' : 'Apples'
})

Other Types of Profile Updates

There are a few other types of profile updates. You can get more information about them from the Mixpanel Library API Reference.

Group Analytics

Mixpanel Group Analytics allows behavioral data analysis by selected groups, as opposed to individual users.

Grouping by identifiers other than the distinct_id allows analysis at a company or group level when using Mixpanel analytics. Read this article to learn more about Group Analytics.

A group is identified by the group_key and group_id.

  • group_key is the property that connects event data for Group Analytics.
  • group_id is the identifier for a specific group.

If the property “Company” is chosen for Group Analytics, “Company” is the group_key, and “Mixpanel”, “Company A”, and “13254” are all potential group_id values.

A user can belong to multiple groups. All updates to a group operate on the group_key and group_id.

Creating a Group Key

You must reach out to your CSM to determine what event property you will use for the group_key in Group Analytics.

Sending Group Identifiers With Events

To send group identifiers with events, send the group_key as a property key and the group_id as the property value. The data type of the group_key property is a list, therefore you can add multiple values for a single user. It is also possible to pass only one value.

Mixpanel can group events by the group_id, similar to how events are grouped with the distinct_id. A group_id, however, is a group level identifier and not a user level identifier like the distinct_id.

Note that sending in a group_key and group_id as event properties does not add users to the group profile or assign group membership to the user's profile. Only events with your chosen group_key property set will be available for behavioral analysis at the group level. See the sections following the code example to learn how to add users to a group profile or add a group to the user's profile.

# Tracks an event named 'Plan Purchase',
# with the distinct_id as user_id and a 
# group_id = Company with a group_key = Mixpanel
mp.track(user_id, 'Plan Purchase', {'Plan Type' : 'Premium', 'Company' : 'mixpanel'})

Adding Group Identifiers to Individual Users

To connect group information to a user profile, include the group_key and group_id by sending the property as part of the people_set() call.

# Create or update a user profile with 'first name', 'last name',
# 'favorite color' properties, and a group_id = company
# with a group_key = Mixpanel
mp.people_set('12345', {
    '$first_name'    : 'John',
    '$last_name'     : 'Doe',
    'Favorite Color' : 'red',
    'Company'        : 'Mixpanel',
}, meta = {'$ignore_time' : 'true', '$ip' : 0})

Creating Group Profiles

It is possible to create a Group profile that is similar to a user profile. You must call group_set() to create a group profile. It is important to include the group_key, group_id, and at least one property so that the profile is not empty.

# Create a group profile with group_key = company,
# group_id = Mixpanel,
# and assign the property "company type" with value "Analytics"
# to the profile
mp.group_set('Company', 'mixpanel', {'Company Type': 'Analytics', '$name': 'Mixpanel'})

Setting Group Properties

You can add details to Group Profiles by adding properties to them.

You can set the property $name to populate the name field at the top of the group profile.

These operations are similar to the corresponding operations for user profile property updates.

set

group_set() updates or adds a property to a group. If the profile does not exist, it creates a new profile with the passed properties.

# Create a group profile with group_key = company,
# group_id = Mixpanel
# and assign the property "company type" with value "Analytics"
# to the profile
mp.group_set('Company', 'mixpanel', {'Company Type': 'Analytics', '$name': 'Mixpanel'})

set once

group_set_once() adds a property value to a group only if it has not been set before.

# Create a group profile with group_key = company,
# group_id = Mixpanel
# and assign the property "company type" with value "Analytics"
# to the profile only if it is not already set
mp.group_set_once('Company', 'mixpanel', {'Company Type': 'Analytics'})

unset

group_unset() unsets a specific property in the group.

# Permanently removes the group profile property "Company Type" 
mp.group_unset('Company', 'mixpanel', ['Company Type'])

remove

group_remove() removes a specific value in a list property.

# Add two values in a list to "Company Type" property
mp.group_set('Company', 'mixpanel', {'Company Type': ['Hardware', 'Analytics'], '$name': 'Mixpanel'})

# Remove "Hardware" from the list of values for "Company Type" 
mp.group_remove('Company', 'mixpanel', {'Company Type': 'Hardware'})

union

group_union() adds the specified values to a list property and ensures that those values only appear once.

# Merge "Funnels" and "Messages" values into existing "Features" list
mp.group_union('Company', 'mixpanel', {'Features': ['Funnels', 'Messages']})

delete

group_delete() permanently deletes a group profile.

# Delete the Mixpanel group profile
mp.group_delete('Company', 'Mixpanel')

update

group_update() sends a generic group profile update.

Callers are responsible for formatting the update message as documented in the Mixpanel HTTP specification. This method may be useful if you want to use very new or experimental features, but please use the other group_* methods where possible.

Tracking Revenue

Mixpanel makes it easy to analyze the revenue you make from individual customers. By associating charges with user profiles, you can compare revenue across different customer segments and calculate things like lifetime value.

You can track a single transaction with Mixpanel.people_track_charge(). Sending a message created with people_track_charge will add transactions to the individual user profile, which will also be reflected in the Mixpanel Revenue report.

# Records a charge of $9.99 from user '12345'
mp.people_track_charge('12345', 9.99)

# records a charge of $30.50 on the 2nd of January
mp.people_track_charge("12345", 30.50, {
    '$time': '2013-01-02T09:32:00'
})

Scaling your Server-Side Tracking

By default, the Mixpanel class sends a request to Mixpanel immediately for every tracking message or profile update. This is convenient for getting started quickly, but almost all server-side use of the Mixpanel library will eventually want to do the IO associated with tracking in a separate thread or process from the events being tracked.

The Mixpanel library provides the Consumer class for finer control of your tracking IO.

In addition to your token, the Mixpanel constructor takes an optional consumer argument. This argument, if provided, should be an object with a method named send(), that takes three arguments:

Argument
Type
Description

endpoint

string

Either the string 'events' for messages intended to go to the Mixpanel /track endpoint, the string 'people' for messages intended for the Mixpanel /people endpoint, or imports for event data sent to the /import endpoint.

json_message

string

A JSON message, encoded in a string, that can be used by the service at the named endpoint. The structure of meaningful JSON messages is described in the Mixpanel HTTP API reference.

api_key

string

Defaults to None. Include the project API key if the endpoint requires a key, such as “imports”, or the consumer is buffered.

You can use the send() method of your Consumer to send your messages to a separate process, add them to a queue, or write them to a log.

class LoggingConsumer(object):
    def __init__(self):
        self.mp_log = open("MIXPANEL_LOG.txt", "w+")

    def send(self, endpoint, json_message, api_key=None):
        self.mp_log.write("{0}::{1}\n".format(endpoint, json_message))

# Whenever you track with logging_mp, your messages will
# be written to MIXPANEL_LOG.txt rather than being sent
# to the Mixpanel servers
logging_mp = Mixpanel(YOUR_TOKEN, LoggingConsumer())

Using a custom consumer is most powerful when you combine it with the existing consumers in the mixpanel module.

import mixpanel

# The default Mixpanel consumer will take
# endpoints and messages and send them to Mixpanel
consumer = mixpanel.Consumer()
with open("MIXPANEL_LOG.txt", "r+") as read_log:
    for line in read_log:
        (endpoint, message) = line.split('::', 1)
        consumer.send(endpoint, message)

The combination of package-provided consumers and your own custom consumer makes it simple to use the Mixpanel library with a queueing system. For example:

# In your time-sensitive process
class EnqueueingConsumer(object):
    def send(self, endpoint, json_message, api_key=None):
        YOUR_QUEUE.set('mixpanel_queue', JSON.dumps([ endpoint, json_message ]))

mp = mixpanel.Mixpanel(YOUR_TOKEN, EnqueueingConsumer())

# Track just like you would in any other situation
mp.track(user_id, 'Sent Message')
mp.people_increment(user_id, {
    'Messages Sent': 1
})

# In a worker process on another machine
consumer = mixpanel.Consumer()
while True:
    job = YOUR_QUEUE.get('mixpanel_queue')
    consumer.send(*JSON.loads(job))

For applications where overall load is light, but the latency of a particular process is an issue, you can also use mixpanel-python-async, a third party consumer that processes tracking requests efficiently in a separate thread.

Is this article helpful?

Comments

0 comments

Please sign in to leave a comment.