-
Notifications
You must be signed in to change notification settings - Fork 20
/
KISSMetricsAPI.h
executable file
·173 lines (149 loc) · 5 KB
/
KISSMetricsAPI.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
//
// KISSMetricsAPI.h
// KISSMetricsAPI
//
// Created by Einar Vollset on 9/15/11.
// Copyright 2011 KISSMetrics. All rights reserved.
//
#import <Foundation/Foundation.h>
#if TARGET_OS_IPHONE
#import <UIKit/UIKit.h>
#else
#import <CoreServices/CoreServices.h>
#endif
@interface KISSMetricsAPI : NSObject
/**
* sharedAPIWithKey:
*
* Initializes the Kissmetrics API. Requires a valid API key.
*
* Parameters:
* - apiKey: The NSString API key obtained from www.kissmetrics.io
*
* Return Value:
* The singleton KissmetricsAPI.
*
* Discussion:
* Calling this method first before any other is required, it is therefore strongly
* recommended that you call this in applicationDidFinishLaunching: of your app delegate.
* Calling this method also identifies the current user with whatever identity was last
* passed to identify:, or with an anonymous identifier if alias: has not been called yet
* for this install.
*/
+ (KISSMetricsAPI *) sharedAPIWithKey:(NSString *)apiKey;
/**
* sharedAPI
*
* Returns the singleton KissmetricsAPI object previously initialized with sharedAPIWithKey:
*
* Return Value:
* The singleton KissmetricsAPI object, or nil if sharedAPIWithKey: has not been called.
* Note, in the latter case an error message will also be displayed on the log.
*/
+ (KISSMetricsAPI *) sharedAPI;
/**
* recordEvent:withProperties:
*
* Records an event with an optional set of properties.
*
* Parameters:
* - name: An NSString identifying this event.
*
* - properties: An NSDictionary of properties. The keys must all be non-nil, non-empty
* NSStrings. The values must all be non-nil, non-empty NSStrings or NSNumber. Any key/value
* pair that does not conform to this will be dropped with a warning message displayed on the log.
*
* Discussion:
*
* In theory you can make your event name as long as you like, and send as many properties as you want
* up to about 8KB, but in practice, as this API makes HTTPS GET calls to KISSMetrics' servers you will
* eventually hit the maximum URL length allowed by KISSMetrics servers. Anything where the total URL
* generated by the API is > 2000 characters will generate a warning message on the logs.
*/
- (void)recordEvent:(NSString *)name withProperties:(NSDictionary *)properties;
/**
* setProperties:properties
*
* Sets one or more properties on a user.
*
*
* Parameters:
*
* - properties: An NSDictionary of properties. The keys must all be non-nil, non-empty NSStrings.
* The values must all be non-nil, non-empty NSStrings or NSNumber. Any key/value pair that does
* not conform to this will be dropped with a warning message displayed on the log.
*
*
* Discussion:
*
* In theory you can send as many properties as you want up to about 8KB, but in practice, as this API
* makes HTTPS GET calls to KISSMetrics' servers you will eventually hit the maximum URL length allowed by
* KISSMetrics servers. Anything where the total URL generated by the API is > 2000 characters will
* generate a warning message on the logs.
*/
- (void)setProperties:(NSDictionary *)properties;
/**
* identify:
*
* Associates an identity (such as an email address) with a user.
*
*
* Parameters:
* - identity: An NSString identifying the current user. If nil or the empty string, this call is a no-op.
*
*
* Discussion:
* You can associate multiple identities with a user; the KISSMetrics website will allow you to view all
* identities associated with any given user.
* The API will persist the latest identity passed in with identify: between sessions, and use this in
* sharedAPIWithKey: (see sharedAPIWithKey: for more details).
*/
- (void)identify:(NSString *)identity;
/**
* identity
*
* Discussion:
* Returns the latest identity set through identify:
*/
- (NSString *)identity;
/**
* clearIdentity:
*
* Clears the last set identity.
*
*
* Discussion:
* You can clear the last set identity after a user logs out to prevent the activity of another user
* from being attributed to the last logged in identity.
*/
- (void)clearIdentity;
/**
* alias:
*
* Associates two identities (such as an email address and a name) with a user.
*
*
* Parameters:
* - firstIdentity: An NSString containing the first identity. If nil or the empty string, this call is a no-op.
* - secondIdentity: An NSString containing the second identity. If nil or the empty string, this call is a no-op.
*
* Discussion:
* You can associate multiple identities with a user; the KISSMetrics website will allow you to view all
* identities associated with any given user.
* Unlike identify, this API will NOT persist any identities.
*/
- (void)alias:(NSString *)firstIdentity withIdentity:(NSString *)secondIdentity;
#if !TARGET_OS_IPHONE
/**
* macVersionNumber
*
* Returns back OS X version number using Gestalt()
*
*
* Discussion:
* You can return back the current version of Mac OS X that you're running. This will return back a
* formatted NSString. This is included in the logging props and is only defined for Mac OS X.
*/
+ (NSString *)macVersionNumber;
#endif
@end