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