“BrazeiOSSDK
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) - flushDataAndProcessRequestQueue
 
(void) - shutdownServerCommunication
 
(void) - changeUser:
 
(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< ABKAppboyEndpointDelegateappboyEndpointDelegate
 
id< ABKIDFADelegateidfaDelegate
 
ABKInAppMessageControllerinAppMessageController
 
ABKLocationManagerlocationManager
 
id< ABKURLDelegateappboyUrlDelegate
 
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:
 
(BOOL) - submitFeedback:message:isReportingABug:
 
(void) - submitFeedback:withCompletionHandler:
 
(void) - logFeedDisplayed
 
("The feedback feature is
disabled for new accounts, and
will be removed in a future
SDK release.") 
- __deprecated_msg
 
(void) - logContentCardsDisplayed
 
(void) - requestFeedRefresh
 
(void) - requestContentCardsRefresh
 
(NSString *) - getDeviceId
 
(BOOL) - userNotificationWasSentFromAppboy:
 
(BOOL) - pushNotificationWasSentFromAppboy:
 
(void) - registerPushToken:
 
(void) - registerApplication:didReceiveRemoteNotification:
 
(void) - registerApplication:didReceiveRemoteNotification:fetchCompletionHandler:
 
(void) - getActionWithIdentifier:forRemoteNotification:completionHandler:
 
(void) - userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler:
 
(void) - pushAuthorizationFromUserNotificationCenter:
 

Method Documentation

- ("The feedback feature is disabled for new accounts, and will be removed in a future SDK release.") __deprecated_msg

If you're displaying feedback page on your own instead of using ABKFeedbackViewController, you should still report impressions of the feedback page back to Braze with this method so that your campaign reporting features still work in the dashboard.

- (void) changeUser: (NSString *)  userId
Parameters
userIdThe new user's ID (from the host application).

This method changes the user's ID.

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) 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 requestEnableSDKOnNextAppRun: and a subsequent call to startWithApiKey:. All references to the previous singleton should be released.

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) flushDataAndProcessRequestQueue

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 need to call this after each network related activity in your app. This includes:

  • Retrieving an updated feed and in-app message after a new session is opened or the user is changed. Braze will automatically add the request for new data to the network queue, you just need to give it permission to execute that request.
  • Flushing updated user data (custom events, custom attributes, as well as automatically collected data).
  • Flushing automatic analytics events such as starting and ending sessions.

If you're using ABKAutomaticRequestProcessingExceptForDataFlush, you only need to call this when you want to force an immediate flush of updated user data.

- (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 or NSString objects with <= 255 characters.

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.

- (BOOL) pushNotificationWasSentFromAppboy: ("Use instead.")  __deprecated_msg[ABKPushUtils isAppboyRemoteNotification:]
Parameters
optionsThe NSDictionary you get from application:didFinishLaunchingWithOptions or application:didReceiveRemoteNotification in your App Delegate.

Test a push notification to see if it came Braze.

- (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) registerPushToken: (NSString *)  token
Parameters
tokenThe 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.

+ (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. This currently supports ABKRequestProcessingPolicyOptionKey, ABKSocialAccountAcquisitionPolicyOptionKey and ABKFlushIntervalOptionKey. 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.

- (BOOL) submitFeedback: (NSString *)  replyToEmail
message: (NSString *)  message
isReportingABug: ("The feedback feature is disabled for new)  accounts
(and will be removed in a future SDK release.")  __deprecated_msg 
Parameters
replyToEmailThe email address to send feedback replies to.
messageThe message input by the user. Must be non-null and non-empty.
isReportingABugFlag indicating whether or not the feedback describes a bug, or is merely a suggestion/question.
Returns
a boolean indicating whether or not the feedback item was successfully queued for delivery.

Submits a piece of feedback to the Braze feedback center so that it can be handled in the Braze dashboard. The request to submit feedback is made immediately, however, this method does not block and will return as soon as the feedback request is placed on the network queue.

- (void) submitFeedback: (ABKFeedback *)  feedback
withCompletionHandler: ("The feedback feature is disabled for new)  accounts
(and will be removed in a future SDK release.")  __deprecated_msg 
Parameters
feedbackThe feedback object with feedback message, email, and is-bug flag.
completionHandlerThe block to execute when the feedback sending process is complete. An ABKFeedbackSentResult enum will be passed to the block indicating if the feedback was sent successfully.

Submits a piece of feedback to the Braze feedback center so that it can be handled in the Braze dashboard. The request to submit feedback is made immediately. However, this method does not block and will return as soon as the feedback request is placed on the network queue.

+ (nonnull Appboy *) unsafeInstance

Get the Appboy singleton. Throws an exception if accessed before startWithApiKey: is called.

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

- (BOOL) userNotificationWasSentFromAppboy: (10.0)  NS_AVAILABLE_IOS
Parameters
responseThe response passed in from userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler:.

This method returns whether or not a UNNotification was sent from Braze servers.

+ (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:. All references to the previous singleton should be released.

The SDK will automatically re-enable itself when startWithApiKey: is next 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<ABKAppboyEndpointDelegate>) appboyEndpointDelegate
readwritenonatomicweak

A class conforming to the ABKAppboyEndpointDelegate protocol can be set to route Braze API and Resource traffic in a custom way. For example, one might proxy Braze image downloads by having the getResourceEndpoint method return a proxy URI.

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

- (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] flushDataAndProcessRequestQueue]

.

- (ABKSDKFlavor) sdkFlavor
readwritenonatomicassign

Property for internal reporting of SDK flavor.

- (ABKUser*) user
readatomicassign

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