Braze iOS SDK
Documentation for the Braze iOS SDK
 All Classes Functions Properties
Instance Methods | Class Methods | Properties | List of all members
Appboy Class Reference

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:
 

Properties

ABKUseruser
 
ABKFeedControllerfeedController
 
ABKContentCardsControllercontentCardsController
 
ABKRequestProcessingPolicy requestProcessingPolicy
 
id< ABKIDFADelegateidfaDelegate
 
id< ABKSdkAuthenticationDelegatesdkAuthenticationDelegate
 
NSURLSessionConfiguration * urlSessionConfiguration
 
ABKInAppMessageControllerinAppMessageController
 
ABKLocationManagerlocationManager
 
id< ABKURLDelegateappboyUrlDelegate
 
id< ABKImageDelegateimageDelegate
 
ABKSDKFlavor sdkFlavor
 
(void) + wipeDataAndDisableForAppRun
 
(void) + disableSDK
 
(void) + requestEnableSDKOnNextAppRun
 
(void) - logCustomEvent:withProperties:
 
(void) - logPurchase:inCurrency:atPrice:
 
(void) - logPurchase:inCurrency:atPrice:withProperties:
 
(void) - logPurchase:inCurrency:atPrice:withQuantity:
 
(void) - logPurchase:inCurrency:atPrice:withQuantity:andProperties:
 
(void) - logFeedDisplayed
 
(void) - logContentCardsDisplayed
 
(void) - requestFeedRefresh
 
(void) - requestContentCardsRefresh
 
(void) - requestGeofencesWithLongitude:latitude:
 
(NSString *) - getDeviceId
 
(void) - registerDeviceToken:
 
(void) - registerApplication:didReceiveRemoteNotification:
 
(void) - registerApplication:didReceiveRemoteNotification:fetchCompletionHandler:
 
(void) - getActionWithIdentifier:forRemoteNotification:completionHandler:
 
(void) - userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler:
 
(void) - pushAuthorizationFromUserNotificationCenter:
 
(void) - addSdkMetadata:
 

Method Documentation

- (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.)

Parameters
metadataThe metadata values reflecting the current SDK integration.
- (void) changeUser: (NSString *)  userId
Parameters
userIdThe 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:

  • If the same user is identified on another device, their user profile, usage history and event history will be shared across devices.
  • If your app is used by multiple people, you can assign each of them a unique identifier to track them separately. Only the most recent user on a particular device will receive push notifications and in-app messages.
  • If you identify a user which has never been identified on another device, the entire history of that user as an "anonymous" user on this device will be preserved and associated with the newly identified user.
  • However, if you identify a user which has been identified on another device, the previous anonymous history of the user on this device will not be added to the already existing profile for that user.
  • Note that switching from one an anonymous user to an identified user or from one identified user to another is a relatively costly operation. When you request the user switch, the current session for the previous user is automatically closed and a new session is started. Braze will also automatically make a data refresh request to get the news feed, in-app message and other information for the new user.

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 
Parameters
userIdThe new user's ID (from the host application)
signatureThe 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 
Parameters
identifierThe action identifier passed in from the handleActionWithIdentifier:forRemoteNotification:.
userInfoAn NSDictionary passed in from the handleActionWithIdentifier:forRemoteNotification: call.
completionHandlerA 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.

Returns
The device ID.
- (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
Parameters
eventNameThe 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 
Parameters
eventNameThe name of the event to log.
propertiesAn 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 
Parameters
productIdentifierA String indicating the product that was purchased. Usually the product identifier in the iTunes store.
currencyCodeCurrencies 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.
pricePrices 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.
quantityAn unsigned number to indicate the purchase quantity. This number must be greater than 0 but no larger than 100.
propertiesAn 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
Parameters
pushAuthGrantedThe 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 
Parameters
applicationThe app's UIApplication object
notificationAn 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 
Parameters
applicationThe app's UIApplication object
notificationAn NSDictionary passed in from the didReceiveRemoteNotification:fetchCompletionHandler: call
completionHandlerA 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
Parameters
deviceTokenThe 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
Parameters
signatureThe 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 
Parameters
apiKeyThe app's API key
applicationthe current app
launchOptionsThe 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 
Parameters
apiKeyThe app's API key
applicationThe current app
launchOptionsThe options NSDictionary that you get from application:didFinishLaunchingWithOptions
appboyOptionsAn 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 
Parameters
centerThe app's current UNUserNotificationCenter object
responseThe UNNotificationResponse object passed in from the didReceiveNotificationResponse:withCompletionHandler: call
completionHandlerA 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:.

Property Documentation

- (id<ABKURLDelegate>) appboyUrlDelegate
readwritenonatomicweak

A class conforming to the ABKURLDelegate protocol can be set to handle URLs in a custom way.

- (id<ABKIDFADelegate>) idfaDelegate
readwritenonatomicstrong

A class extending ABKIDFADelegate can be set to provide the IDFA to Braze.

- (id<ABKImageDelegate>) imageDelegate
readwritenonatomicstrong

A class conforming to ABKImageDelegate can be set to use a custom image library.

- (ABKInAppMessageController*) inAppMessageController
readatomicassign

The current in-app message manager. See ABKInAppMessageController.h.

- (ABKLocationManager*) locationManager
readnonatomicassign

The Braze location manager provides access to location related functionality in the Braze SDK. See ABKLocationManager.h.

- (ABKRequestProcessingPolicy) requestProcessingPolicy
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]

.

- (id<ABKSdkAuthenticationDelegate>) sdkAuthenticationDelegate
readwritenonatomicstrong

A class conforming to ABKSdkAuthenticationDelegate can be set to handle SDK Authentication errors.

- (ABKSDKFlavor) sdkFlavor
readwritenonatomicassign

Property for internal reporting of SDK flavor.

- (NSURLSessionConfiguration*) urlSessionConfiguration
readnonatomicassign

A custom NSURLSessionConfiguration for configuring network session parameters.

- (ABKUser*) user
readatomicassign

The current app user. See ABKUser.h and changeUser:userId below.