0
# People Analytics
1

2
People Analytics functionality enables comprehensive user profile management with property operations, list management, and revenue tracking. All operations create profiles if they don't exist and support extensive property manipulation.
3

4
## Capabilities
5

6
### Profile Property Management
7

8
Set and manage user profile properties with support for conditional updates and one-time property setting.
9

10
```python { .api }
11
def people_set(distinct_id: str, properties: dict, meta: dict = None):
12
    """
13
    Set properties of a people record.
14

15
    Parameters:
16
    - distinct_id (str): The profile to update
17
    - properties (dict): Properties to set
18
    - meta (dict, optional): Overrides Mixpanel special properties
19

20
    Returns:
21
    None
22

23
    Note: If the profile does not exist, creates a new profile with these properties.
24
    """
25

26
def people_set_once(distinct_id: str, properties: dict, meta: dict = None):
27
    """
28
    Set properties of a people record if they are not already set.
29

30
    Parameters:
31
    - distinct_id (str): The profile to update
32
    - properties (dict): Properties to set
33
    - meta (dict, optional): Overrides Mixpanel special properties
34

35
    Returns:
36
    None
37

38
    Note: Properties that already exist will not be overwritten. Creates profile if it doesn't exist.
39
    """
40
```
41

42
**Usage Example:**
43

44
```python
45
from mixpanel import Mixpanel
46

47
mp = Mixpanel("YOUR_PROJECT_TOKEN")
48

49
# Set user profile properties
50
mp.people_set("user_123", {
51
    "$first_name": "John",
52
    "$last_name": "Doe",
53
    "$email": "john@example.com",
54
    "$phone": "+1234567890",
55
    "plan": "premium",
56
    "signup_date": "2024-01-15",
57
    "preferences": "email_notifications"
58
})
59

60
# Set properties only if not already set
61
mp.people_set_once("user_123", {
62
    "first_login": "2024-01-15",
63
    "signup_source": "organic",
64
    "initial_plan": "free"
65
})
66
```
67

68
### Numerical Operations
69

70
Increment or decrement numerical properties with support for multiple properties in a single operation.
71

72
```python { .api }
73
def people_increment(distinct_id: str, properties: dict, meta: dict = None):
74
    """
75
    Increment/decrement numerical properties of a people record.
76

77
    Parameters:
78
    - distinct_id (str): The profile to update
79
    - properties (dict): Properties to increment/decrement; values should be numeric
80
    - meta (dict, optional): Overrides Mixpanel special properties
81

82
    Returns:
83
    None
84

85
    Note: Nonexistent properties default to zero. Negative values decrement the property.
86
    """
87
```
88

89
**Usage Example:**
90

91
```python
92
# Increment user engagement metrics
93
mp.people_increment("user_123", {
94
    "page_views": 1,
95
    "session_count": 1,
96
    "total_time_spent": 300,  # seconds
97
    "feature_usage": 1
98
})
99

100
# Decrement credits or points
101
mp.people_increment("user_456", {
102
    "credits_remaining": -10,
103
    "points_balance": -50
104
})
105
```
106

107
### List Property Management
108

109
Manage list-style properties with append, union, and remove operations for handling collections of values.
110

111
```python { .api }
112
def people_append(distinct_id: str, properties: dict, meta: dict = None):
113
    """
114
    Append to the list associated with a property.
115

116
    Parameters:
117
    - distinct_id (str): The profile to update
118
    - properties (dict): Properties to append
119
    - meta (dict, optional): Overrides Mixpanel special properties
120

121
    Returns:
122
    None
123

124
    Note: Appending to nonexistent properties results in a list with a single element.
125
    """
126

127
def people_union(distinct_id: str, properties: dict, meta: dict = None):
128
    """
129
    Merge the values of a list associated with a property.
130

131
    Parameters:
132
    - distinct_id (str): The profile to update
133
    - properties (dict): Properties to merge
134
    - meta (dict, optional): Overrides Mixpanel special properties
135

136
    Returns:
137
    None
138

139
    Note: Duplicate values are ignored when merging lists.
140
    """
141

142
def people_remove(distinct_id: str, properties: dict, meta: dict = None):
143
    """
144
    Permanently remove a value from the list associated with a property.
145

146
    Parameters:
147
    - distinct_id (str): The profile to update
148
    - properties (dict): Properties to remove
149
    - meta (dict, optional): Overrides Mixpanel special properties
150

151
    Returns:
152
    None
153
    """
154
```
155

156
**Usage Example:**
157

158
```python
159
# Append items to user's lists
160
mp.people_append("user_123", {
161
    "favorite_categories": "electronics",
162
    "purchased_items": "laptop_pro_001",
163
    "viewed_pages": "/product/smartphone"
164
})
165

166
# Union multiple values (no duplicates)
167
mp.people_union("user_123", {
168
    "interests": ["technology", "gaming", "music"],
169
    "tags": ["vip", "early_adopter"]
170
})
171

172
# Remove specific values from lists
173
mp.people_remove("user_123", {
174
    "cart_items": "item_to_remove",
175
    "notifications": "promotional_emails"
176
})
177
```
178

179
### Property Removal
180

181
Remove properties entirely from user profiles.
182

183
```python { .api }
184
def people_unset(distinct_id: str, properties: list, meta: dict = None):
185
    """
186
    Permanently remove properties from a people record.
187

188
    Parameters:
189
    - distinct_id (str): The profile to update
190
    - properties (list): Property names to remove
191
    - meta (dict, optional): Overrides Mixpanel special properties
192

193
    Returns:
194
    None
195
    """
196
```
197

198
**Usage Example:**
199

200
```python
201
# Remove specific properties from user profile
202
mp.people_unset("user_123", [
203
    "temp_property",
204
    "outdated_preference",
205
    "old_email"
206
])
207
```
208

209
### Revenue Tracking
210

211
Track revenue and transaction data with comprehensive transaction history management.
212

213
```python { .api }
214
def people_track_charge(distinct_id: str, amount: float, properties: dict = None, meta: dict = None):
215
    """
216
    Track a charge on a people record.
217

218
    Parameters:
219
    - distinct_id (str): The profile with which to associate the charge
220
    - amount (float): Number of dollars charged
221
    - properties (dict, optional): Extra properties related to the transaction
222
    - meta (dict, optional): Overrides Mixpanel special properties
223

224
    Returns:
225
    None
226

227
    Note: Charges appear in the Mixpanel revenue report.
228
    """
229

230
def people_clear_charges(distinct_id: str, meta: dict = None):
231
    """
232
    Permanently clear all charges on a people record.
233

234
    Parameters:
235
    - distinct_id (str): The profile whose charges will be cleared
236
    - meta (dict, optional): Overrides Mixpanel special properties
237

238
    Returns:
239
    None
240
    """
241
```
242

243
**Usage Example:**
244

245
```python
246
# Track a purchase with transaction details
247
mp.people_track_charge("user_123", 99.99, {
248
    "product_name": "Premium Plan",
249
    "plan_duration": "monthly",
250
    "currency": "USD",
251
    "payment_method": "credit_card",
252
    "transaction_id": "txn_abc123"
253
})
254

255
# Track refund (negative amount)
256
mp.people_track_charge("user_456", -29.99, {
257
    "refund_reason": "customer_request",
258
    "original_transaction": "txn_def456"
259
})
260

261
# Clear all transaction history
262
mp.people_clear_charges("user_789")
263
```
264

265
### Profile Deletion
266

267
Permanently delete user profiles and all associated data.
268

269
```python { .api }
270
def people_delete(distinct_id: str, meta: dict = None):
271
    """
272
    Permanently delete a people record.
273

274
    Parameters:
275
    - distinct_id (str): The profile to delete
276
    - meta (dict, optional): Overrides Mixpanel special properties
277

278
    Returns:
279
    None
280

281
    Note: This action is irreversible and will remove all profile data.
282
    """
283
```
284

285
**Usage Example:**
286

287
```python
288
# Delete user profile (GDPR compliance, account deletion, etc.)
289
mp.people_delete("user_to_delete")
290
```
291

292
### Generic Profile Updates
293

294
Send custom profile update messages for advanced use cases or new Mixpanel features.
295

296
```python { .api }
297
def people_update(message: dict, meta: dict = None):
298
    """
299
    Send a generic update to Mixpanel people analytics.
300

301
    Parameters:
302
    - message (dict): The message to send, must include '$distinct_id' and operation keys like '$set', '$add', etc.
303
    - meta (dict, optional): Overrides Mixpanel special properties
304

305
    Returns:
306
    None
307

308
    Note: Callers are responsible for formatting the message according to Mixpanel's user profiles documentation.
309
    The message should follow the structure: {'$distinct_id': 'user_id', '$set': {...}, '$token': 'auto-added', '$time': 'auto-added'}
310
    """
311
```
312

313
**Usage Example:**
314

315
```python
316
# Custom profile update using the generic method
317
mp.people_update({
318
    '$distinct_id': 'user_123',
319
    '$set': {'custom_field': 'value'},
320
    '$add': {'score': 10}
321
})
322

323
# Advanced usage with multiple operations
324
mp.people_update({
325
    '$distinct_id': 'user_456',
326
    '$set': {'status': 'premium'},
327
    '$unset': ['temp_field'],
328
    '$append': {'actions': 'upgraded'}
329
})
330
```
331

332
## Best Practices
333

334
### Profile Management
335

336
- Use consistent distinct_id values across events and profile updates
337
- Leverage Mixpanel's special properties (prefixed with $) for enhanced functionality
338
- Set meaningful profile properties that aid in user segmentation and analysis
339

340
### Revenue Tracking
341

342
- Always use the appropriate currency and include transaction metadata
343
- Track refunds as negative amounts with clear reasoning
344
- Maintain transaction history for audit and analysis purposes
345

346
### Data Privacy
347

348
- Implement profile deletion for GDPR compliance and user privacy requests
349
- Be cautious with sensitive data in profile properties
350
- Use people_unset to remove outdated or sensitive profile information