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