|
Braze iOS SDK
Documentation for the Braze iOS SDK
|
|
Braze iOS SDK
Documentation for the Braze iOS SDK
|
Instance Methods | |
| (void) | - requestImmediateDataFlush |
|
("Please use `requestImmediateDataFlush` instead.") | - __deprecated_msg |
| (void) | - shutdownServerCommunication |
| (void) | - changeUser: |
| (void) | - changeUser:sdkAuthSignature: |
| (void) | - setSdkAuthenticationSignature: |
| (void) | - unsubscribeFromSdkAuthenticationErrors |
| (void) | - logCustomEvent: |
Class Methods | |
| (nullable Appboy *) | + sharedInstance |
| (nonnull Appboy *) | + unsafeInstance |
| (void) | + startWithApiKey:inApplication:withLaunchOptions: |
| (void) | + startWithApiKey:inApplication:withLaunchOptions:withAppboyOptions: |
| - (void) addSdkMetadata: | (NSArray< ABKSdkMetadata > *) | metadata |
Adds SDK Metadata values to those automatically collected by the SDK.
Metadata tell Braze how the SDK is integrated (e.g. wrapper, package manager, etc.)
| metadata | The metadata values reflecting the current SDK integration. |
| - (void) changeUser: | (NSString *) | userId |
| userId | The new user's ID (from the host application). |
This method changes the user's ID. These user IDs should be private and not easily obtained (e.g. not a plain email address or username).
When you first start using Braze on a device, the user is considered "anonymous". You can use this method to optionally identify a user with a unique ID, which enables the following:
Note: Once you identify a user, you cannot go back to the "anonymous" profile. The transition from anonymous to identified tracking only happens once because the initial anonymous user receives special treatment to allow for preservation of their history. We recommend against changing the user id just because your app has entered a "logged out" state because it separates this device from the user profile and thus you will be unable to target the previously logged out user with re-engagement campaigns. If you anticipate multiple users on the same device, but only want to target one of them when your app is in a logged out state, we recommend separately keeping track of the user ID you want to target while logged out and switching back to that user ID as part of your app's logout process.
| - (void) changeUser: | (NSString *) | userId | |
| sdkAuthSignature: | (nullable NSString *) | signature | |
| userId | The new user's ID (from the host application) |
| signature | The SDK Authentication signature for the user being identified. |
See documantation for changeUser: above
| + (void) disableSDK |
This method immediately disables the Braze iOS SDK. After this method is called, the sharedInstance singleton will be nulled out and Braze functionality will be disabled until the SDK is re-enabled via a call to requestEnableSDKOnNextAppRun: and re-initialized in a subsequent app run via a call to startWithApiKey:. All references to the previous singleton should be released.
Note that the next call to startWithApiKey: must take place in a subsequent app run. Initializing the SDK within the same app run after calling this method is not supported.
Unlike with wipeDataAndDisableForAppRun:, calling requestEnableSDKOnNextAppRun: is required to re-enable the SDK after the method is called.
Note that if you are using unsafeInstance:, further calls to unsafeInstance: after using this method will cause an exception to be thrown. We do not recommend using this method in concert with unsafeInstance:.
| - (void) getActionWithIdentifier: | (NSString *) | identifier | |
| forRemoteNotification: | (NSDictionary *) | userInfo | |
| completionHandler: | (8_0) | ||
| (10_0) | |||
| ("`getActionWithIdentifier:forRemoteNotification:completionHandler:` is deprecated in iOS) | 10 | ||
| (please use`userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler:`instead.") | NS_DEPRECATED_IOS | ||
| identifier | The action identifier passed in from the handleActionWithIdentifier:forRemoteNotification:. |
| userInfo | An NSDictionary passed in from the handleActionWithIdentifier:forRemoteNotification: call. |
| completionHandler | A block passed in from the didReceiveRemoteNotification:fetchCompletionHandler: call |
This method forwards remote notifications and the custom action chosen by user to Braze. Call it from the application:handleActionWithIdentifier:forRemoteNotification: method of your App Delegate.
| - (NSString *) getDeviceId |
Get the device ID - the IDFV - which will reset if all apps for a given vendor are removed from the device.
| - (void) logContentCardsDisplayed |
If you're displaying content cards on your own instead of using ABKContentCardsViewController, you should still report impressions of the content cards back to Braze with this method so that your campaign reporting features still work in the dashboard.
| - (void) logCustomEvent: | (NSString *) | eventName |
| eventName | The name of the event to log. |
Adds an app specific event to event tracking log that's lazily pushed up to the server. Think of events like counters. That is, each time you log an event, we'll update a counter for that user. Events should be fairly broad like "beat level 1" or "watched video" instead of something more specific like "watched Katy Perry's Last Friday Night" so you can create more broad user segments for targeting.
[[Appboy sharedInstance] logCustomEvent:"clicked_button"];
| - (void) logCustomEvent: | (NSString *) | eventName | |
| withProperties: | (nullable NSDictionary *) | properties | |
| eventName | The name of the event to log. |
| properties | An NSDictionary of properties to associate with this purchase. Property keys are non-empty NSString objects with <= 255 characters and no leading dollar signs. Property values can be NSNumber booleans, integers, floats < 62 bits, NSDate objects, NSString objects with <= 255 characters, or any JSON Encodable object including NSArray and NSDictionary of the previous data types (nested properties). Total length of encoded properties must be under 50 KB. |
Adds an app specific event to event tracking log that's lazily pushed up to the server. Think of events like counters. That is, each time you log an event, we'll update a counter for that user. Events should be fairly broad like "beat level 1" or "watched video" instead of something more specific like "watched Katy Perry's Last Friday Night" so you can create more broad user segments for targeting.
[[Appboy sharedInstance] logCustomEvent:"clicked_button" properties:@"key1":@"val"}];
| - (void) logFeedDisplayed |
If you're displaying cards on your own instead of using ABKFeedViewController, you should still report impressions of the news feed back to Braze with this method so that your campaign reporting features still work in the dashboard.
| - (void) logPurchase: | (NSString *) | productIdentifier | |
| inCurrency: | (NSString *) | currencyCode | |
| atPrice: | (NSDecimalNumber *) | price | |
This method is equivalent to calling logPurchase:inCurrency:atPrice:withQuantity:andProperties: with a quantity of 1 and nil properties. Please see logPurchase:inCurrency:atPrice:withQuantity:andProperties: for more information.
| - (void) logPurchase: | (NSString *) | productIdentifier | |
| inCurrency: | (NSString *) | currencyCode | |
| atPrice: | (NSDecimalNumber *) | price | |
| withProperties: | (nullable NSDictionary *) | properties | |
This method is equivalent to calling logPurchase:inCurrency:atPrice:withQuantity:andProperties with a quantity of 1. Please see logPurchase:inCurrency:atPrice:withQuantity:andProperties: for more information.
| - (void) logPurchase: | (NSString *) | productIdentifier | |
| inCurrency: | (NSString *) | currencyCode | |
| atPrice: | (NSDecimalNumber *) | price | |
| withQuantity: | (NSUInteger) | quantity | |
This method is equivalent to calling logPurchase:inCurrency:atPrice:withQuantity:andProperties with nil properties. Please see logPurchase:inCurrency:atPrice:withQuantity:andProperties: for more information.
| - (void) logPurchase: | (NSString *) | productIdentifier | |
| inCurrency: | (NSString *) | currencyCode | |
| atPrice: | (NSDecimalNumber *) | price | |
| withQuantity: | (NSUInteger) | quantity | |
| andProperties: | (nullable NSDictionary *) | properties | |
| productIdentifier | A String indicating the product that was purchased. Usually the product identifier in the iTunes store. |
| currencyCode | Currencies should be represented as an ISO 4217 currency code. Prices should be sent in decimal format, with the same base units as are provided by the SKProduct class. Callers of this method who have access to the NSLocale object for the purchase in question (which can be obtained from SKProduct listings provided by StoreKit) can obtain the currency code by invoking: [locale objectForKey:NSLocaleCurrencyCode]Supported currency symbols include: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTC, BTN, BWP, BYR, BZD, CAD, CDF, CHF, CLF, CLP, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EEK, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GGP, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, IMP, INR, IQD, IRR, ISK, JEP, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MTL, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SRD, STD, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VEF, VND, VUV, WST, XAF, XAG, XAU, XCD, XDR, XOF, XPD, XPF, XPT, YER, ZAR, ZMK, ZMW and ZWL. Any other provided currency symbol will result in a logged warning and no other action taken by the SDK. |
| price | Prices should be reported as NSDecimalNumber objects. Base units are treated the same as with SKProduct from StoreKit and depend on the currency. As an example, USD should be reported as Dollars.Cents, whereas JPY should be reported as a whole number of Yen. All provided NSDecimalNumber values will have NSRoundPlain rounding applied such that a maximum of two digits exist after their decimal point. |
| quantity | An unsigned number to indicate the purchase quantity. This number must be greater than 0 but no larger than 100. |
| properties | An NSDictionary of properties to associate with this purchase. Property keys are non-empty NSString objects with <= 255 characters and no leading dollar signs. Property values can be NSNumber integers, floats, booleans < 62 bits in length, NSDate objects or NSString objects with <= 255 characters. |
Logs a purchase made in the application.
Note: Braze supports purchases in multiple currencies. Purchases that you report in a currency other than USD will be shown in the dashboard in USD based on the exchange rate at the date they were reported.
| - (void) pushAuthorizationFromUserNotificationCenter: | (BOOL) | pushAuthGranted |
| pushAuthGranted | The boolean value passed in from completionHandler in UNUserNotificationCenter's requestAuthorizationWithOptions:completionHandler: method, which indicates if the push authorization was granted or not. |
This method forwards the push authorization result to Braze after the user interacts with the notification prompt. Call it from the UNUserNotificationCenter's requestAuthorizationWithOptions:completionHandler: method when you prompt users to enable push.
| - (void) registerApplication: | (UIApplication *) | application | |
| didReceiveRemoteNotification: | (3_0) | ||
| (10_0) | |||
| ("`registerApplication:didReceiveRemoteNotification:` is deprecated in iOS) | 10 | ||
| (please use`registerApplication:didReceiveRemoteNotification:fetchCompletionHandler:`instead.") | NS_DEPRECATED_IOS | ||
| application | The app's UIApplication object |
| notification | An NSDictionary passed in from the didReceiveRemoteNotification call |
This method forwards remote notifications to Braze. Call it from the application:didReceiveRemoteNotification method of your App Delegate.
| - (void) registerApplication: | (UIApplication *) | application | |
| didReceiveRemoteNotification: | (NSDictionary *) | notification | |
| fetchCompletionHandler: | (UIBackgroundFetchResult) | completionHandler | |
| application | The app's UIApplication object |
| notification | An NSDictionary passed in from the didReceiveRemoteNotification:fetchCompletionHandler: call |
| completionHandler | A block passed in from the didReceiveRemoteNotification:fetchCompletionHandler: call |
This method forwards remote notifications to Braze. If the completionHandler is passed in when the method is called, Braze will call the completionHandler. However, if the completionHandler is not passed in, it is the host app's responsibility to call the completionHandler. Call it from the application:didReceiveRemoteNotification:fetchCompletionHandler: method of your App Delegate.
| - (void) registerDeviceToken: | (NSData *) | deviceToken |
| deviceToken | The device's push token. |
This method posts a token to Braze servers to associate the token with the current device.
| - (void) requestContentCardsRefresh |
Enqueues a content cards request for the current user.
| + (void) requestEnableSDKOnNextAppRun |
This method requests the Braze iOS SDK to be re-enabled on the next app run. After this method is called, the following call to startWithApiKey: will successfully re-enable the SDK. Braze functionality will remain disabled until that point.
Note that this method does not re-initialize the Appboy singleton on its own nor re-enable Braze functionality immediately.
| - (void) requestFeedRefresh |
Enqueues a news feed request for the current user. Note that if the queue already contains another request for the current user, that the new feed request will be merged into the already existing request and only one will execute for that user.
When the new cards for news feed return from Braze server, the SDK will post an ABKFeedUpdatedNotification with an ABKFeedUpdatedIsSuccessfulKey in the notification's userInfo dictionary to indicate if the news feed request is successful or not. For more detail about the ABKFeedUpdatedNotification and the ABKFeedUpdatedIsSuccessfulKey, please check ABKFeedController.
| - (void) requestGeofencesWithLongitude: | (double) | longitude | |
| latitude: | (double) | latitude | |
Manually request geofences with a specific location.
| - (void) requestImmediateDataFlush |
Enqueues a data flush request for the current user and immediately starts processing the network queue. Note that if the queue already contains another request for the current user, that the new data flush request will be merged into the already existing request and only one will execute for that user.
If you're using ABKManualRequestProcessing, you only need to call this when you want to force an immediate flush of updated user data.
| - (void) setSdkAuthenticationSignature: | (NSString *) | signature |
| signature | The SDK Authentication signature for the current user |
Sets the signature used for SDK authentication for the current user.
| + (nullable Appboy *) sharedInstance |
Get the Appboy singleton. Returns nil if accessed before startWithApiKey: called.
| - (void) shutdownServerCommunication |
Stops all in flight server communication and enables manual request processing control to ensure that no automatic network activity occurs. You should usually only call shutdownServerCommunication if the OS is forcing you to stop background tasks upon exit of your application. To continue normal operation after calling this, you will need to explicitly set the request processing mode back to your desired state.
| + (void) startWithApiKey: | (NSString *) | apiKey | |
| inApplication: | (UIApplication *) | application | |
| withLaunchOptions: | (nullable NSDictionary *) | launchOptions | |
| apiKey | The app's API key |
| application | the current app |
| launchOptions | The options NSDictionary that you get from application:didFinishLaunchingWithOptions |
Starts up Braze and tells it that your app is done launching. You should call this method in your App Delegate application:didFinishLaunchingWithOptions method before calling makeKeyAndVisible, accessing [Appboy sharedInstance] or otherwise rendering Braze view controllers. Your apiKey comes from the Braze dashboard where you registered your app.
| + (void) startWithApiKey: | (NSString *) | apiKey | |
| inApplication: | (UIApplication *) | application | |
| withLaunchOptions: | (nullable NSDictionary *) | launchOptions | |
| withAppboyOptions: | (nullable NSDictionary *) | appboyOptions | |
| apiKey | The app's API key |
| application | The current app |
| launchOptions | The options NSDictionary that you get from application:didFinishLaunchingWithOptions |
| appboyOptions | An optional NSDictionary with startup configuration values for Braze. See below for more information. |
Starts up Braze and tells it that your app is done launching. You should call this method in your App Delegate application:didFinishLaunchingWithOptions method before calling makeKeyAndVisible, accessing [Appboy sharedInstance] or otherwise rendering Braze view controllers. Your apiKey comes from the Braze dashboard where you registered your app.
| + (nonnull Appboy *) unsafeInstance |
Get the Appboy singleton. Throws an exception if accessed before startWithApiKey: is called.
| - (void) unsubscribeFromSdkAuthenticationErrors |
Unsubscribe from SDK Authentication errors. After this method is called, the ABKSdkAuthenticationDelegate method handleSdkAuthenticationError: will not be called in the event of an SDK Authentication error.
| - (void) userNotificationCenter: | (UNUserNotificationCenter *) | center | |
| didReceiveNotificationResponse: | (UNNotificationResponse *) | response | |
| withCompletionHandler: | (10_0) | NS_AVAILABLE_IOS | |
| center | The app's current UNUserNotificationCenter object |
| response | The UNNotificationResponse object passed in from the didReceiveNotificationResponse:withCompletionHandler: call |
| completionHandler | A block passed in from the didReceiveNotificationResponse:withCompletionHandler: call. Braze will call it at the end of the method if one is passed in. If you prefer to handle the completionHandler youself, please pass nil to Braze. |
This method forwards the response of the notification to Braze after user interacted with the notification. Call it from the userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler: method of your App Delegate.
| + (void) wipeDataAndDisableForAppRun |
This method immediately wipes all data from the Braze iOS SDK. After this method is called, the sharedInstance singleton will be nulled out and Braze functionality will be disabled until the next call to startWithApiKey: in a subsequent app run. All references to the previous singleton should be released.
Note that the next call to startWithApiKey: must take place in a subsequent app run. Initializing the SDK within the same app run after calling this method is not supported.
The SDK will automatically re-enable itself when startWithApiKey: is called. There is no need to call requestEnableSDKOnNextAppRun: to re-enable the SDK. wipeDataAndDisableForAppRun: may be used at any time, including while the SDK is otherwise disabled.
Note that if you are using unsafeInstance:, further calls to unsafeInstance: after using this method will cause an uncaught exception to be thrown. We do not recommend using this method in concert with unsafeInstance:.
|
readwritenonatomicweak |
A class conforming to the ABKURLDelegate protocol can be set to handle URLs in a custom way.
|
readwritenonatomicstrong |
A class extending ABKIDFADelegate can be set to provide the IDFA to Braze.
|
readwritenonatomicstrong |
A class conforming to ABKImageDelegate can be set to use a custom image library.
|
readatomicassign |
The current in-app message manager. See ABKInAppMessageController.h.
|
readnonatomicassign |
The Braze location manager provides access to location related functionality in the Braze SDK. See ABKLocationManager.h.
|
readwriteatomic |
The policy regarding processing of network requests by the SDK. See the enumeration values for more information on possible options. This value can be set at runtime, or can be injected in at startup via the appboyOptions dictionary.
Any time the request processing policy is set to manual, any scheduled flush of the queue is canceled, but if the request queue was already processing, the current queue will finish processing. If you need to cancel in flight requests, you need to call
[[Appboy sharedInstance] shutdownServerCommunication]
.
Setting the request policy does not automatically cause a flush to occur, it just allows for a flush to be scheduled the next time an eligible request is enqueued. To force an immediate flush after changing the request processing policy, invoke
[[Appboy sharedInstance] requestImmediateDataFlush]
.
|
readwritenonatomicstrong |
A class conforming to ABKSdkAuthenticationDelegate can be set to handle SDK Authentication errors.
|
readwritenonatomicassign |
Property for internal reporting of SDK flavor.
|
readnonatomicassign |
A custom NSURLSessionConfiguration for configuring network session parameters.
1.8.3.1
