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