WAFbImpl.framework
view | history | commit | commitdiff
hank
2019-06-20 e81c27b13950ca02baa879ae7b8108c0c3ef7fb0
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
9f077b 21 #if !TARGET_OS_TV
H 22 #import <WebKit/WebKit.h>
23 #endif
24
9febd9 25 #import <FBSDKCoreKit/FBSDKGraphRequestConnection.h>
W 26
e81c27 27 NS_ASSUME_NONNULL_BEGIN
H 28
bad748 29 @class FBSDKAccessToken;
W 30 @class FBSDKGraphRequest;
31
13e53a 32 #if __IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_10_0
H 33
9febd9 34 /**  NSNotificationCenter name indicating a result of a failed log flush attempt. The posted object will be an NSError instance. */
e81c27 35 FOUNDATION_EXPORT NSNotificationName const FBSDKAppEventsLoggingResultNotification
H 36 NS_SWIFT_NAME(AppEventsLoggingResult);
13e53a 37
H 38 #else
39
40 /**  NSNotificationCenter name indicating a result of a failed log flush attempt. The posted object will be an NSError instance. */
e81c27 41 FOUNDATION_EXPORT NSString *const FBSDKAppEventsLoggingResultNotification
H 42 NS_SWIFT_NAME(AppEventsLoggingResultNotification);
13e53a 43
H 44 #endif
bad748 45
9febd9 46 /**  optional plist key ("FacebookLoggingOverrideAppID") for setting `loggingOverrideAppID` */
e81c27 47 FOUNDATION_EXPORT NSString *const FBSDKAppEventsOverrideAppIDBundleKey
H 48 NS_SWIFT_NAME(AppEventsOverrideAppIDBundleKey);
bad748 49
9febd9 50 /**
bad748 51
9febd9 52  NS_ENUM (NSUInteger, FBSDKAppEventsFlushBehavior)
bad748 53
9febd9 54   Specifies when `FBSDKAppEvents` sends log events to the server.
bad748 55
W 56  */
57 typedef NS_ENUM(NSUInteger, FBSDKAppEventsFlushBehavior)
58 {
59
9febd9 60   /** Flush automatically: periodically (once a minute or every 100 logged events) and always at app reactivation. */
bad748 61   FBSDKAppEventsFlushBehaviorAuto = 0,
W 62
9febd9 63   /** Only flush when the `flush` method is called. When an app is moved to background/terminated, the
bad748 64    events are persisted and re-established at activation, but they will only be written with an
W 65    explicit call to `flush`. */
66   FBSDKAppEventsFlushBehaviorExplicitOnly,
e81c27 67 } NS_SWIFT_NAME(AppEvents.FlushBehavior);
bad748 68
9febd9 69 /**
13e53a 70   NS_ENUM(NSUInteger, FBSDKProductAvailability)
H 71     Specifies product availability for Product Catalog product item update
72  */
73 typedef NS_ENUM(NSUInteger, FBSDKProductAvailability)
74 {
75   /**
76    * Item ships immediately
77    */
78   FBSDKProductAvailabilityInStock = 0,
79   /**
80    * No plan to restock
81    */
82   FBSDKProductAvailabilityOutOfStock,
83   /**
84    * Available in future
85    */
86   FBSDKProductAvailabilityPreOrder,
87   /**
88    * Ships in 1-2 weeks
89    */
90   FBSDKProductAvailabilityAvailableForOrder,
91   /**
92    * Discontinued
93    */
94   FBSDKProductAvailabilityDiscontinued,
e81c27 95 } NS_SWIFT_NAME(AppEvents.ProductAvailability);
13e53a 96
H 97 /**
98  NS_ENUM(NSUInteger, FBSDKProductCondition)
99  Specifies product condition for Product Catalog product item update
100  */
101 typedef NS_ENUM(NSUInteger, FBSDKProductCondition)
102 {
103   FBSDKProductConditionNew = 0,
104   FBSDKProductConditionRefurbished,
105   FBSDKProductConditionUsed,
e81c27 106 } NS_SWIFT_NAME(AppEvents.ProductCondition);
13e53a 107
H 108 /**
bad748 109  @methodgroup Predefined event names for logging events common to many apps.  Logging occurs through the `logEvent` family of methods on `FBSDKAppEvents`.
W 110  Common event parameters are provided in the `FBSDKAppEventsParameterNames*` constants.
111  */
112
e81c27 113 /// typedef for FBSDKAppEventName
H 114 typedef NSString *const FBSDKAppEventName NS_TYPED_EXTENSIBLE_ENUM NS_SWIFT_NAME(AppEvents.Name);
115
9febd9 116 /** Log this event when the user has achieved a level in the app. */
e81c27 117 FOUNDATION_EXPORT FBSDKAppEventName FBSDKAppEventNameAchievedLevel;
bad748 118
9febd9 119 /** Log this event when the user has entered their payment info. */
e81c27 120 FOUNDATION_EXPORT FBSDKAppEventName FBSDKAppEventNameAddedPaymentInfo;
bad748 121
9febd9 122 /** Log this event when the user has added an item to their cart.  The valueToSum passed to logEvent should be the item's price. */
e81c27 123 FOUNDATION_EXPORT FBSDKAppEventName FBSDKAppEventNameAddedToCart;
bad748 124
9febd9 125 /** Log this event when the user has added an item to their wishlist.  The valueToSum passed to logEvent should be the item's price. */
e81c27 126 FOUNDATION_EXPORT FBSDKAppEventName FBSDKAppEventNameAddedToWishlist;
bad748 127
9febd9 128 /** Log this event when a user has completed registration with the app. */
e81c27 129 FOUNDATION_EXPORT FBSDKAppEventName FBSDKAppEventNameCompletedRegistration;
bad748 130
9febd9 131 /** Log this event when the user has completed a tutorial in the app. */
e81c27 132 FOUNDATION_EXPORT FBSDKAppEventName FBSDKAppEventNameCompletedTutorial;
bad748 133
9febd9 134 /** Log this event when the user has entered the checkout process.  The valueToSum passed to logEvent should be the total price in the cart. */
e81c27 135 FOUNDATION_EXPORT FBSDKAppEventName FBSDKAppEventNameInitiatedCheckout;
H 136
137 /** Log this event when the user has completed a transaction.  The valueToSum passed to logEvent should be the total price of the transaction. */
138 FOUNDATION_EXPORT FBSDKAppEventName FBSDKAppEventNamePurchased;
bad748 139
9febd9 140 /** Log this event when the user has rated an item in the app.  The valueToSum passed to logEvent should be the numeric rating. */
e81c27 141 FOUNDATION_EXPORT FBSDKAppEventName FBSDKAppEventNameRated;
bad748 142
9febd9 143 /** Log this event when a user has performed a search within the app. */
e81c27 144 FOUNDATION_EXPORT FBSDKAppEventName FBSDKAppEventNameSearched;
bad748 145
9febd9 146 /** Log this event when the user has spent app credits.  The valueToSum passed to logEvent should be the number of credits spent. */
e81c27 147 FOUNDATION_EXPORT FBSDKAppEventName FBSDKAppEventNameSpentCredits;
bad748 148
9febd9 149 /** Log this event when the user has unlocked an achievement in the app. */
e81c27 150 FOUNDATION_EXPORT FBSDKAppEventName FBSDKAppEventNameUnlockedAchievement;
bad748 151
9febd9 152 /** Log this event when a user has viewed a form of content in the app. */
e81c27 153 FOUNDATION_EXPORT FBSDKAppEventName FBSDKAppEventNameViewedContent;
13e53a 154
H 155 /** A telephone/SMS, email, chat or other type of contact between a customer and your business. */
e81c27 156 FOUNDATION_EXPORT FBSDKAppEventName FBSDKAppEventNameContact;
13e53a 157
H 158 /** The customization of products through a configuration tool or other application your business owns. */
e81c27 159 FOUNDATION_EXPORT FBSDKAppEventName FBSDKAppEventNameCustomizeProduct;
13e53a 160
H 161 /** The donation of funds to your organization or cause. */
e81c27 162 FOUNDATION_EXPORT FBSDKAppEventName FBSDKAppEventNameDonate;
13e53a 163
H 164 /** When a person finds one of your locations via web or application, with an intention to visit (example: find product at a local store). */
e81c27 165 FOUNDATION_EXPORT FBSDKAppEventName FBSDKAppEventNameFindLocation;
13e53a 166
H 167 /** The booking of an appointment to visit one of your locations. */
e81c27 168 FOUNDATION_EXPORT FBSDKAppEventName FBSDKAppEventNameSchedule;
H 169
170 /** The subsequent subscriptions after the start of a paid subscription for a product or service you offer. */
171 FOUNDATION_EXPORT FBSDKAppEventName FBSDKAppEventNameSubscriptionHeartbeat;
13e53a 172
H 173 /** The start of a free trial of a product or service you offer (example: trial subscription). */
e81c27 174 FOUNDATION_EXPORT FBSDKAppEventName FBSDKAppEventNameStartTrial;
13e53a 175
H 176 /** The submission of an application for a product, service or program you offer (example: credit card, educational program or job). */
e81c27 177 FOUNDATION_EXPORT FBSDKAppEventName FBSDKAppEventNameSubmitApplication;
13e53a 178
H 179 /** The start of a paid subscription for a product or service you offer. */
e81c27 180 FOUNDATION_EXPORT FBSDKAppEventName FBSDKAppEventNameSubscribe;
13e53a 181
H 182 /** Log this event when the user views an ad. */
e81c27 183 FOUNDATION_EXPORT FBSDKAppEventName FBSDKAppEventNameAdImpression;
13e53a 184
H 185 /** Log this event when the user clicks an ad. */
e81c27 186 FOUNDATION_EXPORT FBSDKAppEventName FBSDKAppEventNameAdClick;
bad748 187
9febd9 188 /**
bad748 189  @methodgroup Predefined event name parameters for common additional information to accompany events logged through the `logEvent` family
W 190  of methods on `FBSDKAppEvents`.  Common event names are provided in the `FBAppEventName*` constants.
191  */
e81c27 192
H 193 /// typedef for FBSDKAppEventParameterName
194 typedef NSString *const FBSDKAppEventParameterName NS_TYPED_EXTENSIBLE_ENUM NS_SWIFT_NAME(AppEvents.ParameterName);
bad748 195
27832c 196  /**
H 197   * Parameter key used to specify data for the one or more pieces of content being logged about.
198   * Data should be a JSON encoded string.
199   * Example:
200   * "[{\"id\": \"1234\", \"quantity\": 2, \"item_price\": 5.99}, {\"id\": \"5678\", \"quantity\": 1, \"item_price\": 9.99}]"
201   */
e81c27 202 FOUNDATION_EXPORT FBSDKAppEventParameterName FBSDKAppEventParameterNameContent;
27832c 203
9febd9 204 /** 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. */
e81c27 205 FOUNDATION_EXPORT FBSDKAppEventParameterName FBSDKAppEventParameterNameContentID;
bad748 206
9febd9 207 /** 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. */
e81c27 208 FOUNDATION_EXPORT FBSDKAppEventParameterName FBSDKAppEventParameterNameContentType;
bad748 209
9febd9 210 /** 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>. */
e81c27 211 FOUNDATION_EXPORT FBSDKAppEventParameterName FBSDKAppEventParameterNameCurrency;
bad748 212
9febd9 213 /** 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. */
e81c27 214 FOUNDATION_EXPORT FBSDKAppEventParameterName FBSDKAppEventParameterNameDescription;
bad748 215
9febd9 216 /** Parameter key used to specify the level achieved in a `FBAppEventNameAchieved` event. */
e81c27 217 FOUNDATION_EXPORT FBSDKAppEventParameterName FBSDKAppEventParameterNameLevel;
bad748 218
9febd9 219 /** Parameter key used to specify the maximum rating available for the `FBAppEventNameRate` event.  E.g., "5" or "10". */
e81c27 220 FOUNDATION_EXPORT FBSDKAppEventParameterName FBSDKAppEventParameterNameMaxRatingValue;
bad748 221
9febd9 222 /** Parameter key used to specify how many items are being processed for an `FBAppEventNameInitiatedCheckout` or `FBAppEventNamePurchased` event. */
e81c27 223 FOUNDATION_EXPORT FBSDKAppEventParameterName FBSDKAppEventParameterNameNumItems;
bad748 224
9febd9 225 /** 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. */
e81c27 226 FOUNDATION_EXPORT FBSDKAppEventParameterName FBSDKAppEventParameterNamePaymentInfoAvailable;
bad748 227
9febd9 228 /** Parameter key used to specify method user has used to register for the app, e.g., "Facebook", "email", "Twitter", etc */
e81c27 229 FOUNDATION_EXPORT FBSDKAppEventParameterName FBSDKAppEventParameterNameRegistrationMethod;
bad748 230
9febd9 231 /** Parameter key used to specify the string provided by the user for a search operation. */
e81c27 232 FOUNDATION_EXPORT FBSDKAppEventParameterName FBSDKAppEventParameterNameSearchString;
bad748 233
9febd9 234 /** 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. */
e81c27 235 FOUNDATION_EXPORT FBSDKAppEventParameterName FBSDKAppEventParameterNameSuccess;
13e53a 236
H 237 /**
238  @methodgroup Predefined event name parameters for common additional information to accompany events logged through the `logProductItem` method on `FBSDKAppEvents`.
239  */
240
e81c27 241 /// typedef for FBSDKAppEventParameterProduct
H 242 typedef NSString *const FBSDKAppEventParameterProduct NS_TYPED_EXTENSIBLE_ENUM NS_SWIFT_NAME(AppEvents.ParameterProduct);
243
244 /** Parameter key used to specify the product item's category. */
245 FOUNDATION_EXPORT FBSDKAppEventParameterProduct FBSDKAppEventParameterProductCategory;
246
13e53a 247 /** Parameter key used to specify the product item's custom label 0. */
e81c27 248 FOUNDATION_EXPORT FBSDKAppEventParameterProduct FBSDKAppEventParameterProductCustomLabel0;
13e53a 249
H 250 /** Parameter key used to specify the product item's custom label 1. */
e81c27 251 FOUNDATION_EXPORT FBSDKAppEventParameterProduct FBSDKAppEventParameterProductCustomLabel1;
13e53a 252
H 253 /** Parameter key used to specify the product item's custom label 2. */
e81c27 254 FOUNDATION_EXPORT FBSDKAppEventParameterProduct FBSDKAppEventParameterProductCustomLabel2;
13e53a 255
H 256 /** Parameter key used to specify the product item's custom label 3. */
e81c27 257 FOUNDATION_EXPORT FBSDKAppEventParameterProduct FBSDKAppEventParameterProductCustomLabel3;
13e53a 258
H 259 /** Parameter key used to specify the product item's custom label 4. */
e81c27 260 FOUNDATION_EXPORT FBSDKAppEventParameterProduct FBSDKAppEventParameterProductCustomLabel4;
13e53a 261
H 262 /** Parameter key used to specify the product item's AppLink app URL for iOS. */
e81c27 263 FOUNDATION_EXPORT FBSDKAppEventParameterProduct FBSDKAppEventParameterProductAppLinkIOSUrl;
13e53a 264
H 265 /** Parameter key used to specify the product item's AppLink app ID for iOS App Store. */
e81c27 266 FOUNDATION_EXPORT FBSDKAppEventParameterProduct FBSDKAppEventParameterProductAppLinkIOSAppStoreID;
13e53a 267
H 268 /** Parameter key used to specify the product item's AppLink app name for iOS. */
e81c27 269 FOUNDATION_EXPORT FBSDKAppEventParameterProduct FBSDKAppEventParameterProductAppLinkIOSAppName;
13e53a 270
H 271 /** Parameter key used to specify the product item's AppLink app URL for iPhone. */
e81c27 272 FOUNDATION_EXPORT FBSDKAppEventParameterProduct FBSDKAppEventParameterProductAppLinkIPhoneUrl;
13e53a 273
H 274 /** Parameter key used to specify the product item's AppLink app ID for iPhone App Store. */
e81c27 275 FOUNDATION_EXPORT FBSDKAppEventParameterProduct FBSDKAppEventParameterProductAppLinkIPhoneAppStoreID;
13e53a 276
H 277 /** Parameter key used to specify the product item's AppLink app name for iPhone. */
e81c27 278 FOUNDATION_EXPORT FBSDKAppEventParameterProduct FBSDKAppEventParameterProductAppLinkIPhoneAppName;
13e53a 279
H 280 /** Parameter key used to specify the product item's AppLink app URL for iPad. */
e81c27 281 FOUNDATION_EXPORT FBSDKAppEventParameterProduct FBSDKAppEventParameterProductAppLinkIPadUrl;
13e53a 282
H 283 /** Parameter key used to specify the product item's AppLink app ID for iPad App Store. */
e81c27 284 FOUNDATION_EXPORT FBSDKAppEventParameterProduct FBSDKAppEventParameterProductAppLinkIPadAppStoreID;
13e53a 285
H 286 /** Parameter key used to specify the product item's AppLink app name for iPad. */
e81c27 287 FOUNDATION_EXPORT FBSDKAppEventParameterProduct FBSDKAppEventParameterProductAppLinkIPadAppName;
13e53a 288
H 289 /** Parameter key used to specify the product item's AppLink app URL for Android. */
e81c27 290 FOUNDATION_EXPORT FBSDKAppEventParameterProduct FBSDKAppEventParameterProductAppLinkAndroidUrl;
13e53a 291
H 292 /** Parameter key used to specify the product item's AppLink fully-qualified package name for intent generation. */
e81c27 293 FOUNDATION_EXPORT FBSDKAppEventParameterProduct FBSDKAppEventParameterProductAppLinkAndroidPackage;
13e53a 294
H 295 /** Parameter key used to specify the product item's AppLink app name for Android. */
e81c27 296 FOUNDATION_EXPORT FBSDKAppEventParameterProduct FBSDKAppEventParameterProductAppLinkAndroidAppName;
13e53a 297
H 298 /** Parameter key used to specify the product item's AppLink app URL for Windows Phone. */
e81c27 299 FOUNDATION_EXPORT FBSDKAppEventParameterProduct FBSDKAppEventParameterProductAppLinkWindowsPhoneUrl;
13e53a 300
H 301 /** Parameter key used to specify the product item's AppLink app ID, as a GUID, for App Store. */
e81c27 302 FOUNDATION_EXPORT FBSDKAppEventParameterProduct FBSDKAppEventParameterProductAppLinkWindowsPhoneAppID;
13e53a 303
H 304 /** Parameter key used to specify the product item's AppLink app name for Windows Phone. */
e81c27 305 FOUNDATION_EXPORT FBSDKAppEventParameterProduct FBSDKAppEventParameterProductAppLinkWindowsPhoneAppName;
bad748 306
W 307 /*
308  @methodgroup Predefined values to assign to event parameters that accompany events logged through the `logEvent` family
309  of methods on `FBSDKAppEvents`.  Common event parameters are provided in the `FBSDKAppEventParameterName*` constants.
310  */
311
e81c27 312 /// typedef for FBSDKAppEventParameterValue
H 313 typedef NSString *const FBSDKAppEventParameterValue NS_TYPED_EXTENSIBLE_ENUM NS_SWIFT_NAME(AppEvents.ParameterValue);
314
9febd9 315 /** Yes-valued parameter value to be used with parameter keys that need a Yes/No value */
e81c27 316 FOUNDATION_EXPORT FBSDKAppEventParameterValue FBSDKAppEventParameterValueYes;
bad748 317
9febd9 318 /** No-valued parameter value to be used with parameter keys that need a Yes/No value */
e81c27 319 FOUNDATION_EXPORT FBSDKAppEventParameterValue FBSDKAppEventParameterValueNo;
bad748 320
13e53a 321 /** Parameter key used to specify the type of ad in an FBSDKAppEventNameAdImpression
H 322  * or FBSDKAppEventNameAdClick event.
323  * E.g. "banner", "interstitial", "rewarded_video", "native" */
e81c27 324 FOUNDATION_EXPORT FBSDKAppEventParameterName FBSDKAppEventParameterNameAdType;
13e53a 325
H 326 /** Parameter key used to specify the unique ID for all events within a subscription
327  * in an FBSDKAppEventNameSubscribe or FBSDKAppEventNameStartTrial event. */
e81c27 328 FOUNDATION_EXPORT FBSDKAppEventParameterName FBSDKAppEventParameterNameOrderID;
H 329
330 /*
331  @methodgroup Predefined values to assign to user data store
332  */
333
334 /// typedef for FBSDKAppEventUserDataType
335 typedef NSString *const FBSDKAppEventUserDataType NS_TYPED_EXTENSIBLE_ENUM NS_SWIFT_NAME(AppEvents.UserDataType);
336
337 /** Parameter key used to specify user's email. */
338 FOUNDATION_EXPORT FBSDKAppEventUserDataType FBSDKAppEventEmail;
339
340 /** Parameter key used to specify user's first name. */
341 FOUNDATION_EXPORT FBSDKAppEventUserDataType FBSDKAppEventFirstName;
342
343 /** Parameter key used to specify user's last name. */
344 FOUNDATION_EXPORT FBSDKAppEventUserDataType FBSDKAppEventLastName;
345
346 /** Parameter key used to specify user's phone. */
347 FOUNDATION_EXPORT FBSDKAppEventUserDataType FBSDKAppEventPhone;
348
349 /** Parameter key used to specify user's date of birth. */
350 FOUNDATION_EXPORT FBSDKAppEventUserDataType FBSDKAppEventDateOfBirth;
351
352 /** Parameter key used to specify user's gender. */
353 FOUNDATION_EXPORT FBSDKAppEventUserDataType FBSDKAppEventGender;
354
355 /** Parameter key used to specify user's city. */
356 FOUNDATION_EXPORT FBSDKAppEventUserDataType FBSDKAppEventCity;
357
358 /** Parameter key used to specify user's state. */
359 FOUNDATION_EXPORT FBSDKAppEventUserDataType FBSDKAppEventState;
360
361 /** Parameter key used to specify user's zip. */
362 FOUNDATION_EXPORT FBSDKAppEventUserDataType FBSDKAppEventZip;
363
364 /** Parameter key used to specify user's country. */
365 FOUNDATION_EXPORT FBSDKAppEventUserDataType FBSDKAppEventCountry;
bad748 366
9febd9 367 /**
bad748 368
W 369
9febd9 370   Client-side event logging for specialized application analytics available through Facebook App Insights
bad748 371  and for use with Facebook Ads conversion tracking and optimization.
W 372
9febd9 373
W 374
bad748 375  The `FBSDKAppEvents` static class has a few related roles:
W 376
377  + Logging predefined and application-defined events to Facebook App Insights with a
378  numeric value to sum across a large number of events, and an optional set of key/value
379  parameters that define "segments" for this event (e.g., 'purchaserStatus' : 'frequent', or
380  'gamerLevel' : 'intermediate')
381
382  + Logging events to later be used for ads optimization around lifetime value.
383
384  + Methods that control the way in which events are flushed out to the Facebook servers.
385
386  Here are some important characteristics of the logging mechanism provided by `FBSDKAppEvents`:
387
388  + Events are not sent immediately when logged.  They're cached and flushed out to the Facebook servers
389  in a number of situations:
390  - when an event count threshold is passed (currently 100 logged events).
391  - when a time threshold is passed (currently 15 seconds).
392  - when an app has gone to background and is then brought back to the foreground.
393
394  + Events will be accumulated when the app is in a disconnected state, and sent when the connection is
395  restored and one of the above 'flush' conditions are met.
396
397  + The `FBSDKAppEvents` class is thread-safe in that events may be logged from any of the app's threads.
398
399  + The developer can set the `flushBehavior` on `FBSDKAppEvents` to force the flushing of events to only
400  occur on an explicit call to the `flush` method.
401
402  + The developer can turn on console debug output for event logging and flushing to the server by using
403  the `FBSDKLoggingBehaviorAppEvents` value in `[FBSettings setLoggingBehavior:]`.
404
405  Some things to note when logging events:
406
407  + There is a limit on the number of unique event names an app can use, on the order of 1000.
408  + There is a limit to the number of unique parameter names in the provided parameters that can
409  be used per event, on the order of 25.  This is not just for an individual call, but for all
410  invocations for that eventName.
411  + Event names and parameter names (the keys in the NSDictionary) must be between 2 and 40 characters, and
412  must consist of alphanumeric characters, _, -, or spaces.
413  + The length of each parameter value can be no more than on the order of 100 characters.
414
415  */
e81c27 416
H 417 NS_SWIFT_NAME(AppEvents)
bad748 418 @interface FBSDKAppEvents : NSObject
e81c27 419
H 420 - (instancetype)init NS_UNAVAILABLE;
421 + (instancetype)new NS_UNAVAILABLE;
422
423 /*
424  * Control over event batching/flushing
425  */
426
427 /**
428
429  The current event flushing behavior specifying when events are sent back to Facebook servers.
430  */
431 @property (class, nonatomic, assign) FBSDKAppEventsFlushBehavior flushBehavior;
432
433 /**
434  Set the 'override' App ID for App Event logging.
435
436
437
438  In some cases, apps want to use one Facebook App ID for login and social presence and another
439  for App Event logging.  (An example is if multiple apps from the same company share an app ID for login, but
440  want distinct logging.)  By default, this value is `nil`, and defers to the `FBSDKAppEventsOverrideAppIDBundleKey`
441  plist value.  If that's not set, it defaults to `[FBSDKSettings appID]`.
442
443  This should be set before any other calls are made to `FBSDKAppEvents`.  Thus, you should set it in your application
444  delegate's `application:didFinishLaunchingWithOptions:` delegate.
445  */
446 @property (class, nonatomic, copy, nullable) NSString *loggingOverrideAppID;
447
448 /*
449  The custom user ID to associate with all app events.
450
451  The userID is persisted until it is cleared by passing nil.
452  */
453 @property (class, nonatomic, copy, nullable) NSString *userID;
bad748 454
W 455 /*
456  * Basic event logging
457  */
458
9febd9 459 /**
bad748 460
9febd9 461   Log an event with just an eventName.
bad748 462
13e53a 463  @param eventName   The name of the event to record.  Limitations on number of events and name length
bad748 464  are given in the `FBSDKAppEvents` documentation.
W 465
466  */
e81c27 467 + (void)logEvent:(FBSDKAppEventName)eventName;
bad748 468
9febd9 469 /**
bad748 470
9febd9 471   Log an event with an eventName and a numeric value to be aggregated with other events of this name.
bad748 472
13e53a 473  @param eventName   The name of the event to record.  Limitations on number of events and name length
bad748 474  are given in the `FBSDKAppEvents` documentation.  Common event names are provided in `FBAppEventName*` constants.
W 475
13e53a 476  @param valueToSum  Amount to be aggregated into all events of this eventName, and App Insights will report
bad748 477  the cumulative and average value of this amount.
W 478  */
e81c27 479 + (void)logEvent:(FBSDKAppEventName)eventName
bad748 480       valueToSum:(double)valueToSum;
W 481
482
9febd9 483 /**
bad748 484
9febd9 485   Log an event with an eventName and a set of key/value pairs in the parameters dictionary.
bad748 486  Parameter limitations are described above.
W 487
13e53a 488  @param eventName   The name of the event to record.  Limitations on number of events and name construction
bad748 489  are given in the `FBSDKAppEvents` documentation.  Common event names are provided in `FBAppEventName*` constants.
W 490
13e53a 491  @param parameters  Arbitrary parameter dictionary of characteristics. The keys to this dictionary must
bad748 492  be NSString's, and the values are expected to be NSString or NSNumber.  Limitations on the number of
W 493  parameters and name construction are given in the `FBSDKAppEvents` documentation.  Commonly used parameter names
494  are provided in `FBSDKAppEventParameterName*` constants.
495  */
e81c27 496 + (void)logEvent:(FBSDKAppEventName)eventName
H 497       parameters:(NSDictionary<FBSDKAppEventParameterName, id> *)parameters;
bad748 498
9febd9 499 /**
bad748 500
9febd9 501   Log an event with an eventName, a numeric value to be aggregated with other events of this name,
bad748 502  and a set of key/value pairs in the parameters dictionary.
W 503
13e53a 504  @param eventName   The name of the event to record.  Limitations on number of events and name construction
bad748 505  are given in the `FBSDKAppEvents` documentation.  Common event names are provided in `FBAppEventName*` constants.
W 506
13e53a 507  @param valueToSum  Amount to be aggregated into all events of this eventName, and App Insights will report
bad748 508  the cumulative and average value of this amount.
W 509
13e53a 510  @param parameters  Arbitrary parameter dictionary of characteristics. The keys to this dictionary must
bad748 511  be NSString's, and the values are expected to be NSString or NSNumber.  Limitations on the number of
W 512  parameters and name construction are given in the `FBSDKAppEvents` documentation.  Commonly used parameter names
513  are provided in `FBSDKAppEventParameterName*` constants.
514
515  */
e81c27 516 + (void)logEvent:(FBSDKAppEventName)eventName
bad748 517       valueToSum:(double)valueToSum
e81c27 518       parameters:(NSDictionary<FBSDKAppEventParameterName, id> *)parameters;
bad748 519
W 520
9febd9 521 /**
bad748 522
9febd9 523   Log an event with an eventName, a numeric value to be aggregated with other events of this name,
bad748 524  and a set of key/value pairs in the parameters dictionary.  Providing session lets the developer
W 525  target a particular <FBSession>.  If nil is provided, then `[FBSession activeSession]` will be used.
526
13e53a 527  @param eventName   The name of the event to record.  Limitations on number of events and name construction
bad748 528  are given in the `FBSDKAppEvents` documentation.  Common event names are provided in `FBAppEventName*` constants.
W 529
13e53a 530  @param valueToSum  Amount to be aggregated into all events of this eventName, and App Insights will report
bad748 531  the cumulative and average value of this amount.  Note that this is an NSNumber, and a value of `nil` denotes
W 532  that this event doesn't have a value associated with it for summation.
533
13e53a 534  @param parameters  Arbitrary parameter dictionary of characteristics. The keys to this dictionary must
bad748 535  be NSString's, and the values are expected to be NSString or NSNumber.  Limitations on the number of
W 536  parameters and name construction are given in the `FBSDKAppEvents` documentation.  Commonly used parameter names
537  are provided in `FBSDKAppEventParameterName*` constants.
538
13e53a 539  @param accessToken  The optional access token to log the event as.
bad748 540  */
e81c27 541 + (void)logEvent:(FBSDKAppEventName)eventName
H 542       valueToSum:(nullable NSNumber *)valueToSum
543       parameters:(NSDictionary<FBSDKAppEventParameterName, id> *)parameters
544      accessToken:(nullable FBSDKAccessToken *)accessToken;
bad748 545
W 546 /*
547  * Purchase logging
548  */
549
9febd9 550 /**
bad748 551
9febd9 552   Log a purchase of the specified amount, in the specified currency.
bad748 553
13e53a 554  @param purchaseAmount    Purchase amount to be logged, as expressed in the specified currency.  This value
bad748 555  will be rounded to the thousandths place (e.g., 12.34567 becomes 12.346).
W 556
13e53a 557  @param currency          Currency, is denoted as, e.g. "USD", "EUR", "GBP".  See ISO-4217 for
bad748 558  specific values.  One reference for these is <http://en.wikipedia.org/wiki/ISO_4217>.
W 559
9febd9 560
W 561               This event immediately triggers a flush of the `FBSDKAppEvents` event queue, unless the `flushBehavior` is set
bad748 562  to `FBSDKAppEventsFlushBehaviorExplicitOnly`.
W 563
564  */
565 + (void)logPurchase:(double)purchaseAmount
566            currency:(NSString *)currency;
567
9febd9 568 /**
bad748 569
9febd9 570   Log a purchase of the specified amount, in the specified currency, also providing a set of
bad748 571  additional characteristics describing the purchase.
W 572
13e53a 573  @param purchaseAmount  Purchase amount to be logged, as expressed in the specified currency.This value
bad748 574  will be rounded to the thousandths place (e.g., 12.34567 becomes 12.346).
W 575
13e53a 576  @param currency        Currency, is denoted as, e.g. "USD", "EUR", "GBP".  See ISO-4217 for
bad748 577  specific values.  One reference for these is <http://en.wikipedia.org/wiki/ISO_4217>.
W 578
13e53a 579  @param parameters      Arbitrary parameter dictionary of characteristics. The keys to this dictionary must
bad748 580  be NSString's, and the values are expected to be NSString or NSNumber.  Limitations on the number of
W 581  parameters and name construction are given in the `FBSDKAppEvents` documentation.  Commonly used parameter names
582  are provided in `FBSDKAppEventParameterName*` constants.
583
9febd9 584
W 585               This event immediately triggers a flush of the `FBSDKAppEvents` event queue, unless the `flushBehavior` is set
bad748 586  to `FBSDKAppEventsFlushBehaviorExplicitOnly`.
W 587
588  */
589 + (void)logPurchase:(double)purchaseAmount
590            currency:(NSString *)currency
e81c27 591          parameters:(NSDictionary<NSString *, id> *)parameters;
bad748 592
9febd9 593 /**
bad748 594
9febd9 595   Log a purchase of the specified amount, in the specified currency, also providing a set of
bad748 596  additional characteristics describing the purchase, as well as an <FBSession> to log to.
W 597
13e53a 598  @param purchaseAmount  Purchase amount to be logged, as expressed in the specified currency.This value
bad748 599  will be rounded to the thousandths place (e.g., 12.34567 becomes 12.346).
W 600
13e53a 601  @param currency        Currency, is denoted as, e.g. "USD", "EUR", "GBP".  See ISO-4217 for
bad748 602  specific values.  One reference for these is <http://en.wikipedia.org/wiki/ISO_4217>.
W 603
13e53a 604  @param parameters      Arbitrary parameter dictionary of characteristics. The keys to this dictionary must
bad748 605  be NSString's, and the values are expected to be NSString or NSNumber.  Limitations on the number of
W 606  parameters and name construction are given in the `FBSDKAppEvents` documentation.  Commonly used parameter names
607  are provided in `FBSDKAppEventParameterName*` constants.
608
13e53a 609  @param accessToken  The optional access token to log the event as.
bad748 610
9febd9 611
W 612             This event immediately triggers a flush of the `FBSDKAppEvents` event queue, unless the `flushBehavior` is set
bad748 613  to `FBSDKAppEventsFlushBehaviorExplicitOnly`.
W 614
615  */
616 + (void)logPurchase:(double)purchaseAmount
617            currency:(NSString *)currency
e81c27 618          parameters:(NSDictionary<NSString *, id> *)parameters
H 619         accessToken:(nullable FBSDKAccessToken *)accessToken;
bad748 620
W 621
622 /*
623  * Push Notifications Logging
624  */
625
9febd9 626 /**
W 627   Log an app event that tracks that the application was open via Push Notification.
bad748 628
13e53a 629  @param payload Notification payload received via `UIApplicationDelegate`.
bad748 630  */
W 631 + (void)logPushNotificationOpen:(NSDictionary *)payload;
632
9febd9 633 /**
W 634   Log an app event that tracks that a custom action was taken from a push notification.
bad748 635
13e53a 636  @param payload Notification payload received via `UIApplicationDelegate`.
H 637  @param action  Name of the action that was taken.
bad748 638  */
W 639 + (void)logPushNotificationOpen:(NSDictionary *)payload action:(NSString *)action;
13e53a 640
H 641 /**
642   Uploads product catalog product item as an app event
643   @param itemID            Unique ID for the item. Can be a variant for a product.
644                            Max size is 100.
645   @param availability      If item is in stock. Accepted values are:
646                               in stock - Item ships immediately
647                               out of stock - No plan to restock
648                               preorder - Available in future
649                               available for order - Ships in 1-2 weeks
650                               discontinued - Discontinued
651   @param condition         Product condition: new, refurbished or used.
652   @param description       Short text describing product. Max size is 5000.
653   @param imageLink         Link to item image used in ad.
654   @param link              Link to merchant's site where someone can buy the item.
655   @param title             Title of item.
656   @param priceAmount       Amount of purchase, in the currency specified by the 'currency'
657                            parameter. This value will be rounded to the thousandths place
658                            (e.g., 12.34567 becomes 12.346).
659   @param currency          Currency used to specify the amount.
660                            E.g. "USD", "EUR", "GBP".  See ISO-4217 for specific values. One reference for these is <http://en.wikipedia.org/wiki/ISO_4217>
661   @param gtin              Global Trade Item Number including UPC, EAN, JAN and ISBN
662   @param mpn               Unique manufacture ID for product
663   @param brand             Name of the brand
664                            Note: Either gtin, mpn or brand is required.
665   @param parameters        Optional fields for deep link specification.
666  */
667 + (void)logProductItem:(NSString *)itemID
668           availability:(FBSDKProductAvailability)availability
669              condition:(FBSDKProductCondition)condition
670            description:(NSString *)description
671              imageLink:(NSString *)imageLink
672                   link:(NSString *)link
673                  title:(NSString *)title
674            priceAmount:(double)priceAmount
675               currency:(NSString *)currency
e81c27 676                   gtin:(nullable NSString *)gtin
H 677                    mpn:(nullable NSString *)mpn
678                  brand:(nullable NSString *)brand
679             parameters:(nullable NSDictionary<NSString *, id> *)parameters;
bad748 680
9febd9 681 /**
bad748 682
37c026 683   Notifies the events system that the app has launched and, when appropriate, logs an "activated app" event.
H 684  This function is called automatically from FBSDKApplicationDelegate applicationDidBecomeActive, unless
685  one overrides 'FacebookAutoLogAppEventsEnabled' key to false in the project info plist file.
686  In case 'FacebookAutoLogAppEventsEnabled' is set to false, then it should typically be placed in the
bad748 687  app delegates' `applicationDidBecomeActive:` method.
W 688
689  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
690  track user acquisition and app install ads conversions.
691
9febd9 692
W 693
bad748 694  `activateApp` will not log an event on every app launch, since launches happen every time the app is backgrounded and then foregrounded.
W 695  "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"
696  event to be logged when sessions are "completed", and these events are logged with the session length, with an indication of how much
697  time has elapsed between sessions, and with the number of background/foreground interruptions that session had.  This data
698  is all visible in your app's App Events Insights.
699  */
700 + (void)activateApp;
701
702 /*
13e53a 703  * Push Notifications Registration and Uninstall Tracking
bad748 704  */
W 705
9febd9 706 /**
37c026 707   Sets and sends device token to register the current application for push notifications.
bad748 708
9febd9 709
W 710
37c026 711  Sets and sends a device token from `NSData` representation that you get from `UIApplicationDelegate.-application:didRegisterForRemoteNotificationsWithDeviceToken:`.
bad748 712
13e53a 713  @param deviceToken Device token data.
bad748 714  */
W 715 + (void)setPushNotificationsDeviceToken:(NSData *)deviceToken;
13e53a 716
H 717 /**
718  Sets and sends device token string to register the current application for push notifications.
719
720
721
722  Sets and sends a device token string
723
724  @param deviceTokenString Device token string.
725  */
e81c27 726 + (void)setPushNotificationsDeviceTokenString:(NSString *)deviceTokenString
H 727 NS_SWIFT_NAME(setPushNotificationsDeviceToken(_:));
bad748 728
9febd9 729 /**
W 730   Explicitly kick off flushing of events to Facebook.  This is an asynchronous method, but it does initiate an immediate
bad748 731  kick off.  Server failures will be reported through the NotificationCenter with notification ID `FBSDKAppEventsLoggingResultNotification`.
W 732  */
733 + (void)flush;
734
9febd9 735 /**
W 736   Creates a request representing the Graph API call to retrieve a Custom Audience "third party ID" for the app's Facebook user.
bad748 737  Callers will send this ID back to their own servers, collect up a set to create a Facebook Custom Audience with,
W 738  and then use the resultant Custom Audience to target ads.
9febd9 739
bad748 740  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 741  This ID is an encrypted encoding of the Facebook user's ID and the invoking Facebook app ID.
742  Multiple calls with the same user will return different IDs, thus these IDs cannot be used to correlate behavior
743  across devices or applications, and are only meaningful when sent back to Facebook for creating Custom Audiences.
744
745  The ID retrieved represents the Facebook user identified in the following way: if the specified access token is valid,
746  the ID will represent the user associated with that token; otherwise the ID will represent the user logged into the
747  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
748  at the iOS level from ad tracking, then a `nil` ID will be returned.
749
750  This method returns `nil` if either the user has opted-out (via iOS) from Ad Tracking, the app itself has limited event usage
751  via the `[FBSDKSettings limitEventAndDataUsage]` flag, or a specific Facebook user cannot be identified.
9febd9 752
e81c27 753  @param accessToken The access token to use to establish the user's identity for users logged into Facebook through this app.
H 754  If `nil`, then the `[FBSDKAccessToken currentAccessToken]` is used.
9febd9 755  */
e81c27 756 + (nullable FBSDKGraphRequest *)requestForCustomAudienceThirdPartyIDWithAccessToken:(nullable FBSDKAccessToken *)accessToken;
9febd9 757
W 758 /*
9f077b 759  Clears the custom user ID to associate with all app events.
H 760  */
761 + (void)clearUserID;
13e53a 762
H 763 /*
764   Sets custom user data to associate with all app events. All user data are hashed
765   and used to match Facebook user from this instance of an application.
766
767   The user data will be persisted between application instances.
768
769  @param email user's email
770  @param firstName user's first name
771  @param lastName user's last name
772  @param phone user's phone
773  @param dateOfBirth user's date of birth
774  @param gender user's gender
775  @param city user's city
776  @param state user's state
777  @param zip user's zip
778  @param country user's country
779  */
e81c27 780 + (void)setUserEmail:(nullable NSString *)email
H 781            firstName:(nullable NSString *)firstName
782             lastName:(nullable NSString *)lastName
783                phone:(nullable NSString *)phone
784          dateOfBirth:(nullable NSString *)dateOfBirth
785               gender:(nullable NSString *)gender
786                 city:(nullable NSString *)city
787                state:(nullable NSString *)state
788                  zip:(nullable NSString *)zip
789              country:(nullable NSString *)country
790 NS_SWIFT_NAME(setUser(email:firstName:lastName:phone:dateOfBirth:gender:city:state:zip:country:));
791
13e53a 792 /*
H 793   Returns the set user data else nil
794 */
e81c27 795 + (nullable NSString *)getUserData;
13e53a 796
H 797 /*
798   Clears the current user data
799 */
800 + (void)clearUserData;
e81c27 801
H 802 /*
803  Sets custom user data to associate with all app events. All user data are hashed
804  and used to match Facebook user from this instance of an application.
805
806  The user data will be persisted between application instances.
807
808  @param data  data
809  @param type  data type, e.g. FBSDKAppEventEmail, FBSDKAppEventPhone
810  */
811 + (void)setUserData:(nullable NSString *)data
812             forType:(FBSDKAppEventUserDataType)type;
813
814 /*
815  Clears the current user data of certain type
816  */
817 + (void)clearUserDataForType:(FBSDKAppEventUserDataType)type;
13e53a 818
H 819 /*
9febd9 820   Sends a request to update the properties for the current user, set by `setUserID:`
W 821
822  You must call `FBSDKAppEvents setUserID:` before making this call.
13e53a 823  @param properties the custom user properties
H 824  @param handler the optional completion handler
9febd9 825  */
e81c27 826 + (void)updateUserProperties:(NSDictionary<NSString *, id> *)properties handler:(nullable FBSDKGraphRequestBlock)handler;
9febd9 827
9f077b 828 #if !TARGET_OS_TV
H 829 /*
830   Intended to be used as part of a hybrid webapp.
831  If you call this method, the FB SDK will inject a new JavaScript object into your webview.
832  If the FB Pixel is used within the webview, and references the app ID of this app,
833  then it will detect the presence of this injected JavaScript object
834  and pass Pixel events back to the FB SDK for logging using the AppEvents framework.
835
13e53a 836  @param webView The webview to augment with the additional JavaScript behaviour
9f077b 837  */
H 838 + (void)augmentHybridWKWebView:(WKWebView *)webView;
839 #endif
840
13e53a 841 /*
H 842  * Unity helper functions
843  */
844
845 /**
846
847  Set if the Unity is already initialized
848
849  @param isUnityInit   whether Unity is initialized.
850
851  */
852 + (void)setIsUnityInit:(BOOL)isUnityInit;
853
854 /*
855  Send event binding to Unity
856  */
857 + (void)sendEventBindingsToUnity;
858
bad748 859 @end
e81c27 860
H 861 NS_ASSUME_NONNULL_END