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