| commit | author | age | ||
| bad748 | 1 | // Copyright (c) 2014-present, Facebook, Inc. All rights reserved. |
| W | 2 | // |
| 3 | // You are hereby granted a non-exclusive, worldwide, royalty-free license to use, | |
| 4 | // copy, modify, and distribute this software in source code or binary form for use | |
| 5 | // in connection with the web services and APIs provided by Facebook. | |
| 6 | // | |
| 7 | // As with any software that integrates with the Facebook platform, your use of | |
| 8 | // this software is subject to the Facebook Developer Principles and Policies | |
| 9 | // [http://developers.facebook.com/policy/]. This copyright notice shall be | |
| 10 | // included in all copies or substantial portions of the software. | |
| 11 | // | |
| 12 | // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | |
| 13 | // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS | |
| 14 | // FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR | |
| 15 | // COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER | |
| 16 | // IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN | |
| 17 | // CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. | |
| 18 | ||
| 19 | #import <Foundation/Foundation.h> | |
| 20 | ||
| 9febd9 | 21 | #import <FBSDKCoreKit/FBSDKGraphRequestConnection.h> |
| W | 22 | |
| bad748 | 23 | #import "FBSDKMacros.h" |
| W | 24 | |
| 25 | @class FBSDKAccessToken; | |
| 26 | @class FBSDKGraphRequest; | |
| 27 | ||
| 9febd9 | 28 | /** NSNotificationCenter name indicating a result of a failed log flush attempt. The posted object will be an NSError instance. */ |
| bad748 | 29 | FBSDK_EXTERN NSString *const FBSDKAppEventsLoggingResultNotification; |
| W | 30 | |
| 9febd9 | 31 | /** optional plist key ("FacebookLoggingOverrideAppID") for setting `loggingOverrideAppID` */ |
| bad748 | 32 | FBSDK_EXTERN NSString *const FBSDKAppEventsOverrideAppIDBundleKey; |
| W | 33 | |
| 9febd9 | 34 | /** |
| bad748 | 35 | |
| 9febd9 | 36 | NS_ENUM (NSUInteger, FBSDKAppEventsFlushBehavior) |
| bad748 | 37 | |
| 9febd9 | 38 | Specifies when `FBSDKAppEvents` sends log events to the server. |
| bad748 | 39 | |
| W | 40 | */ |
| 41 | typedef NS_ENUM(NSUInteger, FBSDKAppEventsFlushBehavior) | |
| 42 | { | |
| 43 | ||
| 9febd9 | 44 | /** Flush automatically: periodically (once a minute or every 100 logged events) and always at app reactivation. */ |
| bad748 | 45 | FBSDKAppEventsFlushBehaviorAuto = 0, |
| W | 46 | |
| 9febd9 | 47 | /** Only flush when the `flush` method is called. When an app is moved to background/terminated, the |
| bad748 | 48 | events are persisted and re-established at activation, but they will only be written with an |
| W | 49 | explicit call to `flush`. */ |
| 50 | FBSDKAppEventsFlushBehaviorExplicitOnly, | |
| 51 | ||
| 52 | }; | |
| 53 | ||
| 9febd9 | 54 | /** |
| bad748 | 55 | @methodgroup Predefined event names for logging events common to many apps. Logging occurs through the `logEvent` family of methods on `FBSDKAppEvents`. |
| W | 56 | Common event parameters are provided in the `FBSDKAppEventsParameterNames*` constants. |
| 57 | */ | |
| 58 | ||
| 9febd9 | 59 | /** Log this event when the user has achieved a level in the app. */ |
| bad748 | 60 | FBSDK_EXTERN NSString *const FBSDKAppEventNameAchievedLevel; |
| W | 61 | |
| 9febd9 | 62 | /** Log this event when the user has entered their payment info. */ |
| bad748 | 63 | FBSDK_EXTERN NSString *const FBSDKAppEventNameAddedPaymentInfo; |
| W | 64 | |
| 9febd9 | 65 | /** Log this event when the user has added an item to their cart. The valueToSum passed to logEvent should be the item's price. */ |
| bad748 | 66 | FBSDK_EXTERN NSString *const FBSDKAppEventNameAddedToCart; |
| W | 67 | |
| 9febd9 | 68 | /** Log this event when the user has added an item to their wishlist. The valueToSum passed to logEvent should be the item's price. */ |
| bad748 | 69 | FBSDK_EXTERN NSString *const FBSDKAppEventNameAddedToWishlist; |
| W | 70 | |
| 9febd9 | 71 | /** Log this event when a user has completed registration with the app. */ |
| bad748 | 72 | FBSDK_EXTERN NSString *const FBSDKAppEventNameCompletedRegistration; |
| W | 73 | |
| 9febd9 | 74 | /** Log this event when the user has completed a tutorial in the app. */ |
| bad748 | 75 | FBSDK_EXTERN NSString *const FBSDKAppEventNameCompletedTutorial; |
| W | 76 | |
| 9febd9 | 77 | /** Log this event when the user has entered the checkout process. The valueToSum passed to logEvent should be the total price in the cart. */ |
| bad748 | 78 | FBSDK_EXTERN NSString *const FBSDKAppEventNameInitiatedCheckout; |
| W | 79 | |
| 9febd9 | 80 | /** Log this event when the user has rated an item in the app. The valueToSum passed to logEvent should be the numeric rating. */ |
| bad748 | 81 | FBSDK_EXTERN NSString *const FBSDKAppEventNameRated; |
| W | 82 | |
| 9febd9 | 83 | /** Log this event when a user has performed a search within the app. */ |
| bad748 | 84 | FBSDK_EXTERN NSString *const FBSDKAppEventNameSearched; |
| W | 85 | |
| 9febd9 | 86 | /** Log this event when the user has spent app credits. The valueToSum passed to logEvent should be the number of credits spent. */ |
| bad748 | 87 | FBSDK_EXTERN NSString *const FBSDKAppEventNameSpentCredits; |
| W | 88 | |
| 9febd9 | 89 | /** Log this event when the user has unlocked an achievement in the app. */ |
| bad748 | 90 | FBSDK_EXTERN NSString *const FBSDKAppEventNameUnlockedAchievement; |
| W | 91 | |
| 9febd9 | 92 | /** Log this event when a user has viewed a form of content in the app. */ |
| bad748 | 93 | FBSDK_EXTERN NSString *const FBSDKAppEventNameViewedContent; |
| W | 94 | |
| 9febd9 | 95 | /** |
| bad748 | 96 | @methodgroup Predefined event name parameters for common additional information to accompany events logged through the `logEvent` family |
| W | 97 | of methods on `FBSDKAppEvents`. Common event names are provided in the `FBAppEventName*` constants. |
| 98 | */ | |
| 99 | ||
| 27832c | 100 | /** |
| H | 101 | * Parameter key used to specify data for the one or more pieces of content being logged about. |
| 102 | * Data should be a JSON encoded string. | |
| 103 | * Example: | |
| 104 | * "[{\"id\": \"1234\", \"quantity\": 2, \"item_price\": 5.99}, {\"id\": \"5678\", \"quantity\": 1, \"item_price\": 9.99}]" | |
| 105 | */ | |
| 106 | FBSDK_EXTERN NSString *const FBSDKAppEventParameterNameContent; | |
| 107 | ||
| 9febd9 | 108 | /** Parameter key used to specify an ID for the specific piece of content being logged about. Could be an EAN, article identifier, etc., depending on the nature of the app. */ |
| bad748 | 109 | FBSDK_EXTERN NSString *const FBSDKAppEventParameterNameContentID; |
| W | 110 | |
| 9febd9 | 111 | /** Parameter key used to specify a generic content type/family for the logged event, e.g. "music", "photo", "video". Options to use will vary based upon what the app is all about. */ |
| bad748 | 112 | FBSDK_EXTERN NSString *const FBSDKAppEventParameterNameContentType; |
| W | 113 | |
| 9febd9 | 114 | /** Parameter key used to specify currency used with logged event. E.g. "USD", "EUR", "GBP". See ISO-4217 for specific values. One reference for these is <http://en.wikipedia.org/wiki/ISO_4217>. */ |
| bad748 | 115 | FBSDK_EXTERN NSString *const FBSDKAppEventParameterNameCurrency; |
| W | 116 | |
| 9febd9 | 117 | /** Parameter key used to specify a description appropriate to the event being logged. E.g., the name of the achievement unlocked in the `FBAppEventNameAchievementUnlocked` event. */ |
| bad748 | 118 | FBSDK_EXTERN NSString *const FBSDKAppEventParameterNameDescription; |
| W | 119 | |
| 9febd9 | 120 | /** Parameter key used to specify the level achieved in a `FBAppEventNameAchieved` event. */ |
| bad748 | 121 | FBSDK_EXTERN NSString *const FBSDKAppEventParameterNameLevel; |
| W | 122 | |
| 9febd9 | 123 | /** Parameter key used to specify the maximum rating available for the `FBAppEventNameRate` event. E.g., "5" or "10". */ |
| bad748 | 124 | FBSDK_EXTERN NSString *const FBSDKAppEventParameterNameMaxRatingValue; |
| W | 125 | |
| 9febd9 | 126 | /** Parameter key used to specify how many items are being processed for an `FBAppEventNameInitiatedCheckout` or `FBAppEventNamePurchased` event. */ |
| bad748 | 127 | FBSDK_EXTERN NSString *const FBSDKAppEventParameterNameNumItems; |
| W | 128 | |
| 9febd9 | 129 | /** Parameter key used to specify whether payment info is available for the `FBAppEventNameInitiatedCheckout` event. `FBSDKAppEventParameterValueYes` and `FBSDKAppEventParameterValueNo` are good canonical values to use for this parameter. */ |
| bad748 | 130 | FBSDK_EXTERN NSString *const FBSDKAppEventParameterNamePaymentInfoAvailable; |
| W | 131 | |
| 9febd9 | 132 | /** Parameter key used to specify method user has used to register for the app, e.g., "Facebook", "email", "Twitter", etc */ |
| bad748 | 133 | FBSDK_EXTERN NSString *const FBSDKAppEventParameterNameRegistrationMethod; |
| W | 134 | |
| 9febd9 | 135 | /** Parameter key used to specify the string provided by the user for a search operation. */ |
| bad748 | 136 | FBSDK_EXTERN NSString *const FBSDKAppEventParameterNameSearchString; |
| W | 137 | |
| 9febd9 | 138 | /** Parameter key used to specify whether the activity being logged about was successful or not. `FBSDKAppEventParameterValueYes` and `FBSDKAppEventParameterValueNo` are good canonical values to use for this parameter. */ |
| bad748 | 139 | FBSDK_EXTERN NSString *const FBSDKAppEventParameterNameSuccess; |
| W | 140 | |
| 141 | /* | |
| 142 | @methodgroup Predefined values to assign to event parameters that accompany events logged through the `logEvent` family | |
| 143 | of methods on `FBSDKAppEvents`. Common event parameters are provided in the `FBSDKAppEventParameterName*` constants. | |
| 144 | */ | |
| 145 | ||
| 9febd9 | 146 | /** Yes-valued parameter value to be used with parameter keys that need a Yes/No value */ |
| bad748 | 147 | FBSDK_EXTERN NSString *const FBSDKAppEventParameterValueYes; |
| W | 148 | |
| 9febd9 | 149 | /** No-valued parameter value to be used with parameter keys that need a Yes/No value */ |
| bad748 | 150 | FBSDK_EXTERN NSString *const FBSDKAppEventParameterValueNo; |
| W | 151 | |
| 152 | ||
| 9febd9 | 153 | /** |
| bad748 | 154 | |
| W | 155 | |
| 9febd9 | 156 | Client-side event logging for specialized application analytics available through Facebook App Insights |
| bad748 | 157 | and for use with Facebook Ads conversion tracking and optimization. |
| W | 158 | |
| 9febd9 | 159 | |
| W | 160 | |
| bad748 | 161 | The `FBSDKAppEvents` static class has a few related roles: |
| W | 162 | |
| 163 | + Logging predefined and application-defined events to Facebook App Insights with a | |
| 164 | numeric value to sum across a large number of events, and an optional set of key/value | |
| 165 | parameters that define "segments" for this event (e.g., 'purchaserStatus' : 'frequent', or | |
| 166 | 'gamerLevel' : 'intermediate') | |
| 167 | ||
| 168 | + Logging events to later be used for ads optimization around lifetime value. | |
| 169 | ||
| 170 | + Methods that control the way in which events are flushed out to the Facebook servers. | |
| 171 | ||
| 172 | Here are some important characteristics of the logging mechanism provided by `FBSDKAppEvents`: | |
| 173 | ||
| 174 | + Events are not sent immediately when logged. They're cached and flushed out to the Facebook servers | |
| 175 | in a number of situations: | |
| 176 | - when an event count threshold is passed (currently 100 logged events). | |
| 177 | - when a time threshold is passed (currently 15 seconds). | |
| 178 | - when an app has gone to background and is then brought back to the foreground. | |
| 179 | ||
| 180 | + Events will be accumulated when the app is in a disconnected state, and sent when the connection is | |
| 181 | restored and one of the above 'flush' conditions are met. | |
| 182 | ||
| 183 | + The `FBSDKAppEvents` class is thread-safe in that events may be logged from any of the app's threads. | |
| 184 | ||
| 185 | + The developer can set the `flushBehavior` on `FBSDKAppEvents` to force the flushing of events to only | |
| 186 | occur on an explicit call to the `flush` method. | |
| 187 | ||
| 188 | + The developer can turn on console debug output for event logging and flushing to the server by using | |
| 189 | the `FBSDKLoggingBehaviorAppEvents` value in `[FBSettings setLoggingBehavior:]`. | |
| 190 | ||
| 191 | Some things to note when logging events: | |
| 192 | ||
| 193 | + There is a limit on the number of unique event names an app can use, on the order of 1000. | |
| 194 | + There is a limit to the number of unique parameter names in the provided parameters that can | |
| 195 | be used per event, on the order of 25. This is not just for an individual call, but for all | |
| 196 | invocations for that eventName. | |
| 197 | + Event names and parameter names (the keys in the NSDictionary) must be between 2 and 40 characters, and | |
| 198 | must consist of alphanumeric characters, _, -, or spaces. | |
| 199 | + The length of each parameter value can be no more than on the order of 100 characters. | |
| 200 | ||
| 201 | */ | |
| 202 | @interface FBSDKAppEvents : NSObject | |
| 203 | ||
| 204 | /* | |
| 205 | * Basic event logging | |
| 206 | */ | |
| 207 | ||
| 9febd9 | 208 | /** |
| bad748 | 209 | |
| 9febd9 | 210 | Log an event with just an eventName. |
| bad748 | 211 | |
| 9febd9 | 212 | - Parameter eventName: The name of the event to record. Limitations on number of events and name length |
| bad748 | 213 | are given in the `FBSDKAppEvents` documentation. |
| W | 214 | |
| 215 | */ | |
| 216 | + (void)logEvent:(NSString *)eventName; | |
| 217 | ||
| 9febd9 | 218 | /** |
| bad748 | 219 | |
| 9febd9 | 220 | Log an event with an eventName and a numeric value to be aggregated with other events of this name. |
| bad748 | 221 | |
| 9febd9 | 222 | - Parameter eventName: The name of the event to record. Limitations on number of events and name length |
| bad748 | 223 | are given in the `FBSDKAppEvents` documentation. Common event names are provided in `FBAppEventName*` constants. |
| W | 224 | |
| 9febd9 | 225 | - Parameter valueToSum: Amount to be aggregated into all events of this eventName, and App Insights will report |
| bad748 | 226 | the cumulative and average value of this amount. |
| W | 227 | */ |
| 228 | + (void)logEvent:(NSString *)eventName | |
| 229 | valueToSum:(double)valueToSum; | |
| 230 | ||
| 231 | ||
| 9febd9 | 232 | /** |
| bad748 | 233 | |
| 9febd9 | 234 | Log an event with an eventName and a set of key/value pairs in the parameters dictionary. |
| bad748 | 235 | Parameter limitations are described above. |
| W | 236 | |
| 9febd9 | 237 | - Parameter eventName: The name of the event to record. Limitations on number of events and name construction |
| bad748 | 238 | are given in the `FBSDKAppEvents` documentation. Common event names are provided in `FBAppEventName*` constants. |
| W | 239 | |
| 9febd9 | 240 | - Parameter parameters: Arbitrary parameter dictionary of characteristics. The keys to this dictionary must |
| bad748 | 241 | be NSString's, and the values are expected to be NSString or NSNumber. Limitations on the number of |
| W | 242 | parameters and name construction are given in the `FBSDKAppEvents` documentation. Commonly used parameter names |
| 243 | are provided in `FBSDKAppEventParameterName*` constants. | |
| 244 | */ | |
| 245 | + (void)logEvent:(NSString *)eventName | |
| 246 | parameters:(NSDictionary *)parameters; | |
| 247 | ||
| 9febd9 | 248 | /** |
| bad748 | 249 | |
| 9febd9 | 250 | Log an event with an eventName, a numeric value to be aggregated with other events of this name, |
| bad748 | 251 | and a set of key/value pairs in the parameters dictionary. |
| W | 252 | |
| 9febd9 | 253 | - Parameter eventName: The name of the event to record. Limitations on number of events and name construction |
| bad748 | 254 | are given in the `FBSDKAppEvents` documentation. Common event names are provided in `FBAppEventName*` constants. |
| W | 255 | |
| 9febd9 | 256 | - Parameter valueToSum: Amount to be aggregated into all events of this eventName, and App Insights will report |
| bad748 | 257 | the cumulative and average value of this amount. |
| W | 258 | |
| 9febd9 | 259 | - Parameter parameters: Arbitrary parameter dictionary of characteristics. The keys to this dictionary must |
| bad748 | 260 | be NSString's, and the values are expected to be NSString or NSNumber. Limitations on the number of |
| W | 261 | parameters and name construction are given in the `FBSDKAppEvents` documentation. Commonly used parameter names |
| 262 | are provided in `FBSDKAppEventParameterName*` constants. | |
| 263 | ||
| 264 | */ | |
| 265 | + (void)logEvent:(NSString *)eventName | |
| 266 | valueToSum:(double)valueToSum | |
| 267 | parameters:(NSDictionary *)parameters; | |
| 268 | ||
| 269 | ||
| 9febd9 | 270 | /** |
| bad748 | 271 | |
| 9febd9 | 272 | Log an event with an eventName, a numeric value to be aggregated with other events of this name, |
| bad748 | 273 | and a set of key/value pairs in the parameters dictionary. Providing session lets the developer |
| W | 274 | target a particular <FBSession>. If nil is provided, then `[FBSession activeSession]` will be used. |
| 275 | ||
| 9febd9 | 276 | - Parameter eventName: The name of the event to record. Limitations on number of events and name construction |
| bad748 | 277 | are given in the `FBSDKAppEvents` documentation. Common event names are provided in `FBAppEventName*` constants. |
| W | 278 | |
| 9febd9 | 279 | - Parameter valueToSum: Amount to be aggregated into all events of this eventName, and App Insights will report |
| bad748 | 280 | the cumulative and average value of this amount. Note that this is an NSNumber, and a value of `nil` denotes |
| W | 281 | that this event doesn't have a value associated with it for summation. |
| 282 | ||
| 9febd9 | 283 | - Parameter parameters: Arbitrary parameter dictionary of characteristics. The keys to this dictionary must |
| bad748 | 284 | be NSString's, and the values are expected to be NSString or NSNumber. Limitations on the number of |
| W | 285 | parameters and name construction are given in the `FBSDKAppEvents` documentation. Commonly used parameter names |
| 286 | are provided in `FBSDKAppEventParameterName*` constants. | |
| 287 | ||
| 9febd9 | 288 | - Parameter accessToken: The optional access token to log the event as. |
| bad748 | 289 | */ |
| W | 290 | + (void)logEvent:(NSString *)eventName |
| 291 | valueToSum:(NSNumber *)valueToSum | |
| 292 | parameters:(NSDictionary *)parameters | |
| 293 | accessToken:(FBSDKAccessToken *)accessToken; | |
| 294 | ||
| 295 | /* | |
| 296 | * Purchase logging | |
| 297 | */ | |
| 298 | ||
| 9febd9 | 299 | /** |
| bad748 | 300 | |
| 9febd9 | 301 | Log a purchase of the specified amount, in the specified currency. |
| bad748 | 302 | |
| 9febd9 | 303 | - Parameter purchaseAmount: Purchase amount to be logged, as expressed in the specified currency. This value |
| bad748 | 304 | will be rounded to the thousandths place (e.g., 12.34567 becomes 12.346). |
| W | 305 | |
| 9febd9 | 306 | - Parameter currency: Currency, is denoted as, e.g. "USD", "EUR", "GBP". See ISO-4217 for |
| bad748 | 307 | specific values. One reference for these is <http://en.wikipedia.org/wiki/ISO_4217>. |
| W | 308 | |
| 9febd9 | 309 | |
| W | 310 | This event immediately triggers a flush of the `FBSDKAppEvents` event queue, unless the `flushBehavior` is set |
| bad748 | 311 | to `FBSDKAppEventsFlushBehaviorExplicitOnly`. |
| W | 312 | |
| 313 | */ | |
| 314 | + (void)logPurchase:(double)purchaseAmount | |
| 315 | currency:(NSString *)currency; | |
| 316 | ||
| 9febd9 | 317 | /** |
| bad748 | 318 | |
| 9febd9 | 319 | Log a purchase of the specified amount, in the specified currency, also providing a set of |
| bad748 | 320 | additional characteristics describing the purchase. |
| W | 321 | |
| 9febd9 | 322 | - Parameter purchaseAmount: Purchase amount to be logged, as expressed in the specified currency.This value |
| bad748 | 323 | will be rounded to the thousandths place (e.g., 12.34567 becomes 12.346). |
| W | 324 | |
| 9febd9 | 325 | - Parameter currency: Currency, is denoted as, e.g. "USD", "EUR", "GBP". See ISO-4217 for |
| bad748 | 326 | specific values. One reference for these is <http://en.wikipedia.org/wiki/ISO_4217>. |
| W | 327 | |
| 9febd9 | 328 | - Parameter parameters: Arbitrary parameter dictionary of characteristics. The keys to this dictionary must |
| bad748 | 329 | be NSString's, and the values are expected to be NSString or NSNumber. Limitations on the number of |
| W | 330 | parameters and name construction are given in the `FBSDKAppEvents` documentation. Commonly used parameter names |
| 331 | are provided in `FBSDKAppEventParameterName*` constants. | |
| 332 | ||
| 9febd9 | 333 | |
| W | 334 | This event immediately triggers a flush of the `FBSDKAppEvents` event queue, unless the `flushBehavior` is set |
| bad748 | 335 | to `FBSDKAppEventsFlushBehaviorExplicitOnly`. |
| W | 336 | |
| 337 | */ | |
| 338 | + (void)logPurchase:(double)purchaseAmount | |
| 339 | currency:(NSString *)currency | |
| 340 | parameters:(NSDictionary *)parameters; | |
| 341 | ||
| 9febd9 | 342 | /** |
| bad748 | 343 | |
| 9febd9 | 344 | Log a purchase of the specified amount, in the specified currency, also providing a set of |
| bad748 | 345 | additional characteristics describing the purchase, as well as an <FBSession> to log to. |
| W | 346 | |
| 9febd9 | 347 | - Parameter purchaseAmount: Purchase amount to be logged, as expressed in the specified currency.This value |
| bad748 | 348 | will be rounded to the thousandths place (e.g., 12.34567 becomes 12.346). |
| W | 349 | |
| 9febd9 | 350 | - Parameter currency: Currency, is denoted as, e.g. "USD", "EUR", "GBP". See ISO-4217 for |
| bad748 | 351 | specific values. One reference for these is <http://en.wikipedia.org/wiki/ISO_4217>. |
| W | 352 | |
| 9febd9 | 353 | - Parameter parameters: Arbitrary parameter dictionary of characteristics. The keys to this dictionary must |
| bad748 | 354 | be NSString's, and the values are expected to be NSString or NSNumber. Limitations on the number of |
| W | 355 | parameters and name construction are given in the `FBSDKAppEvents` documentation. Commonly used parameter names |
| 356 | are provided in `FBSDKAppEventParameterName*` constants. | |
| 357 | ||
| 9febd9 | 358 | - Parameter accessToken: The optional access token to log the event as. |
| bad748 | 359 | |
| 9febd9 | 360 | |
| W | 361 | This event immediately triggers a flush of the `FBSDKAppEvents` event queue, unless the `flushBehavior` is set |
| bad748 | 362 | to `FBSDKAppEventsFlushBehaviorExplicitOnly`. |
| W | 363 | |
| 364 | */ | |
| 365 | + (void)logPurchase:(double)purchaseAmount | |
| 366 | currency:(NSString *)currency | |
| 367 | parameters:(NSDictionary *)parameters | |
| 368 | accessToken:(FBSDKAccessToken *)accessToken; | |
| 369 | ||
| 370 | ||
| 371 | /* | |
| 372 | * Push Notifications Logging | |
| 373 | */ | |
| 374 | ||
| 9febd9 | 375 | /** |
| W | 376 | Log an app event that tracks that the application was open via Push Notification. |
| bad748 | 377 | |
| 9febd9 | 378 | - Parameter payload: Notification payload received via `UIApplicationDelegate`. |
| bad748 | 379 | */ |
| W | 380 | + (void)logPushNotificationOpen:(NSDictionary *)payload; |
| 381 | ||
| 9febd9 | 382 | /** |
| W | 383 | Log an app event that tracks that a custom action was taken from a push notification. |
| bad748 | 384 | |
| 9febd9 | 385 | - Parameter payload: Notification payload received via `UIApplicationDelegate`. |
| W | 386 | - Parameter action: Name of the action that was taken. |
| bad748 | 387 | */ |
| W | 388 | + (void)logPushNotificationOpen:(NSDictionary *)payload action:(NSString *)action; |
| 389 | ||
| 9febd9 | 390 | /** |
| bad748 | 391 | |
| 37c026 | 392 | Notifies the events system that the app has launched and, when appropriate, logs an "activated app" event. |
| H | 393 | This function is called automatically from FBSDKApplicationDelegate applicationDidBecomeActive, unless |
| 394 | one overrides 'FacebookAutoLogAppEventsEnabled' key to false in the project info plist file. | |
| 395 | In case 'FacebookAutoLogAppEventsEnabled' is set to false, then it should typically be placed in the | |
| bad748 | 396 | app delegates' `applicationDidBecomeActive:` method. |
| W | 397 | |
| 398 | This method also takes care of logging the event indicating the first time this app has been launched, which, among other things, is used to | |
| 399 | track user acquisition and app install ads conversions. | |
| 400 | ||
| 9febd9 | 401 | |
| W | 402 | |
| bad748 | 403 | `activateApp` will not log an event on every app launch, since launches happen every time the app is backgrounded and then foregrounded. |
| W | 404 | "activated app" events will be logged when the app has not been active for more than 60 seconds. This method also causes a "deactivated app" |
| 405 | event to be logged when sessions are "completed", and these events are logged with the session length, with an indication of how much | |
| 406 | time has elapsed between sessions, and with the number of background/foreground interruptions that session had. This data | |
| 407 | is all visible in your app's App Events Insights. | |
| 408 | */ | |
| 409 | + (void)activateApp; | |
| 410 | ||
| 411 | /* | |
| 412 | * Push Notifications Registration | |
| 413 | */ | |
| 414 | ||
| 9febd9 | 415 | /** |
| 37c026 | 416 | Sets and sends device token to register the current application for push notifications. |
| bad748 | 417 | |
| 9febd9 | 418 | |
| W | 419 | |
| 37c026 | 420 | Sets and sends a device token from `NSData` representation that you get from `UIApplicationDelegate.-application:didRegisterForRemoteNotificationsWithDeviceToken:`. |
| bad748 | 421 | |
| 9febd9 | 422 | - Parameter deviceToken: Device token data. |
| bad748 | 423 | */ |
| W | 424 | + (void)setPushNotificationsDeviceToken:(NSData *)deviceToken; |
| 425 | ||
| 426 | /* | |
| 427 | * Control over event batching/flushing | |
| 428 | */ | |
| 429 | ||
| 9febd9 | 430 | /** |
| bad748 | 431 | |
| 9febd9 | 432 | Get the current event flushing behavior specifying when events are sent back to Facebook servers. |
| bad748 | 433 | */ |
| W | 434 | + (FBSDKAppEventsFlushBehavior)flushBehavior; |
| 435 | ||
| 9febd9 | 436 | /** |
| bad748 | 437 | |
| 9febd9 | 438 | Set the current event flushing behavior specifying when events are sent back to Facebook servers. |
| bad748 | 439 | |
| 9febd9 | 440 | - Parameter flushBehavior: The desired `FBSDKAppEventsFlushBehavior` to be used. |
| bad748 | 441 | */ |
| W | 442 | + (void)setFlushBehavior:(FBSDKAppEventsFlushBehavior)flushBehavior; |
| 443 | ||
| 9febd9 | 444 | /** |
| W | 445 | Set the 'override' App ID for App Event logging. |
| bad748 | 446 | |
| 9febd9 | 447 | |
| W | 448 | |
| bad748 | 449 | In some cases, apps want to use one Facebook App ID for login and social presence and another |
| W | 450 | for App Event logging. (An example is if multiple apps from the same company share an app ID for login, but |
| 451 | want distinct logging.) By default, this value is `nil`, and defers to the `FBSDKAppEventsOverrideAppIDBundleKey` | |
| 452 | plist value. If that's not set, it defaults to `[FBSDKSettings appID]`. | |
| 453 | ||
| 454 | This should be set before any other calls are made to `FBSDKAppEvents`. Thus, you should set it in your application | |
| 455 | delegate's `application:didFinishLaunchingWithOptions:` delegate. | |
| 456 | ||
| 9febd9 | 457 | - Parameter appID: The Facebook App ID to be used for App Event logging. |
| bad748 | 458 | */ |
| W | 459 | + (void)setLoggingOverrideAppID:(NSString *)appID; |
| 460 | ||
| 9febd9 | 461 | /** |
| W | 462 | Get the 'override' App ID for App Event logging. |
| bad748 | 463 | |
| 9febd9 | 464 | |
| W | 465 | - See:setLoggingOverrideAppID: |
| bad748 | 466 | |
| W | 467 | */ |
| 468 | + (NSString *)loggingOverrideAppID; | |
| 469 | ||
| 470 | ||
| 9febd9 | 471 | /** |
| W | 472 | Explicitly kick off flushing of events to Facebook. This is an asynchronous method, but it does initiate an immediate |
| bad748 | 473 | kick off. Server failures will be reported through the NotificationCenter with notification ID `FBSDKAppEventsLoggingResultNotification`. |
| W | 474 | */ |
| 475 | + (void)flush; | |
| 476 | ||
| 9febd9 | 477 | /** |
| W | 478 | Creates a request representing the Graph API call to retrieve a Custom Audience "third party ID" for the app's Facebook user. |
| bad748 | 479 | Callers will send this ID back to their own servers, collect up a set to create a Facebook Custom Audience with, |
| W | 480 | and then use the resultant Custom Audience to target ads. |
| 481 | ||
| 9febd9 | 482 | - Parameter accessToken: The access token to use to establish the user's identity for users logged into Facebook through this app. |
| bad748 | 483 | If `nil`, then the `[FBSDKAccessToken currentAccessToken]` is used. |
| W | 484 | |
| 9febd9 | 485 | |
| W | 486 | |
| bad748 | 487 | The JSON in the request's response will include an "custom_audience_third_party_id" key/value pair, with the value being the ID retrieved. |
| W | 488 | This ID is an encrypted encoding of the Facebook user's ID and the invoking Facebook app ID. |
| 489 | Multiple calls with the same user will return different IDs, thus these IDs cannot be used to correlate behavior | |
| 490 | across devices or applications, and are only meaningful when sent back to Facebook for creating Custom Audiences. | |
| 491 | ||
| 492 | The ID retrieved represents the Facebook user identified in the following way: if the specified access token is valid, | |
| 493 | the ID will represent the user associated with that token; otherwise the ID will represent the user logged into the | |
| 494 | native Facebook app on the device. If there is no native Facebook app, no one is logged into it, or the user has opted out | |
| 495 | at the iOS level from ad tracking, then a `nil` ID will be returned. | |
| 496 | ||
| 497 | This method returns `nil` if either the user has opted-out (via iOS) from Ad Tracking, the app itself has limited event usage | |
| 498 | via the `[FBSDKSettings limitEventAndDataUsage]` flag, or a specific Facebook user cannot be identified. | |
| 499 | */ | |
| 500 | + (FBSDKGraphRequest *)requestForCustomAudienceThirdPartyIDWithAccessToken:(FBSDKAccessToken *)accessToken; | |
| 9febd9 | 501 | |
| W | 502 | /* |
| 503 | Sets a custom user ID to associate with all app events. | |
| 504 | ||
| 505 | The userID is persisted until it is cleared by passing nil. | |
| 506 | */ | |
| 507 | + (void)setUserID:(NSString *)userID; | |
| 508 | ||
| 509 | /* | |
| 510 | Returns the set custom user ID. | |
| 511 | */ | |
| 512 | + (NSString *)userID; | |
| 513 | ||
| 514 | /* | |
| 515 | Sends a request to update the properties for the current user, set by `setUserID:` | |
| 516 | ||
| 517 | You must call `FBSDKAppEvents setUserID:` before making this call. | |
| 518 | - Parameter properties: the custom user properties | |
| 519 | - Parameter handler: the optional completion handler | |
| 520 | */ | |
| 521 | + (void)updateUserProperties:(NSDictionary *)properties handler:(FBSDKGraphRequestHandler)handler; | |
| 522 | ||
| bad748 | 523 | @end |
