/
Mixpanel.h
811 lines (608 loc) · 21.7 KB
/
Mixpanel.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
#import <Foundation/Foundation.h>
#import <UIKit/UIKit.h>
#import <Mixpanel/MixpanelPeople.h>
#define MIXPANEL_LIMITED_SUPPORT (defined(MIXPANEL_APP_EXTENSION) || defined(MIXPANEL_TVOS_EXTENSION))
@class MixpanelPeople, MPSurvey;
@protocol MixpanelDelegate;
NS_ASSUME_NONNULL_BEGIN
/*!
@class
Mixpanel API.
@abstract
The primary interface for integrating Mixpanel with your app.
@discussion
Use the Mixpanel class to set up your project and track events in Mixpanel
Engagement. It now also includes a <code>people</code> property for accessing
the Mixpanel People API.
<pre>
// Initialize the API
Mixpanel *mixpanel = [Mixpanel sharedInstanceWithToken:@"YOUR API TOKEN"];
// Track an event in Mixpanel Engagement
[mixpanel track:@"Button Clicked"];
// Set properties on a user in Mixpanel People
[mixpanel identify:@"CURRENT USER DISTINCT ID"];
[mixpanel.people set:@"Plan" to:@"Premium"];
</pre>
For more advanced usage, please see the <a
href="https://mixpanel.com/docs/integration-libraries/iphone">Mixpanel iPhone
Library Guide</a>.
*/
@interface Mixpanel : NSObject
#pragma mark Properties
/*!
@property
@abstract
Accessor to the Mixpanel People API object.
@discussion
See the documentation for MixpanelDelegate below for more information.
*/
@property (atomic, readonly, strong) MixpanelPeople *people;
/*!
@property
@abstract
The distinct ID of the current user.
@discussion
A distinct ID is a string that uniquely identifies one of your users.
Typically, this is the user ID from your database. By default, we'll use a
hash of the MAC address of the device. To change the current distinct ID,
use the <code>identify:</code> method.
*/
@property (atomic, readonly, copy) NSString *distinctId;
/*!
@property
@abstract
Current user's name in Mixpanel Streams.
*/
@property (nullable, atomic, copy) NSString *nameTag;
/*!
@property
@abstract
The base URL used for Mixpanel API requests.
@discussion
Useful if you need to proxy Mixpanel requests. Defaults to
https://api.mixpanel.com.
*/
@property (nonatomic, copy) NSString *serverURL;
/*!
@property
@abstract
Flush timer's interval.
@discussion
Setting a flush interval of 0 will turn off the flush timer.
*/
@property (atomic) NSUInteger flushInterval;
/*!
@property
@abstract
Control whether the library should flush data to Mixpanel when the app
enters the background.
@discussion
Defaults to YES. Only affects apps targeted at iOS 4.0, when background
task support was introduced, and later.
*/
@property (atomic) BOOL flushOnBackground;
/*!
@property
@abstract
Controls whether to show spinning network activity indicator when flushing
data to the Mixpanel servers.
@discussion
Defaults to YES.
*/
@property (atomic) BOOL showNetworkActivityIndicator;
/*!
@property
@abstract
Controls whether to automatically check for surveys for the
currently identified user when the application becomes active.
@discussion
Defaults to YES. Will fire a network request on
<code>applicationDidBecomeActive</code> to retrieve a list of valid surveys
for the currently identified user.
*/
@property (atomic) BOOL checkForSurveysOnActive;
/*!
@property
@abstract
Controls whether to automatically show a survey for the
currently identified user when the application becomes active.
@discussion
Defaults to YES. This will only show a survey if
<code>checkForSurveysOnActive</code> is also set to YES, and the
survey check retrieves at least 1 valid survey for the currently
identified user.
*/
@property (atomic) BOOL showSurveyOnActive;
/*!
@property
@abstract
Determines whether a valid survey is available to show to the user.
@discussion
If we haven't fetched the surveys yet, this will return NO. Otherwise
it will return yes if there is at least one survey available.
*/
@property (atomic, readonly) BOOL isSurveyAvailable;
/*!
@property
@abstract
Returns a list of available surveys. You can then call <code>showSurveyWithID:</code>
and pass in <code>survey.ID</code>
@discussion
If we haven't fetched the surveys yet, this will return nil.
*/
@property (atomic, readonly) NSArray<MPSurvey *> *availableSurveys;
/*!
@property
@abstract
Controls whether to automatically check for notifications for the
currently identified user when the application becomes active.
@discussion
Defaults to YES. Will fire a network request on
<code>applicationDidBecomeActive</code> to retrieve a list of valid notifications
for the currently identified user.
*/
@property (atomic) BOOL checkForNotificationsOnActive;
/*!
@property
@abstract
Controls whether to automatically check for A/B test variants for the
currently identified user when the application becomes active.
@discussion
Defaults to YES. Will fire a network request on
<code>applicationDidBecomeActive</code> to retrieve a list of valid variants
for the currently identified user.
*/
@property (atomic) BOOL checkForVariantsOnActive;
/*!
@property
@abstract
Controls whether to automatically check for and show in-app notifications
for the currently identified user when the application becomes active.
@discussion
Defaults to YES.
*/
@property (atomic) BOOL showNotificationOnActive;
/*!
@property
@abstract
Controls whether to automatically send the client IP Address as part of
event tracking. With an IP address, geo-location is possible down to neighborhoods
within a city, although the Mixpanel Dashboard will just show you city level location
specificity. For privacy reasons, you may be in a situation where you need to forego
effectively having access to such granular location information via the IP Address.
@discussion
Defaults to YES.
*/
@property (atomic) BOOL useIPAddressForGeoLocation;
/*!
@property
@abstract
Controls whether to enable the visual A/B test designer on mixpanel.com, you will
be unable to edit A/B tests with this disabled, however previously created A/B
tests and their variants will still be delivered.
@discussion
Defaults to YES.
*/
@property (atomic) BOOL enableABTestDesigner;
/*!
@property
@abstract
Determines the time, in seconds, that a mini notification will remain on
the screen before automatically hiding itself.
@discussion
Defaults to 6.0.
*/
@property (atomic) CGFloat miniNotificationPresentationTime;
/*!
@property
@abstract
If set, determines the background color of mini notifications.
@discussion
If this isn't set, we default to either the color of the UINavigationBar of the top
UINavigationController that is showing when the notification is presented, the
UINavigationBar default color for the app or the UITabBar default color.
*/
@property (atomic, strong, nullable) UIColor *miniNotificationBackgroundColor;
/*!
@property
@abstract
The a MixpanelDelegate object that can be used to assert fine-grain control
over Mixpanel network activity.
@discussion
Using a delegate is optional. See the documentation for MixpanelDelegate
below for more information.
*/
@property (atomic, weak) id<MixpanelDelegate> delegate; // allows fine grain control over uploading (optional)
#pragma mark Tracking
/*!
@method
@abstract
Initializes and returns a singleton instance of the API.
@discussion
If you are only going to send data to a single Mixpanel project from your app,
as is the common case, then this is the easiest way to use the API. This
method will set up a singleton instance of the <code>Mixpanel</code> class for
you using the given project token. When you want to make calls to Mixpanel
elsewhere in your code, you can use <code>sharedInstance</code>.
<pre>
[Mixpanel sharedInstance] track:@"Something Happened"]];
</pre>
If you are going to use this singleton approach,
<code>sharedInstanceWithToken:</code> <b>must be the first call</b> to the
<code>Mixpanel</code> class, since it performs important initializations to
the API.
@param apiToken your project token
*/
+ (Mixpanel *)sharedInstanceWithToken:(NSString *)apiToken;
/*!
@method
@abstract
Initializes a singleton instance of the API, uses it to track launchOptions information,
and then returns it.
@discussion
This is the preferred method for creating a sharedInstance with a mixpanel
like above. With the launchOptions parameter, Mixpanel can track referral
information created by push notifications.
@param apiToken your project token
@param launchOptions your application delegate's launchOptions
*/
+ (Mixpanel *)sharedInstanceWithToken:(NSString *)apiToken launchOptions:(nullable NSDictionary *)launchOptions;
/*!
@method
@abstract
Returns the previously instantiated singleton instance of the API.
@discussion
The API must be initialized with <code>sharedInstanceWithToken:</code> before
calling this class method.
*/
+ (Mixpanel *)sharedInstance;
/*!
@method
@abstract
Initializes an instance of the API with the given project token.
@discussion
Returns the a new API object. This allows you to create more than one instance
of the API object, which is convenient if you'd like to send data to more than
one Mixpanel project from a single app. If you only need to send data to one
project, consider using <code>sharedInstanceWithToken:</code>.
@param apiToken your project token
@param launchOptions optional app delegate launchOptions
@param flushInterval interval to run background flushing
*/
- (instancetype)initWithToken:(NSString *)apiToken launchOptions:(nullable NSDictionary *)launchOptions andFlushInterval:(NSUInteger)flushInterval;
/*!
@method
@abstract
Initializes an instance of the API with the given project token.
@discussion
Supports for the old initWithToken method format but really just passes
launchOptions to the above method as nil.
@param apiToken your project token
@param flushInterval interval to run background flushing
*/
- (instancetype)initWithToken:(NSString *)apiToken andFlushInterval:(NSUInteger)flushInterval;
/*!
@property
@abstract
Sets the distinct ID of the current user.
@discussion
As of version 2.3.1, Mixpanel will choose a default distinct ID based on
whether you are using the AdSupport.framework or not.
If you are not using the AdSupport Framework (iAds), then we use the
<code>[UIDevice currentDevice].identifierForVendor</code> (IFV) string as the
default distinct ID. This ID will identify a user across all apps by the same
vendor, but cannot be used to link the same user across apps from different
vendors.
If you are showing iAds in your application, you are allowed use the iOS ID
for Advertising (IFA) to identify users. If you have this framework in your
app, Mixpanel will use the IFA as the default distinct ID. If you have
AdSupport installed but still don't want to use the IFA, you can define the
<code>MIXPANEL_NO_IFA</code> preprocessor flag in your build settings, and
Mixpanel will use the IFV as the default distinct ID.
If we are unable to get an IFA or IFV, we will fall back to generating a
random persistent UUID.
For tracking events, you do not need to call <code>identify:</code> if you
want to use the default. However, <b>Mixpanel People always requires an
explicit call to <code>identify:</code></b>. If calls are made to
<code>set:</code>, <code>increment</code> or other <code>MixpanelPeople</code>
methods prior to calling <code>identify:</code>, then they are queued up and
flushed once <code>identify:</code> is called.
If you'd like to use the default distinct ID for Mixpanel People as well
(recommended), call <code>identify:</code> using the current distinct ID:
<code>[mixpanel identify:mixpanel.distinctId]</code>.
@param distinctId string that uniquely identifies the current user
*/
- (void)identify:(NSString *)distinctId;
/*!
@method
@abstract
Tracks an event.
@param event event name
*/
- (void)track:(NSString *)event;
/*!
@method
@abstract
Tracks an event with properties.
@discussion
Properties will allow you to segment your events in your Mixpanel reports.
Property keys must be <code>NSString</code> objects and values must be
<code>NSString</code>, <code>NSNumber</code>, <code>NSNull</code>,
<code>NSArray</code>, <code>NSDictionary</code>, <code>NSDate</code> or
<code>NSURL</code> objects. If the event is being timed, the timer will
stop and be added as a property.
@param event event name
@param properties properties dictionary
*/
- (void)track:(NSString *)event properties:(nullable NSDictionary *)properties;
/*!
@method
@abstract
Track a push notification using its payload sent from Mixpanel.
@discussion
To simplify user interaction tracking and a/b testing, Mixpanel
automatically sends IDs for the relevant notification and a/b variants
of each push. This method parses the standard payload and queues a
track call using this information.
@param userInfo remote notification payload dictionary
*/
- (void)trackPushNotification:(NSDictionary *)userInfo;
/*!
@method
@abstract
Registers super properties, overwriting ones that have already been set.
@discussion
Super properties, once registered, are automatically sent as properties for
all event tracking calls. They save you having to maintain and add a common
set of properties to your events. Property keys must be <code>NSString</code>
objects and values must be <code>NSString</code>, <code>NSNumber</code>,
<code>NSNull</code>, <code>NSArray</code>, <code>NSDictionary</code>,
<code>NSDate</code> or <code>NSURL</code> objects.
@param properties properties dictionary
*/
- (void)registerSuperProperties:(NSDictionary *)properties;
/*!
@method
@abstract
Registers super properties without overwriting ones that have already been
set.
@discussion
Property keys must be <code>NSString</code> objects and values must be
<code>NSString</code>, <code>NSNumber</code>, <code>NSNull</code>,
<code>NSArray</code>, <code>NSDictionary</code>, <code>NSDate</code> or
<code>NSURL</code> objects.
@param properties properties dictionary
*/
- (void)registerSuperPropertiesOnce:(NSDictionary *)properties;
/*!
@method
@abstract
Registers super properties without overwriting ones that have already been set
unless the existing value is equal to defaultValue.
@discussion
Property keys must be <code>NSString</code> objects and values must be
<code>NSString</code>, <code>NSNumber</code>, <code>NSNull</code>,
<code>NSArray</code>, <code>NSDictionary</code>, <code>NSDate</code> or
<code>NSURL</code> objects.
@param properties properties dictionary
@param defaultValue overwrite existing properties that have this value
*/
- (void)registerSuperPropertiesOnce:(NSDictionary *)properties defaultValue:(nullable id)defaultValue;
/*!
@method
@abstract
Removes a previously registered super property.
@discussion
As an alternative to clearing all properties, unregistering specific super
properties prevents them from being recorded on future events. This operation
does not affect the value of other super properties. Any property name that is
not registered is ignored.
Note that after removing a super property, events will show the attribute as
having the value <code>undefined</code> in Mixpanel until a new value is
registered.
@param propertyName array of property name strings to remove
*/
- (void)unregisterSuperProperty:(NSString *)propertyName;
/*!
@method
@abstract
Clears all currently set super properties.
*/
- (void)clearSuperProperties;
/*!
@method
@abstract
Returns the currently set super properties.
*/
- (NSDictionary *)currentSuperProperties;
/*!
@method
@abstract
Starts a timer that will be stopped and added as a property when a
corresponding event is tracked.
@discussion
This method is intended to be used in advance of events that have
a duration. For example, if a developer were to track an "Image Upload" event
she might want to also know how long the upload took. Calling this method
before the upload code would implicitly cause the <code>track</code>
call to record its duration.
<pre>
// begin timing the image upload
[mixpanel timeEvent:@"Image Upload"];
// upload the image
[self uploadImageWithSuccessHandler:^{
// track the event
[mixpanel track:@"Image Upload"];
}];
</pre>
@param event a string, identical to the name of the event that will be tracked
*/
- (void)timeEvent:(NSString *)event;
/*!
@method
@abstract
Clears all current event timers.
*/
- (void)clearTimedEvents;
/*!
@method
@abstract
Clears all stored properties and distinct IDs. Useful if your app's user logs out.
*/
- (void)reset;
/*!
@method
@abstract
Uploads queued data to the Mixpanel server.
@discussion
By default, queued data is flushed to the Mixpanel servers every minute (the
default for <code>flushInterval</code>), and on background (since
<code>flushOnBackground</code> is on by default). You only need to call this
method manually if you want to force a flush at a particular moment.
*/
- (void)flush;
/*!
@method
@abstract
Calls flush, then optionally archives and calls a handler when finished.
@discussion
When calling <code>flush</code> manually, it is sometimes important to verify
that the flush has finished before further action is taken. This is
especially important when the app is in the background and could be suspended
at any time if protocol is not followed. Delegate methods like
<code>application:didReceiveRemoteNotification:fetchCompletionHandler:</code>
are called when an app is brought to the background and require a handler to
be called when it finishes.
*/
- (void)flushWithCompletion:(nullable void (^)())handler;
/*!
@method
@abstract
Writes current project info, including distinct ID, super properties and pending event
and People record queues to disk.
@discussion
This state will be recovered when the app is launched again if the Mixpanel
library is initialized with the same project token. <b>You do not need to call
this method</b>. The library listens for app state changes and handles
persisting data as needed. It can be useful in some special circumstances,
though, for example, if you'd like to track app crashes from main.m.
*/
- (void)archive;
/*!
@method
@abstract
Creates a distinct_id alias from alias to original id.
@discussion
This method is used to map an identifier called an alias to the existing Mixpanel
distinct id. This causes all events and people requests sent with the alias to be
mapped back to the original distinct id. The recommended usage pattern is to call
both createAlias: and identify: when the user signs up, and only identify: (with
their new user ID) when they log in. This will keep your signup funnels working
correctly.
<pre>
// This makes the current ID (an auto-generated GUID)
// and 'Alias' interchangeable distinct ids.
[mixpanel createAlias:@"Alias"
forDistinctID:mixpanel.distinctId];
// You must call identify if you haven't already
// (e.g., when your app launches).
[mixpanel identify:mixpanel.distinctId];
</pre>
@param alias the new distinct_id that should represent original
@param distinctID the old distinct_id that alias will be mapped to
*/
- (void)createAlias:(NSString *)alias forDistinctID:(NSString *)distinctID;
- (NSString *)libVersion;
+ (NSString *)libVersion;
#if !MIXPANEL_LIMITED_SUPPORT
#pragma mark - Mixpanel Surveys
/*!
@method
@abstract
Shows the survey with the given name.
@discussion
This method allows you to explicitly show a named survey at the time of your choosing.
*/
- (void)showSurveyWithID:(NSUInteger)ID;
/*!
@method
@abstract
Show a survey if one is available.
@discussion
This method allows you to display the first available survey targeted to the currently
identified user at the time of your choosing. You would typically pair this with
setting <code>showSurveyOnActive = NO;</code> so that the survey won't show automatically.
*/
- (void)showSurvey;
#pragma mark - Mixpanel Notifications
/*!
@method
@abstract
Shows the notification of the given id.
@discussion
You do not need to call this method on the main thread.
*/
- (void)showNotificationWithID:(NSUInteger)ID;
/*!
@method
@abstract
Shows a notification with the given type if one is available.
@discussion
You do not need to call this method on the main thread.
@param type The type of notification to show, either @"mini", or @"takeover"
*/
- (void)showNotificationWithType:(NSString *)type;
/*!
@method
@abstract
Shows a notification if one is available.
@discussion
You do not need to call this method on the main thread.
*/
- (void)showNotification;
#pragma mark - Mixpanel A/B Testing
/*!
@method
@abstract
Join any experiments (A/B tests) that are available for the current user.
@discussion
Mixpanel will check for A/B tests automatically when your app enters
the foreground. Call this method if you would like to to check for,
and join, any experiments are newly available for the current user.
You do not need to call this method on the main thread.
*/
- (void)joinExperiments;
/*!
@method
@abstract
Join any experiments (A/B tests) that are available for the current user.
@discussion
Same as joinExperiments but will fire the given callback after all experiments
have been loaded and applied.
*/
- (void)joinExperimentsWithCallback:(nullable void (^)())experimentsLoadedCallback;
#endif
@end
/*!
@protocol
@abstract
Delegate protocol for controlling the Mixpanel API's network behavior.
@discussion
Creating a delegate for the Mixpanel object is entirely optional. It is only
necessary when you want full control over when data is uploaded to the server,
beyond simply calling stop: and start: before and after a particular block of
your code.
*/
@protocol MixpanelDelegate <NSObject>
@optional
/*!
@method
@abstract
Asks the delegate if data should be uploaded to the server.
@discussion
Return YES to upload now, NO to defer until later.
@param mixpanel Mixpanel API instance
*/
- (BOOL)mixpanelWillFlush:(Mixpanel *)mixpanel;
@end
NS_ASSUME_NONNULL_END