Search specific term/phrase surrounded by double quotes. e.g. “deep linking”
Exclude records that contain a specific term prefixed with a minus. e.g. Android -Firebase

iOS Full Reference

Public methods made available by Branch for your iOS app.

getInstance

MethodDescription
(Branch *)getInstance;Get the live, global Branch instance.

Example Usage

let branch: Branch = Branch.getInstance()
Branch *branch = [Branch getInstance];

initSessionWithLaunchOptions

MethodDescription
(void)initSessionWithLaunchOptions:(nullable NSDictionary *)options andRegisterDeepLinkHandler:(nullable callbackWithParams)callback;Initialize a Branch session with your app's specific launch options, and handle the completion with a callbackWithParams object.
(void)initSessionWithLaunchOptions:(nullable NSDictionary *)options andRegisterDeepLinkHandlerUsingBranchUniversalObject:(nullable callbackWithBranchUniversalObject)callback;Initialize a Branch session with your app's specific launch options, and handle the completion with a callbackWithBranchUniversalObject object.
ArgumentTypeDescription
optionsNSDictionaryThe launch options provided by your AppDelegate file's didFinishLaunchingWithOptions: method.
callbackcallbackWithParams or callbackWithBranchUniversalObjectA callback that is called when the session is opened. This will be called multiple times during the app's life, including any time the app goes through a background/foreground cycle.

Example Usage

// Within the AppDelegate
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
  let branch: Branch = Branch.getInstance()
  branch?.initSession(launchOptions: launchOptions, deepLinkHandler: { params, error in
    if error == nil {
        // Params are the deep linked params associated with the link that the user clicked
        print("params: %@", params.description)
    }
   })
  return true
}

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    // Pass URL to the "handle deep link" call
    let branchHandled = Branch.getInstance().application(
        application,
        open: url,
        options: options
    )
    if (!branchHandled) {
        // If not handled by Branch, do other deep link routing for the Facebook SDK, Pinterest SDK, etc
    }

    return true
}

func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    let handledByBranch = Branch.getInstance().continue(userActivity)

    return handledByBranch
}
// Within the AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    Branch *branch = [Branch getInstance];
    [branch initSessionWithLaunchOptions:launchOptions andRegisterDeepLinkHandler:^(NSDictionary *params, NSError *error) {
    	// Route user based on params
    }];
    return YES;
}

- (BOOL)application:(UIApplication *)application
            openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
    BOOL branchHandled =
        [[Branch getInstance]
            application:application
                openURL:url
                options:options];
    if (!branchHandled) {
        // Do other deep link routing for the Facebook SDK, Pinterest SDK, etc.
    }
    return YES;
}

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> *restorableObjects))restorationHandler {
    BOOL handledByBranch = [[Branch getInstance] continueUserActivity:userActivity];

    return handledByBranch;
}

Parameters Returned:

Note: The ~ symbol denotes analytics and + denotes information added by Branch.

ParameterDescription
~channelThe channel on which the link was shared, specified at Branch Link creation time.
~featureThe feature, such as invite or share, specified at Branch Link creation time.
~tagsAny tags, specified at Branch Link creation time.
~campaignThe campaign the link is associated with, specified at Branch Link creation time.
~stageThe stage, specified at Branch Link creation time.
~creation_sourceWhere the Branch Link was created ('API', 'Dashboard', 'SDK', 'iOS SDK', 'Android SDK', or 'Web SDK').
+match_guaranteedTrue or false as to whether the match was made with 100% accuracy.
+referrerThe referrer for the Branch Link click, if a Branch Link was clicked.
+phone_numberThe phone number of the user, if the user texted themself the app.
+is_first_sessionDenotes whether this is the first session (install) or any other session (open).
+clicked_branch_linkDenotes whether or not the user clicked a Branch Link that triggered this session.
+click_timestampEpoch timestamp of when the click occurred.

handleDeepLink

Warning: Handling a new Branch Deep Link in your app will clear the current session data and a new referred "open" will be attributed.

MethodDescription
(BOOL)handleDeepLink:(nullable NSURL *)url;Allow Branch to handle a link that opens the app, and to parse the parameters from it.

Returns true if Branch handled the link.
ArgumentTypeDescription
urlNSURLThe URL that caused the app to be opened.

Example Usage

// The following call would return `false`
Branch.getInstance().handleDeepLink("myapp://")

// The following call would return `true`
Branch.getInstance().handleDeepLink("myapp://open?link_click_id=12345")
// The following call would return `YES`
NSURL *URL = [NSURL URLWithString:@"myapp://open?link_click_id=12345"];
[[Branch getInstance] handleDeepLink:URL];

continueUserActivity

MethodDescription
(BOOL)continueUserActivity:(nullable NSUserActivity *)userActivity;Allow Branch to handle restoration from an NSUserActivity.

Returns true if Branch handled the link.
ArgumentTypeDescription
userActivityNSUserActivityThe NSUserActivity that caused the app to be opened.

Example Usage

func application(application: UIApplication, continueUserActivity userActivity: NSUserActivity, restorationHandler: ([AnyObject]?) -> Void) -> Bool {
  Branch.getInstance().continueUserActivity(userActivity);
  return true
}
- (BOOL)application:(UIApplication *)application
continueUserActivity:(NSUserActivity *)userActivity
  restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> *))restorationHandler {
    [[Branch getInstance] continueUserActivity:userActivity];
    return YES;
}

application

MethodDescription
(BOOL)application:(nullable UIApplication *)application openURL:(nullable NSURL *)url options:(nullable NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options;Allow Branch to open the URL that gets passed to it.

This is the preferred Branch method to call inside your application:openURL:options: method.
ArgumentTypeDescription
applicationUIApplicationThe application that was passed to your app delegate.
urlNSURLThe URL that was passed to your app delegate.
optionsNSDictionaryThe launch options dictionary that was passed to your app delegate.

Example Usage

func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
    Branch.getInstance().application(app, open: url, options:options)
    return true
}
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
    return [[Branch getInstance] application:app openURL:url options:options];
}

handlePushNotification

MethodDescription
(void)handlePushNotification:(nullable NSDictionary *)userInfo;Allow Branch to handle a push notification with a Branch Link.

When creating a push notification, specify the Branch Link as an NSString for the @"branch" key.
ArgumentTypeDescription
userInfoNSDictionaryThe application that was passed to your app delegate.

Example Usage

// NSDictionary userInfo = @{@"branch": @"https://bnc.lt/...", ... };
// NSDictionary userInfo = @{@"branch": @"https://app.link/...", ... };

Branch.getInstance().handlePushNotification(response.notification.request.content.userInfo)
// NSDictionary userInfo = @{@"branch": @"https://bnc.lt/...", ... };
// NSDictionary userInfo = @{@"branch": @"https://app.link/...", ... };

[[Branch getInstance] handlePushNotification:userInfo];

enableLogging

MethodDescription
(void)enableLogging;Enable sending debug messages to NSLog (the Apple System Log facility).

Important: Branch recommends that you use this method with your Branch test key and that you remove the method call before releasing to production.
ArgumentTypeDescription
userInfoNSDictionaryThe application that was passed to your app delegate.

Example Usage

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
  // Add `enableLogging` before `initSesssion` in AppDelegate
  Branch.enableLogging()
  
	// Listener for Branch Deep Link data
	Branch.getInstance().initSession(launchOptions: launchOptions) { (params, error) in
		// Do stuff here with Deep Link data (nav to page, display content, etc)
		print(params as? [String: AnyObject] ?? {})
	}
	return true
}
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
	// Add `enableLogging` before `initSesssion` in AppDelegate
	[Branch enableLogging];

	// Listener for Branch Deep Link data
	[[Branch getInstance] initSessionWithLaunchOptions:launchOptions andRegisterDeepLinkHandler:^(NSDictionary * _Nonnull params, NSError * _Nullable error) {
		// Do stuff here with Deep Link data (nav to page, display content, etc)
		NSLog(@"%@", params);
	}];
	return YES;
}

setAPIURL

MethodDescription
(void)setAPIUrl:(NSString *)urlSet the Branch API URL globally for all Branch operations.
ArgumentTypeDescription
urlNSStringThe new API URL to be used by Branch.

Example Usage

Branch.setAPIURL("https://api3.branch.io")
[Branch setAPIURL:@"https://api3.branch.io"];

validateSDKIntegration

MethodDescription
(void)validateSDKIntegration;Check that you've added the Branch iOS SDK successfully to your app and are able to handle Branch Deep Links. After you run your app, check the project's Xcode logs to make sure all the SDK Integration tests pass.

See SDK Integration Validator for more information.

Warning: this method should not be used in production - it is for debugging purposes only.

Example Usage

// Check your Xcode logs to make sure all the SDK Integration tests pass
// Make sure to comment out or remove validateSDKIntegration in your production build
Branch.getInstance().validateSDKIntegration()
// Check your Xcode logs to make sure all the SDK Integration tests pass
// Make sure to comment out or remove validateSDKIntegration in your production build
[[Branch getInstance] validateSDKIntegration];

addAllowedScheme

MethodDescription
(void)addAllowedScheme:(nullable NSString *)scheme;Allow a URI scheme to be tracked by Branch.

Defaults to all schemes.
ArgumentTypeDescription
schemeNSStringURI scheme allowed to be tracked, for example@"http", @"https", or @"myapp".

Example Usage

Branch.getInstance().addAllowedScheme("https")
[[Branch getInstance] addAllowedScheme:@"https"];

setAllowedSchemes

MethodDescription
(void)setAllowedSchemes:(nullable NSArray *)schemes;Allow an array of URI schemes to be tracked by Branch.

Defaults to all schemes.
ArgumentTypeDescription
schemesNSArrayAn array of URI schemes allowed to be tracked.

Example Usage

var allowedSchemes = ["http", "https", "myapp"]
Branch.getInstance().setAllowedSchemes(allowedSchemes)
[[Branch getInstance] addAllowedScheme:@[@"http", @"https", @"myapp"]];

checkPasteboardOnInstall

MethodDescription
(void)checkPasteboardOnInstall;Implement deferred deep linking via Branch NativeLink™.

This method checks the device's pasteboard (clipboard) for a Branch link on app installation. If found, the Branch Link is used to provide deferred deep link data.

Notes:

- To use this feature, you must enable NativeLink™ either in the Branch Dashboard or by manually configuring the Branch link to use $ios_nativelink.
- Using this feature may result in the end user seeing a toast message (you can check this with the willShowPasteboardToast method).
- The required minimum Branch iOS SDK version for this feature is v1.39.4.

Example Usage

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
	// The `checkPasteboardOnInstall` call must be made before `initSesssion`
	Branch.getInstance().checkPasteboardOnInstall()

	// Listener for Branch Deep Link data
	Branch.getInstance().initSession(launchOptions: launchOptions) { (params, error) in
		// Do stuff here with Deep Link data (nav to page, display content, etc)
		print(params as? [String: AnyObject] ?? {})
	}
  
	return true
}
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
	// The `checkPasteboardOnInstall` call must be made before `initSesssion`
	[[Branch getInstance] checkPasteboardOnInstall];

	// Listener for Branch Deep Link data
	[[Branch getInstance] initSessionWithLaunchOptions:launchOptions andRegisterDeepLinkHandler:^(NSDictionary * _Nonnull params, NSError * _Nullable error) {
		// Do stuff here with Deep Link data (nav to page, display content, etc)
		NSLog(@"%@", params);
	}];
  
	return YES;
}

Visit the iOS Advanced Features page for more examples using the checkPasteboardOnInstall() method.


willShowPasteboardToast

MethodDescription
(BOOL)willShowPasteboardToast;Check whether the Branch iOS SDK will trigger a pasteboard toast message for the end user.

Returns true if the end user will see a pasteboard toast message.

Example Usage

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
	// The `checkPasteboardOnInstall` call must be made before `initSesssion`
	Branch.getInstance().checkPasteboardOnInstall()
  
	// Check if pasteboard toast will show for end user
	if Branch.getInstance().willShowPasteboardToast(){
		// You can give the user information about what just occurred here
	}
  
	// Listener for Branch Deep Link data
	Branch.getInstance().initSession(launchOptions: launchOptions) { (params, error) in
		// Do stuff here with Deep Link data (nav to page, display content, etc)
		print(params as? [String: AnyObject] ?? {})
	}
	return true
}
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
	// The `checkPasteboardOnInstall` call must be made before `initSessionWithLaunchOptions`
	Branch.getInstance().checkPasteboardOnInstall()
  
	// Check if pasteboard toast will show for end user
	if ([[Branch getInstance] willShowPasteboardToast]) {
		// You can give the user information about what just occurred here    
	}

	// Listener for Branch Deep Link data
	[[Branch getInstance] initSessionWithLaunchOptions:launchOptions andRegisterDeepLinkHandler:^(NSDictionary * _Nonnull params, NSError * _Nullable error) {
		// Do stuff here with Deep Link data (nav to page, display content, etc)
		NSLog(@"%@", params);
	}];
	return YES;
}

setAppClipAppGroup

MethodDescription
(void)setAppClipAppGroup:(NSString *)appGroup;Set the AppGroup used to share data between the App Clip and your full app.
ArgumentTypeDescription
appGroupNSStringThe AppGroup to use.

Example Usage

// Within the AppDelegate
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    
    // The `setAppClipAppGroup()` call must be made before `initSession()`
    Branch.getInstance().setAppClipAppGroup("group.io.branch")
    BranchScene.shared().initSession(launchOptions: launchOptions) { (params, error, scene) in
        if let dict = params {
            
            if Monster.shared.waitingForData {
                let name = (dict["monster_name"] as? String) ?? "Branchster"
                Monster.shared.update(name: name)
            }
        }
    }
    
    return true
}
// Within the AppDelegate

- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    Branch *branch = [Branch getInstance];
    
    // The `setAppClipAppGroup()` call must be made before `initSessionWithLaunchOptions()`
    [branch setAppClipAppGroup:@"group.io.branch"];

    [branch initSessionWithLaunchOptions:launchOptions
        andRegisterDeepLinkHandlerUsingBranchUniversalObject:
            ^ (BranchUniversalObject *BUO, BranchLinkProperties *linkProperties, NSError *error) {

    }];

		return YES;
}

handleATTAuthorizationStatus

MethodDescription
(void)handleATTAuthorizationStatus:(NSUInteger)status;Pass the AppTrackingTransparency authorization status to Branch to measure ATT prompt performance.

Example Usage

if #available(iOS 14.0, *)  {
  // Check that `trackingAuthorizationStatus` is `notDetermined`, otherwise prompt will not display
	if ATTrackingManager.trackingAuthorizationStatus == .notDetermined {
		ATTrackingManager.requestTrackingAuthorization { (status) in
			// `handleATTAuthorizationStatus()` should be called from the callback of `requestTrackingAuthorization()`
			Branch.getInstance().handleATTAuthorizationStatus(status.rawValue)
		}
	}
}
if (@available(iOS 14.0, *)) {
  // Check that `trackingAuthorizationStatus` is `notDetermined`, otherwise prompt will not display
	if (ATTrackingManager.trackingAuthorizationStatus == ATTrackingManagerAuthorizationStatusNotDetermined) {
		[ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
      // `handleATTAuthorizationStatus()` should be called from the callback of `requestTrackingAuthorization()`
			[[Branch getInstance] handleATTAuthorizationStatus:status];
		}];
	}
}

addFacebookPartnerParameterWithName

MethodDescription
(void)addFacebookPartnerParameterWithName:(NSString *)name value:(NSString *)value;Add a Partner Parameter for Facebook. This allows you to pass additional hashed information to the SDK for Facebook Advanced Matching.

Once set, this parameter is attached to INSTALL, OPEN, and other events until they are cleared or the app restarts.
ArgumentTypeDescription
nameNSStringPartner Parameter name. See Facebook's documentation for details on valid parameters.
valueNSStringPartner Parameter value. See Facebook's documentation for details on valid parameters.

Example Usage

Branch.getInstance().addFacebookPartnerParameter(withName: "ph", value: "0000xxxx")

// Call `initSession()` after `addFacebookPartnerParameter()`
[[Branch getInstance] addFacebookPartnerParameterWithName:@"ph" value:@"0000xxxx"];

// Call `initSession()` after `addFacebookPartnerParameterWithName()`

addSnapPartnerParameterWithName

MethodDescription
(void)addSnapPartnerParameterWithName:(NSString *)name value:(NSString *)value;Add a Partner Parameter for Snap.

Once set, this parameter is attached to INSTALL, OPEN, and other events until they are cleared or the app restarts.
ArgumentTypeDescription
nameNSStringPartner Parameter name. See Snap's documentation for details on valid parameters.
valueNSStringPartner Parameter value. See Snap's documentation for details on valid parameters.

Example Usage

Branch.getInstance().addSnapPartnerParameter(withName: "ph", value: "0000xxxx")

// Call `initSession()` after `addSnapPartnerParameter()`
[[Branch getInstance] addSnapPartnerParameterWithName:@"ph" value:@"0000xxxx"];

// Call `initSession()` after `addSnapPartnerParameterWithName()`

clearPartnerParameters

MethodDescription
(void)clearPartnerParameters;Clears all Partner Parameters.

Example Usage

Branch.getInstance().clearPartnerParameters()
[[Branch getInstance] clearPartnerParameters];

setRetryInterval

MethodDescription
(void)setRetryInterval:(NSTimeInterval)retryInterval;Specify the time to wait in seconds between retries in the case of a Branch server error.
ArgumentTypeDescription
retryIntervalNSTimeIntervalNumber of seconds to wait between retries.

Example Usage

Branch.getInstance().setRetryInterval(10.0)
[[Branch getInstance] setRetryInterval:10.0];

setMaxRetries

MethodDescription
(void)setMaxRetries:(NSInteger)maxRetries;Specify the max number of times to retry in the case of a Branch server error.
ArgumentTypeDescription
maxRetriesNSIntegerNumber of retries to make.

Example Usage

Branch.getInstance().setMaxRetries(3)
[[Branch getInstance] setMaxRetries:3];

setNetworkTimeout

MethodDescription
(void)setNetworkTimeout:(NSTimeInterval)timeout;Specify the amount of time to wait before a request should be considered timed out.
ArgumentTypeDescription
timeoutNSTimeIntervalNumber of seconds to wait before a request is considered timed out.

Example Usage

Branch.getInstance().setNetworkTimeout(10.0)
[[Branch getInstance] setNetworkTimeout:10.0];

disableAdNetworkCallouts

MethodDescription
(void)disableAdNetworkCallouts:(BOOL)disableCallouts;Disable callouts to ad networks for all events (by default, Branch sends callouts to ad networks).

If callouts to ad networks are disabled, Branch will not send any events to the ad networks specified in your Branch account. If ad networks are not specified in your Branch account, this method will be ignored.
ArgumentTypeDescription
disableCalloutsBOOLWhen set to true, callouts to ad networks will be disabled.

Example Usage

Branch.getInstance().disableAdNetworkCallouts(true)
[[Branch getInstance] disableCallouts:YES];

isBranchLink

MethodDescription
(BOOL)isBranchLink:(NSString *)urlString;Check if a URL is likely a Branch link.

This check happens against Info.plist and the standard Branch list.
ArgumentTypeDescription
urlStringNSStringThe URL to check.

Example Usage

Branch.isBranchLink("https://example.app.link/fzmLEhobLD?$custom_data=123&hello=world")
[Branch isBranchLink:@"https://example.app.link/fzmLEhobLD?$custom_data=123&hello=world"];

setRequestMetadataKey

MethodDescription
(void)setRequestMetadataKey:(NSString *)key value:(nullable id)value;Add key-value pairs to the metadata of every request.

Some Data Integration Partners require specific identifiers to be set prior to Branch initialization. Use this function to set those identifiers.
ArgumentTypeDescription
keyNSStringString to be included in request metadata.
valueidObject to be included in request metadata.

Example Usage

General example:

// Inside the `didFinishLaunchingWithOptions` method
// Replace <analytics_id> with your Data Integration Partner's key
Branch.getInstance().setRequestMetadataKey("<analytics_id>", "<value>")
// Inside the `didFinishLaunchingWithOptions` method
// Replace <analytics_id> with your Data Integration Partner's key
[[Branch getInstance] setRequestMetadataKey:@"<analytics_id>" value: @"<value>"];

Example using Braze as the 3rd party Data Integration Partner:

// Inside the `didFinishLaunchingWithOptions` method
Branch.getInstance.setRequestMetadataKey("$braze_install_id", braze.deviceId)
// Inside the `didFinishLaunchingWithOptions` method
[[Branch getInstance] setRequestMetadataKey:@"$braze_install_id" value: braze.deviceId];

Visit the iOS Advanced Features page to learn more about the setRequestMetadataKey() method.


setTrackingDisabled

MethodDescription
(void) setTrackingDisabled:(BOOL)disabled;Disable the Branch SDK from tracking the user. This is useful for GDPR privacy compliance.

When tracking is disabled, the Branch SDK will clear the Branch defaults of user identifying information and prevent Branch from making any Branch network calls that will track the user.
ArgumentTypeDescription
disabledBOOLWhen set to true, tracking will be disabled.

Implications of Using setTrackingDisabled

ActionWill work?
Opening Branch Deep Links with an explicit URLY
Deferred deep linkingN
Generating short linksN (returns long links)
Sending user tracking events such as userCompletedAction, BranchCommerceEvents, and
BranchEvents
N
User rewards and creditsN
Setting a user identity and logging a user identity outN

Example Usage

// Call takes place at the SDK level
Branch.setTrackingDisabled(true)
// Call takes place at the SDK level
[Branch setTrackingDisabled:YES];

trackingDisabled

MethodDescription
(BOOL) trackingDisabled;Check whether user tracking is currently disabled.

Returns true if user tracking is disabled.

Example Usage

func trackingStatus() -> Bool {
  // Call takes place at the SDK level
  return Branch.trackingDisabled()
}
// Call takes place at the SDK level
[Branch trackingDisabled];

setReferrerGbraidValidityWindow

MethodDescription
(void) setReferrerGbraidValidityWindow:(NSTimeInterval) validityWindow;Sets the time window for which referrer_gbraid is valid, starting from now.

After the validity window is over, it gets cleared from settings and will not be sent with requests anymore.
ArgumentTypeDescription
validityWindowNSTimeIntervalThe number of seconds referrer_gbraid will be valid starting from now.

Default validityWindow is 30 days (2,592,000 seconds).

Example Usage

Branch.setReferrerGbraidValidityWindow(10.0)
[Branch setReferrerGbraidValidityWindow:10.0]

setDMAParamsForEEA

🚧

Warning: NULL by Default

Please note that the 3 parameters passed to setDMAParamsForEEA() are all NULL by default.

Failure to include user consent signals may result in attribution or campaign performance degradation. For additional information, please reach out to your Google AM.

MethodDescription
(void) setDMAParamsForEEA:(BOOL)eeaRegion AdPersonalizationConsent:(BOOL)adPersonalizationConsent AdUserDataUsageConsent:(BOOL)adUserDataUsageConsentSets the value of parameters required by Google Conversion APIs for DMA Compliance in the EEA region.
ArgumentTypeDescription
eeaRegionBooleanSet to true if user is included in European Union regulations. For example, if the user is located within the EEA, they are within the scope of DMA.

Set to false if user is considered excluded from European Union regulations.
adPersonalizationConsentBooleanSet to true if user has granted consent for ads personalization.

Set to false if user has denied consent for ads personalization.
adUserDataUsageConsentBooleanSet to true if user has granted consent for 3P transmission of user-level data for ads.

Set to false is user has denied consent for 3P transmission of user-level data for ads.

Example Usage

// Example for an EEA resident who has denied both ad personalization and data usage consent
Branch.getInstance().setDMAParamsForEEA(true,false,false)
// Example for an EEA resident who has denied both ad personalization and data usage consent
[[Branch getInstance]
	setDMAParamsForEEA:YES
	adPersonalizationConsent:NO
	adUserDataUsageConsent:NO];
// Example for an EEA resident who has consented to ad personalization but denied data usage consent
Branch.getInstance().setDMAParamsForEEA(true,true,false)
// Example for an EEA resident who has consented to ad personalization but denied data usage consent
[[Branch getInstance]
	setDMAParamsForEEA:YES
	adPersonalizationConsent:YES
	adUserDataUsageConsent:NO];
// Example for an EEA resident who has denied ad personalization but granted data usage consent
Branch.getInstance().setDMAParamsForEEA(true,false,true)
// Example for an EEA resident who has denied ad personalization but granted data usage consent
[[Branch getInstance]
	setDMAParamsForEEA:YES
	adPersonalizationConsent:NO
	adUserDataUsageConsent:YES];

Read more about the setDMAParamsForEEA() method and Google DMA compliance in iOS Advanced Features guide.


getFirstReferringBranchUniversalObject

MethodDescription
(nullable BranchLinkProperties *)getFirstReferringBranchLinkProperties;Get the BranchUniversalObject instance from the first time this user was referred (can be empty).

Example Usage

Branch.getInstance.getFirstReferringBranchUniversalObject()
const char *_getFirstReferringBranchUniversalObject() {
	BranchUniversalObject* universalObject = [[Branch getInstance] getFirstReferringBranchUniversalObject];
	return jsonCStringFromDictionary(dictFromBranchUniversalObject(universalObject));
}

getFirstReferringBranchLinkProperties

MethodDescription
(nullable BranchLinkProperties *)getFirstReferringBranchLinkProperties;Get the BranchLinkProperties instance from the first time this user was referred (can be empty).

Example Usage

Branch.getInstance.getFirstReferringBranchLinkProperties()
[[Branch getInstance] getFirstReferringBranchLinkProperties];

getFirstReferringParams

MethodDescription
(nullable NSDictionary *)getFirstReferringParams;Get the parameters used the first time this user was referred (can be empty).

Example Usage

// In AppDelegate file, inside `didFinishLaunchingWithOptions()` method

// Listener for Branch Deep Link data
Branch.getInstance().initSession(launchOptions: launchOptions) { params, error in
  print(params as? [String: AnyObject] ?? {})
}

// Get first referring params for Deep Link
let installParams = Branch.getInstance().getFirstReferringParams()
// In AppDelegate file, inside `didFinishLaunchingWithOptions()` method

// Listener for Branch Deep Link data
[[Branch getInstance] initSessionWithLaunchOptions:launchOptions
                        andRegisterDeepLinkHandler:^(NSDictionary * _Nullable params,
                                                     NSError * _Nullable error) {
    if (!error) {
        //Referring params
        NSLog(@"Referring link params %@",params);
    }
}];

// Get first referring params for Deep Link
NSDictionary *installParams =  [[Branch getInstance] getFirstReferringParams];

getLatestReferringBranchUniversalObject

MethodDescription
(nullable BranchUniversalObject *)getLatestReferringBranchUniversalObject;Get the BranchUniversalObject instance from the most recent time this user was referred (can be empty).

Example Usage

Branch.getInstance.getLatestReferringBranchUniversalObject()
[[Branch getInstance] getLatestReferringBranchUniversalObject];

getLatestReferringBranchLinkProperties

MethodDescription
(nullable BranchLinkProperties *)getLatestReferringBranchLinkProperties;Get the BranchLinkProperties instance from the most recent time this user was referred (can be empty).

Example Usage

Branch.getInstance.getLatestReferringBranchLinkProperties()
[[Branch getInstance] getLatestReferringBranchLinkProperties];

getLatestReferringParams

MethodDescription
(nullable NSDictionary *)getLatestReferringParams;Get the parameters used the most recent time this user was referred (can be empty).

This call does not block the calling thread, which means you may receive results from the previous time the user was referred.

If you need the most recent result, use getLatestReferringParamsSynchronous instead.

Example Usage

// In AppDelegate file, inside `didFinishLaunchingWithOptions()` method

// Listener for Branch Deep Link data
Branch.getInstance().initSession(launchOptions: launchOptions) { params, error in
  print(params as? [String: AnyObject] ?? {})
}

// Get latest referring params for Deep Link
// Warning: This method may return results from a previous referral
let sessionParams = Branch.getInstance().getLatestReferringParams()
// In AppDelegate file, inside `didFinishLaunchingWithOptions()` method

// Listener for Branch Deep Link data
[[Branch getInstance] initSessionWithLaunchOptions:launchOptions
                        andRegisterDeepLinkHandler:^(NSDictionary * _Nullable params,
                                                     NSError * _Nullable error) {
    if (!error) {
        //Referring params
        NSLog(@"Referring link params %@",params);
    }
}];

// Get latest referring params for Deep Link
// Warning: This method may return results from a previous referral
NSDictionary *sessionParams = [[Branch getInstance] getLatestReferringParams];

getLatestReferringParamsSynchronous

MethodDescription
(nullable NSDictionary *)getLatestReferringParamsSynchronous;Get the parameters used the most recent time this user was referred (can be empty).

This call blocks the calling thread until the latest results are available.

If you do not want to block the calling thread, use getLatestReferringParams() instead.

Example Usage

// Warning: This method blocks the calling thread until the latest results are available
Branch.getInstance.getLatestReferringParamsSynchronous()
// Warning: This method may block the current thread until the latest results are available
[[Branch getInstance] getLatestReferringParamsSynchronous];

resetUserSession

MethodDescription
(void)resetUserSession;Tells Branch to act as though initSession() had not been called.

Will require another open call (this is done automatically, internally).

Example Usage

Branch.getInstance.resetUserSession()
[[Branch getInstance] resetUserSession];

isUserIdentified

MethodDescription
(BOOL)isUserIdentified;Indicates whether or not this user has a custom identity specified for them. This is independent of installs.

If you call setIdentity(), this device will have that identity associated with this user until logout() is called. This includes persisting through uninstalls, as Branch tracks device ID.

Warning: This method should only be invoked after initSession completes, either within the callback or after a delay. If it is invoked before, then Branch will silently initialize the SDK before the callback has been set, in order to carry out this method's required task. As a result, you may experience issues where the initSession callback does not fire.

Example Usage

// Warning: only invoke `isUserIdentified()` after `initSession()` completes
Branch.getInstance.isUserIdentified()
// Warning: only invoke `isUserIdentified() after `initSession()` completes
[[Branch getInstance] isUserIdentified];

setIdentity

MethodDescription
(void)setIdentity:(nullable NSString *)userId;Set the user's identity to a unique ID used by your system, so that it is identifiable by you elsewhere.
(void)setIdentity:(nullable NSString *)userId withCallback:(nullable callbackWithParams)callback;Set the user's identity to a unique ID used by your system, so that it is identifiable by you elsewhere and receive a completion callback, notifying you whether it succeeded or failed.

WARNINGS:

  • If you use the same ID between users on different sessions/devices, their actions will be merged.
  • This request is not removed from the queue upon failure - it will be retried until it succeeds.
ArgumentTypeDescription
userIdNSStringThe ID that Branch should use to identify this user.
callbackcallbackWithParamsThe callback to be called once the request has completed (success or failure).

Example Usage Without Callback

// Login
Branch.getInstance().setIdentity("your_user_id")

// Logout
Branch.getInstance().logout()
//Login
Branch *branch = [Branch getInstance];
[branch setIdentity:@"test_user" withCallback:^(NSDictionary *params, NSError *error) {
	NSLog(@"callback in setIdentity %@", params);
}];

// Logout
[[Branch getInstance] logout]; // Or replace with .logoutWithCallback() to customize further

logout

MethodDescription
(void)logout;Clear all of the current user's session items.

Warning: If the request to logout fails, the items will not be cleared.

Example Usage

Branch.getInstance().logout()
[[Branch getInstance] logout];

logoutWithCallback

MethodDescription
(void)logoutWithCallback:(nullable callbackWithStatus)callback;Clear all of the current user's session items.

Warning: If the request to logout fails, the items will not be cleared.
ArgumentTypeDescription
logoutWithCallbackcallbackWithStatusThe callback to be called once the request has completed (success or failure).

Example Usage

let branch = Branch.getInstance()
branch.logoutWithCallback { (changed, error) in
	if (error != nil || !changed) {
		print(String(format: "Logout failed: %@", error!))
} else {
		print("Logout succeeded")
	}
}
Branch *branch = [Branch getInstance];
[branch logoutWithCallback:^(BOOL changed, NSError *error) {
	if (error || !changed) {
		NSLog(@"Logout failed: %@", error);
  } else {
    NSLog(@"Logout succeeded");
  }
}];

getShortURL (sync)

Warning: This method makes a synchronous URL request.

MethodDescription
(NSString *)getShortURL;Get a short URL without any items specified. The usage type will default to unlimited.

Example Usage

Branch.getInstance().getShortURL()
[[Branch getInstance] getShortURL];

getShortURLWithParams (sync, without tags)

Warning: The variations of getShortURLWithParams() in this table make a synchronous URL request.

ArgumentTypeDescription
paramsNSDictionaryDictionary of parameters to include in the short URL.
channelNSStringChannel for the short URL. Examples include Facebook, Twitter, and SMS (depending on where it will be shared).
featureNSStringFeature that the short URL is utilizing. Examples could be Sharing, Referring, Inviting, etc.
stageNSStringThe stage used for the short URL, indicating what part of a funnel the user is in.
aliasNSStringThe alias for a short URL. Warning: If you pass an alias that is already taken, the method call will fail.
typeBranchLinkTypeThe type of short URL this is, either single use or unlimited use. Single use means once per user.
durationNSUIntegerHow long to keep an unmatched link click in Branch's backend server queue before discarding.

Example Usage

// For all variations of `getShortURLWithParams()` the usage type will default to unlimited

let params: [String: Any] = [
    "key1": "value1",
    "key2": "value2"
]
let shortURL = Branch.getInstance().getShortURL(withParams: params)
// For all variations of `getShortURLWithParams()` the usage type will default to unlimited

NSDictionary *params = @{
    @"key1": @"value1",
    @"key2": @"value2"
};
NSString *shortURL = [[Branch getInstance] getShortURLWithParams:params];

getShortURLWithParams (sync, with tags)

Warning: The variations of getShortURLWithParams() in this table make a synchronous URL request.

MethodDescription
(NSString *)getShortURLWithParams:(nullable NSDictionary *)params andTags:(nullable NSArray *)tags andChannel:(nullable NSString *)channel andFeature:(nullable NSString *)feature andStage:(nullable NSString *)stage;Get a short URL with specified parameters, tags, channel, feature, and stage.
(NSString *)getShortURLWithParams:(nullable NSDictionary *)params andTags:(nullable NSArray *)tags andChannel:(nullable NSString *)channel andFeature:(nullable NSString *)feature andStage:(nullable NSString *)stage andAlias:(nullable NSString *)alias;Get a short URL with specified parameters, tags, channel, feature, stage, and alias.
(NSString *)getShortURLWithParams:(nullable NSDictionary *)params andTags:(nullable NSArray *)tags andChannel:(nullable NSString *)channel andFeature:(nullable NSString *)feature andStage:(nullable NSString *)stage andAlias:(nullable NSString *)alias ignoreUAString:(nullable NSString *)ignoreUAString;Get a short URL with specified parameters, tags, channel, feature, stage, and type.
(NSString *)getShortURLWithParams:(nullable NSDictionary *)params andTags:(nullable NSArray *)tags andChannel:(nullable NSString *)channel andFeature:(nullable NSString *)feature andStage:(nullable NSString *)stage andCampaign:(nullable NSString *)campaign andAlias:(nullable NSString *)alias ignoreUAString:(nullable NSString *)ignoreUAString forceLinkCreation:(BOOL)forceLinkCreation;Get a short URL with specified parameters, tags, channel, feature, stage, and match duration.
(NSString *)getShortURLWithParams:(nullable NSDictionary *)params andTags:(nullable NSArray *)tags andChannel:(nullable NSString *)channel andFeature:(nullable NSString *)feature andStage:(nullable NSString *)stage andType:(BranchLinkType)type;Get a short URL with specified parameters, tags, alias, channel, feature, stage, and match duration.
(NSString *)getShortURLWithParams:(nullable NSDictionary *)params andTags:(nullable NSArray *)tags andChannel:(nullable NSString *)channel andFeature:(nullable NSString *)feature andStage:(nullable NSString *)stage andMatchDuration:(NSUInteger)duration;Get a short URL with specified parameters, tags, alias, channel, feature, stage, campaign, and match duration.
(NSString *)getShortUrlWithParams:(nullable NSDictionary *)params andTags:(nullable NSArray *)tags andAlias:(nullable NSString *)alias andChannel:(nullable NSString *)channel andFeature:(nullable NSString *)feature andStage:(nullable NSString *)stage andMatchDuration:(NSUInteger)duration;Get a short URL with specified tags, params, channel, feature, stage, and match duration.
(NSString *)getShortUrlWithParams:(nullable NSDictionary *)params andTags:(nullable NSArray *)tags andAlias:(nullable NSString *)alias andChannel:(nullable NSString *)channel andFeature:(nullable NSString *)feature andStage:(nullable NSString *)stage andCampaign:campaign andMatchDuration:(NSUInteger)duration;Get a short URL with specified params, channel, feature, stage, campaign and match duration.
ArgumentTypeDescription
paramsNSDictionaryDictionary of parameters to include in the short URL.
tagsNSArrayAn array of tags to associate with this short URL. Useful for tracking.
channelNSStringChannel for the short URL. Examples include Facebook, Twitter, and SMS (depending on where it will be shared).
featureNSStringFeature that the short URL is utilizing. Examples could be Sharing, Referring, Inviting, etc.
stageNSStringThe stage used for the short URL, indicating what part of a funnel the user is in.
aliasNSStringThe alias for a short URL. Warning: If you pass an alias that is already taken, the method call will fail.
typeBranchLinkTypeThe type of short URL this is, either single use or unlimited use. Single use means once per user.
durationNSUIntegerHow long to keep an unmatched link click in Branch's backend server queue before discarding.
campaigncampaignUse this field to organize the links by actual marketing campaign.
ignoreUAStringNSStringThe User Agent string to tell the server to ignore the next request - prevents it from treating a preview scrape as a link click.
forceLinkCreationBOOLWhether we should create a link from the Branch key even if initSession failed. Defaults to NO.

Example Usage

// For all variations of `getShortURLWithParams()` the usage type will default to unlimited

let params: [String: Any] = [
    "key1": "value1",
    "key2": "value2"
]

let shortURL = Branch.getInstance().getShortURL(withParams:params andTags:["one", "two", "three"])
// For all variations of `getShortURLWithParams()` the usage type will default to unlimited

NSDictionary *params = @{
    @"key1": @"value1",
    @"key2": @"value2"
};

NSString *shortURL = [[Branch getInstance] getShortURLWithParams:params andTags:@["one", "two", "three"]];

getLongURLWithParams

ArgumentTypeDescription
paramsNSDictionaryDictionary of parameters to include in the long URL.
tagsNSArrayAn array of tags to associate with this long URL. Useful for tracking.
channelNSStringChannel for the long URL. Examples include Facebook, Twitter, and SMS (depending on where it will be shared).
featureNSStringFeature that the long URL is utilizing. Examples could be Sharing, Referring, Inviting, etc.
stageNSStringThe stage used for the long URL, indicating what part of a funnel the user is in.
aliasNSStringThe alias for a long URL. Warning: If you pass an alias that is already taken, the method call will fail.
campaigncampaignUse this field to organize the links by actual marketing campaign.

Example Usage

// For all variations of `getLongURLWithParams()` the usage type will default to unlimited

let params: [String: Any] = [
    "key1": "value1",
    "key2": "value2"
]
let longUrl = Branch.getInstance().getLongURL(withParams: params, andChannel: "channel", andTags: ["tag1"], andFeature: "feature", andStage: "stage", andAlias: "testingLinkAlias123")
// For all variations of `getLongURLWithParams()` the usage type will default to unlimited

NSDictionary *params = @{
    @"key1": @"value1",
    @"key2": @"value2"
};
NSString *longUrl = [[Branch getInstance] getLongURLWithParams:params andChannel:@"channel" andTags:@[@"tag1"] andFeature:@"feature" andStage:@"stage" andAlias:@"testingLinkAlias123"];

getLongAppLinkURLWithParams

MethodDescription
(NSString *)getLongAppLinkURLWithParams:(NSDictionary *)params andChannel:(nullable NSString *)channel andTags:(NSArray *)tags andFeature:(NSString *)feature andStage:(NSString *)stage andAlias:(NSString *)alias;Get a long app.link URL with specified parameters, channel, tags, feature, stage, and alias. Warning: If you pass an alias that is already taken, the method call will fail.
ArgumentTypeDescription
paramsNSDictionaryDictionary of parameters to include in the long app.link URL.
channelNSStringChannel for the long app.link URL. Examples include Facebook, Twitter, and SMS (depending on where it will be shared).
tagsNSArrayAn array of tags to associate with this long app.link URL. Useful for tracking.
featureNSStringFeature that the long app.link URL is utilizing. Examples could be Sharing, Referring, Inviting, etc.
stageNSStringThe stage used for the long app.link URL, indicating what part of a funnel the user is in.
aliasNSStringThe alias for the long app.link URL. Warning: If you pass an alias that is already taken, the method call will fail.

Example Usage

// The usage type of `getLongAppLinkURLWithParams()` will default to unlimited

let params: [String: Any] = [
    "key1": "value1",
    "key2": "value2"
]

let longAppUrl = Branch.getInstance().getLongAppLinkURL(withParams: params, andChannel: "channel", andTags: ["tag1"], andFeature: "feature", andStage: "stage", andAlias: "testingLinkAlias123")
// The usage type of `getLongAppLinkURLWithParams()` will default to unlimited

NSDictionary *params = @{
    @"key1": @"value1",
    @"key2": @"value2"
};

NSString *longAppUrl = [[Branch getInstance] getLongAppLinkURLWithParams:params andChannel:@"channel" andTags:@[@"tag1"] andFeature:@"feature" andStage:@"stage" andAlias:@"testingLinkAlias123"];

getShortURLWithCallback (async)

Warning: This method should only be invoked after initSession() completes, either within the callback or after a delay. If it is invoked before, Branch will silently initialize the SDK before the callback has been set, in order to carry out this method's required task. As a result, you may experience issues where the initSession() callback does not fire.

MethodDescription
(void)getShortURLWithCallback:(nullable callbackWithUrl)callback;Get a short URL without any items specified.
ArgumentTypeDescription
callbackcallbackWithUrlCallback called with the short URL.

Example Usage

// The usage type of `getShortURLWithCallback()` will default to unlimited

Branch.getInstance().getShortURLWithCallback { (url, error) in
	print("Generated short URL: \(url)")
}
// The usage type of `getShortURLWithCallback()` will default to unlimited

NSDictionary *params = @{
	@"key1": @"value1",
	@"key2": @"value2"
};
  
[[Branch getInstance] getShortURLWithCallback:^(NSString * _Nullable url, NSError * _Nullable error) {
    NSLog(@"Generated short URL: %@", url);
}];

getShortURLWithParams (async, without tags)

Warning: The variations of getShortURLWithParams() in this table should only be invoked after initSession() completes, either within the callback or after a delay. If it is invoked before, Branch will silently initialize the SDK before the callback has been set, in order to carry out this method's required task. As a result, you may experience issues where the initSession() callback does not fire.

MethodDescription
(void)getShortURLWithParams:(nullable NSDictionary *)params andCallback:(nullable callbackWithUrl)callback;Get a short URL without any items specified.
(void)getShortURLWithParams:(nullable NSDictionary *)params andChannel:(nullable NSString *)channel andFeature:(nullable NSString *)feature andCallback:(nullable callbackWithUrl)callback;Get a short URL with the specified parameters, channel, and feature.
(void)getShortURLWithParams:(nullable NSDictionary *)params andChannel:(nullable NSString *)channel andFeature:(nullable NSString *)feature andStage:(nullable NSString *)stage andCallback:(nullable callbackWithUrl)callback;Get a short URL with the specified parameters, channel, feature, and stage.
(void)getShortURLWithParams:(nullable NSDictionary *)params andChannel:(nullable NSString *)channel andFeature:(nullable NSString *)feature andStage:(nullable NSString *)stage andAlias:(nullable NSString *)alias andCallback:(nullable callbackWithUrl)callback;Get a short URL with the specified parameters, channel, feature, stage, and alias. Warning: If you pass an alias that is already taken, the method call will fail.
(void)getShortURLWithParams:(nullable NSDictionary *)params andChannel:(nullable NSString *)channel andFeature:(nullable NSString *)feature andStage:(nullable NSString *)stage andType:(BranchLinkType)type andCallback:(nullable callbackWithUrl)callback;Get a short URL with the specified parameters, channel, feature, stage, and link type.
(void)getShortURLWithParams:(nullable NSDictionary *)params andChannel:(nullable NSString *)channel andFeature:(nullable NSString *)feature andStage:(nullable NSString *)stage andMatchDuration:(NSUInteger)duration andCallback:(nullable callbackWithUrl)callback;Get a short URL with the specified parameters, channel, feature, stage, and match duration.
ArgumentTypeDescription
paramsNSDictionaryDictionary of parameters to include in the short URL.
callbackcallbackWithUrlCallback called with the short URL.
channelNSStringThe channel for the short URL. Examples include Facebook, Twitter, and SMS, depending on where it will be shared.
featureNSStringThe feature the short URL is utilizing. Examples include Sharing, Referring, Inviting, etc.
stageNSStringThe stage used for the generated short URL, indicating what part of a funnel the user is in.
aliasNSStringThe alias for the short URL. Warning: If you pass an alias that is already taken, the method call will fail.
typeBranchLinkTypeThe type of short URL this is, either single use or unlimited use. Single use means once per user.
durationNSUIntegerHow long to keep an unmatched link click in Branch's backend server queue before discarding.

Example Usage

// Warning: This method should only be invoked after `initSession()` completes, either within the callback or after a delay
// The usage type of `getShortURLWithParams()` will default to unlimited

let linkProperties: BranchLinkProperties = BranchLinkProperties()
linkProperties.channel = "facebook"
linkProperties.feature = "sharing"
linkProperties.campaign = "content 123 launch"
linkProperties.stage = "new user"
linkProperties.alias = "myapp.com/customalias"
linkProperties.matchDuration = 0

func generateShortUrl(params: [AnyHashable : Any], linkProperties: BranchLinkProperties, completion: @escaping (String?, Error?)->(Void)) -> Void {
	Branch.getInstance().getShortUrl(withParams: params, andChannel: linkProperties.channel, andFeature: linkProperties.feature, andStage: linkProperties.stage, andAlias: linkProperties.alias) { (url, error) in
		if (error == nil) {
			completion(url, nil)
		} else {
			completion(nil, error)
		}
	}
}
// Warning: This method should only be invoked after `initSession()` completes, either within the callback or after a delay
// The usage type of `getShortURLWithParams()` will default to unlimited

Branch *branch = [Branch getInstance];
[branch getShortURLWithParams:nil andChannel:@"facebook" andFeature:nil andCallback:^(NSString *url, NSError *error) {
	// Do stuff with URL here
}];

getShortURLWithParams (async, with tags)

Warning: The variations of getShortURLWithParams() in this table should only be invoked after initSession() completes, either within the callback or after a delay. If it is invoked before, Branch will silently initialize the SDK before the callback has been set, in order to carry out this method's required task. As a result, you may experience issues where the initSession() callback does not fire.

MethodDescription
(void)getShortURLWithParams:(nullable NSDictionary *)params andTags:(nullable NSArray *)tags andChannel:(nullable NSString *)channel andFeature:(nullable NSString *)feature andStage:(nullable NSString *)stage andCallback:(nullable callbackWithUrl)callback;Get a short URL with the specified parameters, tags, channel, feature, and stage.
(void)getShortURLWithParams:(nullable NSDictionary *)params andTags:(nullable NSArray *)tags andChannel:(nullable NSString *)channel andFeature:(nullable NSString *)feature andStage:(nullable NSString *)stage andAlias:(nullable NSString *)alias andCallback:(nullable callbackWithUrl)callback;Get a short URL with the specified parameters, tags, channel, feature, stage, and alias. Warning: If you pass an alias that is already taken, the method call will fail.
(void)getShortURLWithParams:(nullable NSDictionary *)params andTags:(nullable NSArray *)tags andChannel:(nullable NSString *)channel andFeature:(nullable NSString *)feature andStage:(nullable NSString *)stage andType:(BranchLinkType)type andCallback:(nullable callbackWithUrl)callback;Get a short URL with the specified parameters, tags, channel, feature, stage, and link type.
(void)getShortURLWithParams:(nullable NSDictionary *)params andTags:(nullable NSArray *)tags andChannel:(nullable NSString *)channel andFeature:(nullable NSString *)feature andStage:(nullable NSString *)stage andMatchDuration:(NSUInteger)duration andCallback:(nullable callbackWithUrl)callback;Get a short URL with the specified parameters, tags, channel, feature, stage, and match duration.
(void)getShortUrlWithParams:(nullable NSDictionary *)params andTags:(nullable NSArray *)tags andAlias:(nullable NSString *)alias andMatchDuration:(NSUInteger)duration andChannel:(nullable NSString *)channel andFeature:(nullable NSString *)feature andStage:(nullable NSString *)stage andCallback:(nullable callbackWithUrl)callback;Get a short URL with the specified parameters, tags, alias, match duration, channel, feature, and stage. Warning: If you pass an alias that is already taken, the method call will fail.
void)getShortUrlWithParams:(nullable NSDictionary *)params andTags:(nullable NSArray *)tags andAlias:(nullable NSString *)alias andMatchDuration:(NSUInteger)duration andChannel:(nullable NSString *)channel andFeature:(nullable NSString *)feature andStage:(nullable NSString *)stage andCampaign:(nullable NSString *)campaign andCallback:(nullable callbackWithUrl)callback;Get a short URL with the specified parameters, tags, alias, match duration, channel, feature, stage, and campaign. Warning: If you pass an alias that is already taken, the method call will fail.
ArgumentTypeDescription
paramsNSDictionaryDictionary of parameters to include in the short URL.
tagsNSArrayAn array of tags to associate with the short URL. Useful for tracking.
callbackcallbackWithUrlCallback called with the short URL.
channelNSStringThe channel for the short URL. Examples include Facebook, Twitter, and SMS, depending on where it will be shared.
featureNSStringThe feature the short URL is utilizing. Examples include Sharing, Referring, Inviting, etc.
stageNSStringThe stage used for the generated short URL, indicating what part of a funnel the user is in.
aliasNSStringThe alias for the short URL. Warning: If you pass an alias that is already taken, the method call will fail.
typeBranchLinkTypeThe type of short URL this is, either single use or unlimited use. Single use means once per user.
durationNSUIntegerHow long to keep an unmatched link click in Branch's backend server queue before discarding.

Example Usage

// Warning: This method should only be invoked after `initSession()` completes, either within the callback or after a delay
// The usage type of `getShortURLWithParams()` will default to unlimited

let linkProperties: BranchLinkProperties = BranchLinkProperties()
linkProperties.channel = "facebook"
linkProperties.feature = "sharing"
linkProperties.campaign = "content 123 launch"
linkProperties.stage = "new user"
linkProperties.tags = ["one", "two", "three"]
linkProperties.alias = "myapp.com/customalias"
linkProperties.matchDuration = 0

func generateShortUrl(params: [AnyHashable : Any], linkProperties: BranchLinkProperties, completion: @escaping (String?, Error?)->(Void)) -> Void {
	Branch.getInstance().getShortUrl(withParams: params, andTags: linkProperties.tags, andAlias: linkProperties.alias, andMatchDuration: linkProperties.matchDuration, andChannel: linkProperties.channel, andFeature: linkProperties.feature, andStage: linkProperties.stage, andCampaign: linkProperties.campaign) { (url, error) in
		if (error == nil) {
			completion(url, nil)
		} else {
			completion(nil, error)
		}
	}
}
// Warning: This method should only be invoked after `initSession()` completes, either within the callback or after a delay
// The usage type of `getShortURLWithParams()` will default to unlimited

BranchLinkProperties *linkProperties = [[BranchLinkProperties alloc] init];
linkProperties.feature = @"share";
linkProperties.channel = @"facebook";
linkProperties.stage = @"new user";
linkProperties.tags = @["one", "two", "three"]

Branch *branch = [Branch getInstance];
[branch getShortURLWithParams:nil andTags:linkProperties.tags andChannel:linkProperties.channel andFeature:linkProperties.feature andStage:linkProperties.stage andCallback:^(NSString *url, NSError *error) {
	// Do stuff with URL here
}];

getSpotlightUrlWithParams (async)

Warning: This method should only be invoked after initSession() completes, either within the callback or after a delay. If it is invoked before, Branch will silently initialize the SDK before the callback has been set, in order to carry out this method's required task. As a result, you may experience issues where the initSession() callback does not fire.

MethodDescription
(void)getSpotlightUrlWithParams:(NSDictionary *)params callback:(callbackWithParams)callback;Get a Spotlight URL with specified parameters.
ArgumentTypeDescription
paramsNSDictionaryDictionary of parameters to include in the Spotlight URL.
callbackcallbackWithParamsCallback called with the Spotlight URL.

Example Usage

// Warning: This method should only be invoked after `initSession()` completes, either within the callback or after a delay

let params: [String: Any] = [
    "key1": "value1",
    "key2": "value2"
]

Branch.getInstance().getSpotlightUrl(withParams: params) { (returnedParams, error) in
	if let url = returnedParams?["url"] as? String {
		print("Got spotlight URL with params: \(url)")
	}
}
// Warning: This method should only be invoked after `initSession()` completes, either within the callback or after a delay

NSDictionary *params = @{
    @"key1": @"value1",
    @"key2": @"value2"
};

[[Branch getInstance] getSpotlightUrlWithParams:params callback:^(NSDictionary * _Nullable returnedParams, NSError * _Nullable error) {
	NSLog(@"Got spotlight URL with params: %@", returnedParams[@"url"]);
}];

createDiscoverableContentWithTitle

Warning: The variations of createDiscoverableContentWithTitle in this table are only useable in iOS 9 or above - earlier versions will simply receive the callback with an error.

MethodDescription
(void)createDiscoverableContentWithTitle:(NSString *)title description:(NSString *)description;Take the current screen and make it discoverable, adding it to Apple's Core Spotlight index. It will not be public by default. Type defaults to kUTTypeImage.
(void)createDiscoverableContentWithTitle:(NSString *)title description:(NSString *)description callback:(callbackWithUrl)callback;Take the current screen and make it discoverable, adding it to Apple's Core Spotlight index. It will not be public by default. Type defaults to kUTTypeImage.
(void)createDiscoverableContentWithTitle:(NSString *)title description:(NSString *)description publiclyIndexable:(BOOL)publiclyIndexable callback:(callbackWithUrl)callback;Take the current screen and make it discoverable, adding it to Apple's Core Spotlight index. Will be public if specified. Type defaults to kUTTypeImage.
(void)createDiscoverableContentWithTitle:(NSString *)title description:(NSString *)description type:(NSString *)type publiclyIndexable:(BOOL)publiclyIndexable callback:(callbackWithUrl)callback;Take the current screen and make it discoverable, adding it to Apple's Core Spotlight index. Will be public if specified. You can override the type as desired, using one of the types provided in MobileCoreServices.
(void)createDiscoverableContentWithTitle:(NSString *)title description:(NSString *)description thumbnailUrl:(NSURL *)thumbnailUrl type:(NSString *)type publiclyIndexable:(BOOL)publiclyIndexable callback:(callbackWithUrl)callback;Take the current screen and make it discoverable, adding it to Apple's Core Spotlight index. Will be public if specified. You can override the type as desired, using one of the types provided in MobileCoreServices.
(void)createDiscoverableContentWithTitle:(NSString *)title description:(NSString *)description thumbnailUrl:(NSURL *)thumbnailUrl type:(NSString *)type publiclyIndexable:(BOOL)publiclyIndexable keywords:(NSSet *)keywords callback:(callbackWithUrl)callback;Take the current screen and make it discoverable, adding it to Apple's Core Spotlight index. Will be public if specified. You can override the type as desired, using one of the types provided in MobileCoreServices.
(void)createDiscoverableContentWithTitle:(NSString *)title description:(NSString *)description thumbnailUrl:(NSURL *)thumbnailUrl linkParams:(NSDictionary *)linkParams publiclyIndexable:(BOOL)publiclyIndexable keywords:(NSSet *)keywords;Take the current screen and make it discoverable, adding it to Apple's Core Spotlight index. Will be public if specified. You can override the type as desired, using one of the types provided in MobileCoreServices.
(void)createDiscoverableContentWithTitle:(NSString *)title description:(NSString *)description thumbnailUrl:(NSURL *)thumbnailUrl linkParams:(NSDictionary *)linkParams type:(NSString *)type publiclyIndexable:(BOOL)publiclyIndexable keywords:(NSSet *)keywords;Take the current screen and make it discoverable, adding it to Apple's Core Spotlight index. Will be public if specified. You can override the type as desired, using one of the types provided in MobileCoreServices.
(void)createDiscoverableContentWithTitle:(NSString *)title description:(NSString *)description thumbnailUrl:(NSURL *)thumbnailUrl type:(NSString *)type publiclyIndexable:(BOOL)publiclyIndexable keywords:(NSSet *)keywords;Take the current screen and make it discoverable, adding it to Apple's Core Spotlight index. Will be public if specified. You can override the type as desired, using one of the types provided in MobileCoreServices.
(void)createDiscoverableContentWithTitle:(NSString *)title description:(NSString *)description thumbnailUrl:(NSURL *)thumbnailUrl linkParams:(NSDictionary *)linkParams publiclyIndexable:(BOOL)publiclyIndexable;Take the current screen and make it discoverable, adding it to Apple's Core Spotlight index. Will be public if specified. You can override the type as desired, using one of the types provided in MobileCoreServices.
(void)createDiscoverableContentWithTitle:(NSString *)title description:(NSString *)description thumbnailUrl:(NSURL *)thumbnailUrl linkParams:(NSDictionary *)linkParams type:(NSString *)type publiclyIndexable:(BOOL)publiclyIndexable keywords:(NSSet *)keywords callback:(callbackWithUrl)callback;Take the current screen and make it discoverable, adding it to Apple's Core Spotlight index. Will be public if specified. You can override the type as desired, using one of the types provided in MobileCoreServices.
(void)createDiscoverableContentWithTitle:(NSString *)title description:(NSString *)description thumbnailUrl:(NSURL *)thumbnailUrl linkParams:(NSDictionary *)linkParams type:(NSString *)type publiclyIndexable:(BOOL)publiclyIndexable keywords:(NSSet *)keywords expirationDate:(NSDate *)expirationDate callback:(callbackWithUrl)callback;Take the current screen and make it discoverable, adding it to Apple's Core Spotlight index. Will be public if specified. You can override the type as desired, using one of the types provided in MobileCoreServices.
(void)createDiscoverableContentWithTitle:(NSString *)title description:(NSString *)description thumbnailUrl:(NSURL *)thumbnailUrl canonicalId:(NSString *)canonicalId linkParams:(NSDictionary *)linkParams type:(NSString *)type publiclyIndexable:(BOOL)publiclyIndexable keywords:(NSSet *)keywords expirationDate:(NSDate *)expirationDate callback:(callbackWithUrl)callback;Take the current screen and make it discoverable, adding it to Apple's Core Spotlight index. Will be public if specified. You can override the type as desired, using one of the types provided in MobileCoreServices.
(void)createDiscoverableContentWithTitle:(NSString *)title description:(NSString *)description thumbnailUrl:(NSURL *)thumbnailUrl linkParams:(NSDictionary *)linkParams type:(NSString *)type publiclyIndexable:(BOOL)publiclyIndexable keywords:(NSSet *)keywords expirationDate:(NSDate *)expirationDate spotlightCallback:(callbackWithUrlAndSpotlightIdentifier)spotlightCallback;Take the current screen and make it discoverable, adding it to Apple's Core Spotlight index. Will be public if specified. You can override the type as desired, using one of the types provided in MobileCoreServices.
(void)createDiscoverableContentWithTitle:(NSString *)title description:(NSString *)description thumbnailUrl:(NSURL *)thumbnailUrl canonicalId:(NSString *)canonicalId linkParams:(NSDictionary *)linkParams type:(NSString *)type publiclyIndexable:(BOOL)publiclyIndexable keywords:(NSSet *)keywords expirationDate:(NSDate *)expirationDate spotlightCallback:(callbackWithUrlAndSpotlightIdentifier)spotlightCallback;Take the current screen and make it discoverable, adding it to Apple's Core Spotlight index. Will be public if specified. You can override the type as desired, using one of the types provided in MobileCoreServices.
ArgumentTypeDescription
titleNSStringTitle for the Spotlight preview item.
descriptionNSStringDescription for the Spotlight preview item.
callbackcallWithUrlCallback called with the Branch URL this will fallback to.
publiclyIndexableBOOLWhether or not this item should be added to Apple's public search index.
typeNSStringThe type to use for the NSUserActivity, taken from the list of constants provided in the MobileCoreServices framework.
thumbnailUrlNSURLURL to an image to be used for the thumbnail in Spotlight.
keywordsNSSetA set of keywords to be used in Apple's search index.
linkParamsNSDictionaryAdditional params to be added to the NSUserActivity. These will also be added to the Branch link.
expirationDateNSDateExpiration date after which this will not appear in Apple's search index
canonicalIdNSStringThe canonical identifier for the content for deduplication.
spotlightCallbackcallbackWithUrlAndSpotlightIdentifierCallback called with the Branch URL this will fallback to.

Example Usage

Branch.getInstance().createDiscoverableContent(withTitle: "Discover Branch", description: "Content Description")
[[Branch getInstance] createDiscoverableContentWithTitle:self.title
description:self.contentDescription
thumbnailUrl:[NSURL URLWithString:self.imageUrl]
canonicalId:self.canonicalIdentifier
linkParams:metadataAndProperties.copy
type:self.type
publiclyIndexable:publiclyIndexable
keywords:[NSSet setWithArray:self.keywords]
expirationDate:self.expirationDate
spotlightCallback:spotlightCallback];

indexOnSpotlightWithBranchUniversalObject

Warning: This method is only useable in iOS 9 or above - earlier versions will simply receive the callback with an error.

ArgumentTypeDescription
universalObjectBranchUniversalObjectDictionary of parameters to include in the Spotlight URL.
linkPropertiesBranchLinkPropertiesCallback called with the Spotlight URL.
completionBranchUniversalObject or NSString or NSErrorCallback called when all Branch Universal Object instance are indexed. Dynamic URL generated and saved as Spotlight identifier.

Example Usage

let buo = BranchUniversalObject(canonicalIdentifier: "item/12345")
let lp = BranchLinkProperties()

Branch.getInstance().indexOnSpotlight(with: buo, linkProperties: lp) { (universalObject, url, error) in
	print("Indexed Branch Universal Object instance on Spotlight.")
}
BranchUniversalObject *buo =  [[BranchUniversalObject alloc] initWithCanonicalIdentifier:@"item/12345"];
BranchLinkProperties *lp = [[BranchLinkProperties alloc] init];

[[Branch getInstance] indexOnSpotlightWithBranchUniversalObject:buo linkProperties:lp completion:^(BranchUniversalObject * _Nonnull universalObject, NSString * _Nonnull url, NSError * _Nonnull error) {
	NSLog(@"Indexed Branch Universal Object instance on Spotlight.");
}];

indexOnSpotlightUsingSearchableItems

Warning: This method is only useable in iOS 9 or above - earlier versions will simply receive the callback with an error.

MethodDescription
(void)indexOnSpotlightUsingSearchableItems:(NSArray<BranchUniversalObject*>*)universalObjects completion:(void (^) (NSArray<BranchUniversalObject*>* universalObjects, NSError* error))completion;Index multiple Branch Universal Object instances using SearchableItem from Apple's CoreSpotlight. Content indexed is private irrespective of the ContentIndexMode value of the BUOs.
ArgumentTypeDescription
universalObjectsNSArray<BranchUniversalObject>Multiple Branch Universal Object instances are indexed on Spotlight using Spotlight metadata.
completionNSArray<BranchUniversalObject> or NSErrorCallback called when all Branch Universal Object instances are indexed. The dynamic URL generated is returned as the spotlightIdentifier of the BUO. Use this identifier to remove content from Spotlight.

Example Usage

let buoArray: [BranchUniversalObject] = [
  BranchUniversalObject(canonicalIdentifier: "item/12345"),
  BranchUniversalObject(canonicalIdentifier: "item/6789")
]

Branch.getInstance().indexOnSpotlight(usingSearchableItems: buoArray) { (universalObjects, error) in
	print("Indexed Branch Universal Object instance on Spotlight.")
}
NSArray<BranchUniversalObject *> *buoArray = @[
  [[BranchUniversalObject alloc] initWithCanonicalIdentifier:@"item/12345"],
  [[BranchUniversalObject alloc] initWithCanonicalIdentifier:@"item/6789"]
];

[[Branch getInstance] indexOnSpotlightUsingSearchableItems:buoArray completion:^(NSArray<BranchUniversalObject *> * _Nonnull universalObjects, NSError * _Nonnull error) {
	NSLog(@"Indexed Branch Universal Object instance on Spotlight.");
}];

removeSearchableItemWithBranchUniversalObject

Warning: This method is only useable in iOS 9 or above - earlier versions will simply receive the callback with an error.

MethodDescription
(void)removeSearchableItemWithBranchUniversalObject:(BranchUniversalObject *)universalObject callback:(void (^_Nullable)(NSError * _Nullable error))completion;Remove indexing of a Branch Universal Object instance, which is indexed using SearchableItem from Apple's CoreSpotlight.
ArgumentTypeDescription
universalObjectBranchUniversalObjectThe Branch Universal Object instance that is to be removed from indexing.
completionvoid (^_Nullable)(NSError * _Nullable error)Called when the request has been journaled by the index. Here “journaled” means that the index makes a note that it has to perform this operation. Note that the request may not have completed.

Example Usage

let buo = BranchUniversalObject(canonicalIdentifier: "item/12345")

Branch.getInstance().removeSearchableItem(with: buo) { (universalObject, error) in
	print("Removed Branch Universal Object instance from Spotlight.")                                                                          
}
BranchUniversalObject *buo =  [[BranchUniversalObject alloc] initWithCanonicalIdentifier:@"item/12345"];

[[Branch getInstance] removeSearchableItemWithBranchUniversalObject:buo completion:^(BranchUniversalObject * _Nonnull universalObject, NSError * _Nonnull error) {
	NSLog(@"Removed Branch Universal Object instance on Spotlight.");
}];

removeSearchableItemsWithBranchUniversalObject

Warning: This method is only useable in iOS 9 or above - earlier versions will simply receive the callback with an error.

MethodDescription
(void)removeSearchableItemsWithBranchUniversalObjects:(NSArray<BranchUniversalObject*> *)universalObjects callback:(void (^_Nullable)(NSError * _Nullable error))completion;Remove indexing of an array of Branch Universal Object instances, which are indexed using SearchableItem from Apple's CoreSpotlight.
ArgumentTypeDescription
universalObjectsNSArray<BranchUniversalObject>The Branch Universal Object instances to remove from Spotlight indexing. Note: The Spotlight identifier of the BUO is used to remove indexing.
completionvoid (^_Nullable)(NSError * _Nullable error)Called when the request has been journaled by the index. Here “journaled” means that the index makes a note that it has to perform this operation. Note that the request may not have completed.

Example Usage

let buoArray: [BranchUniversalObject] = [
  BranchUniversalObject(canonicalIdentifier: "item/12345"),
  BranchUniversalObject(canonicalIdentifier: "item/6789")
]

Branch.getInstance().removeSearchableItems(with: buoArray) { (universalObjects, error) in
	print("Removed Branch Universal Object instances on Spotlight.")
}

NSArray<BranchUniversalObject *> *buoArray = @[
  [[BranchUniversalObject alloc] initWithCanonicalIdentifier:@"item/12345"],
  [[BranchUniversalObject alloc] initWithCanonicalIdentifier:@"item/6789"]
];

[[Branch getInstance] removeSearchableItemsWithBranchUniversalObject:buoArray completion:^(NSArray<BranchUniversalObject *> * _Nonnull universalObjects, NSError * _Nonnull error) {
	NSLog(@"Indexed Branch Universal Object instance on Spotlight.");
}];

removeAllPrivateContentFromSpotLightWithCallback

Warning: This method is only useable in iOS 9 or above - earlier versions will simply receive the callback with an error.

MethodDescription
(void)removeAllPrivateContentFromSpotLightWithCallback:(void (^_Nullable)(NSError * _Nullable error))completion;Remove all content Spotlight indexed, through either SearchableItem or privately indexed Branch Universal Object instances.
ArgumentTypeDescription
completionvoid (^_Nullable)(NSError * _Nullable error)Called when the request has been journaled by the index. Here “journaled” means that the index makes a note that it has to perform this operation. Note that the request may not have completed.

Example Usage

Branch.getInstance().removeAllPrivateContentFromSpotLight { (error) in
    print("Removed all private content from Spotlight.")
}
[[Branch getInstance] removeAllPrivateContentFromSpotLightWithCallback:^(NSError * _Nullable error) {
	NSLog(@"Removed all private content from Spotlight.");
}];

passPasteItemProviders

Warnings:

  • This function only works with iOS 16 or above.
  • Do not call both checkPasteboardOnInstall() and passPasteItemProviders(), or use BranchPasteControl without properly version checking, as checkPasteboardOnInstall() will be called on iOS 16+ as well.
MethodDescription
(void)passPasteItemProviders:(NSArray<NSItemProvider *> *)itemProviders API_AVAILABLE(ios(16));Pass pasteboard items to the Branch SDK when the user implements UIPasteControl on their end. Branch SDK retrieves the URL from these item providers, if any, to support Branch NativeLink functionality.
ArgumentTypeDescription
itemProvidersNSArray<NSItemProvider>An array of item providers collected from the pasteboard.

Example Usage

// Inside the ViewController
override func paste(itemProviders: [NSItemProvider]) {
	if #available(iOS 16.0, *) {
		Branch.getInstance().passPaste(itemProviders)
	} else {
		// Fallback on earlier versions
	}
}
// Inside the ViewController
if (@available(iOS 16.0, *)) {
	[[Branch getInstance] passPasteItemProviders:itemProviders]
}

setLogInAppPurchasesAsEventsEnabled

MethodDescription
(void)setLogInAppPurchasesAsEventsEnabled:(BOOL)enabled;Log in-app purchases as Branch Events.
ArgumentTypeDescription
enabledBOOLSet to true to log in-app purchases as events.

Example Usage

Branch.getInstance().setLogInAppPurchasesAsEventsEnabled(true)
[[Branch getInstance] setLogInAppPurchasesAsEventsEnabled:YES];

logInAppPurchasesBranchEventsEnabled

MethodDescription
(BOOL)logInAppPurchasesBranchEventsEnabled;Check to see if you are tracking in-app purchases as Branch Events.

Returns true if you are tracking in-app purchases as Branch Events.

Example Usage

Branch.getInstance().logInAppPurchasesBranchEventsEnabled()
[[Branch getInstance] logInAppPurchasesBranchEventsEnabled];

logEventWithCompletion

MethodDescription
(void)logEventWithCompletion:(void (^_Nullable)(BOOL success, NSError * _Nullable error))completion;Logs the event on the Branch server. This version will callback on success/failure.
ArgumentTypeDescription
completionvoid (^_Nullable)(BOOL success, NSError * _Nullable error)Completion handler containing any potential error.

Example Usage

// This method should only be invoked after `initSession()`
// If it's invoked before, Branch will silently initialize the SDK before the callback has been set

let event = BranchEvent(standardEvent: .addToCart)
event.logEvent { (success, error) in
    print("Event logged: \(success)")
}
// This method should only be invoked after `initSession()`
// If it's invoked before, Branch will silently initialize the SDK before the callback has been set

// Example 1
event = [BranchEvent standardEvent:BranchStandardEventInitiatePurchase];
[event logEventWithCompletion:^(BOOL success, NSError * _Nullable error) {
	if (success) {
		[self showAlert:@"Succesfully logged commerce event" withDescription:@""];
	} else {
		[self showAlert:@"Error sending commerce event:" withDescription:error.description];
	}
}];

// Example 2
BranchEvent *event = [BranchEvent standardEvent:BranchStandardEventAddToCart];
[event logEventWithCompletion:^(BOOL success, NSError * _Nullable error) {
    NSLog(@"Event logged: %@", @(success));
}];

logEvent

MethodDescription
(void)logEvent;Logs the event on the Branch server. This version automatically caches and retries as necessary.

To learn more about creating a Branch Universal Object (BUO) instance to associate with the Branch Event, follow the examples in this guide.

Example Usage

// This method should only be invoked after `initSession()`
// If it's invoked before, Branch will silently initialize the SDK before the callback has been set

// Create a Branch Event (this example uses the `Purchase` event)
let event = BranchEvent.standardEvent(.purchase)

// Add a populated `BranchUniversalObject` to the event
let buo = BranchUniversalObject(canonicalIdentifier: "item/12345")
event.contentItems     = [ buo ]

// Add additional event data
event.alias = "my custom alias"
event.transactionID = "12344555"
event.eventDescription = "event_description"
event.searchQuery = "item 123"
event.customData = [
    "Custom_Event_Property_Key1": "Custom_Event_Property_val1",
    "Custom_Event_Property_Key2": "Custom_Event_Property_val2"
]

// Log the event
event.logEvent()
// This method should only be invoked after `initSession()`
// If it is invoked before, Branch will silently initialize the SDK before the callback has been set

// Create a Branch Event (this example uses the `BranchStandardEventAddToCart` event)
BranchEvent *event     = [BranchEvent standardEvent:BranchStandardEventAddToCart];

// Add a populated `BranchUniversalObject` to the event
BranchUniversalObject *buo =  [[BranchUniversalObject alloc] initWithCanonicalIdentifier:@"item/12345"];
event.contentItems     = (id) @[ buo ];

// Add additional event data
event.alias = @"my custom alias";
event.transactionID = @"12344555";
event.eventDescription = @"event_description";
event.searchQuery = @"item 123";
event.customData = (NSMutableDictionary*) @{
    @"Custom_Event_Property_Key1": @"Custom_Event_Property_val1",
    @"Custom_Event_Property_Key2": @"Custom_Event_Property_val2"
};

// Log the event
[event logEvent];

logEventWithTransaction

MethodDescription
(void) logEventWithTransaction:(SKPaymentTransaction*_Nonnull)transaction;Log an SKPaymentTransaction as a Branch Event.
ArgumentTypeDescription
transactionSKPaymentTransactionThe SKPaymenTransaction to log as a Branch Event.

Example Usage

let event = BranchEvent(name: "PURCHASE")
event.logEvent(with: transaction as! SKPaymentTransaction)
BranchEvent *event = [[BranchEvent alloc] initWithName:@"eventName"];
[event logEventWithTransaction:(SKPaymentTransaction *)transaction];

addControlParam

MethodDescription
(void)addControlParam:(NSString *)controlParam withValue:(NSString *)value;Add a control parameter to a Branch Link Properties object.
ArgumentTypeDescription
controlParamNSStringThe name of the control parameter.
valueNSStringThe value of the control parameter.

Example Usage

let lp = BranchLinkProperties()
lp.addControlParam("$desktop_url", withValue: "http://example.com/desktop")
lp.addControlParam("$ios_url", withValue: "http://example.com/ios")
lp.addControlParam("$ipad_url", withValue: "http://example.com/ios")
lp.addControlParam("$android_url", withValue: "http://example.com/android")
lp.addControlParam("$match_duration", withValue: "2000")
lp.addControlParam("custom_data", withValue: "yes")
lp.addControlParam("look_at", withValue: "this")
lp.addControlParam("nav_to", withValue: "over here")
lp.addControlParam("random", withValue: UUID.init().uuidString)
BranchLinkProperties *lp = [[BranchLinkProperties alloc] init];
lp.feature = @"facebook";
lp.channel = @"sharing";
lp.campaign = @"content 123 launch";
lp.stage = @"new user";
lp.tags = @[@"one", @"two", @"three"];

[lp addControlParam:@"$desktop_url" withValue: @"http://example.com/desktop"];
[lp addControlParam:@"$ios_url" withValue: @"http://example.com/ios"];
[lp addControlParam:@"$ipad_url" withValue: @"http://example.com/ios"];
[lp addControlParam:@"$android_url" withValue: @"http://example.com/android"];
[lp addControlParam:@"$match_duration" withValue: @"2000"];

[lp addControlParam:@"custom_data" withValue: @"yes"];
[lp addControlParam:@"look_at" withValue: @"this"];
[lp addControlParam:@"nav_to" withValue: @"over here"];
[lp addControlParam:@"random" withValue: [[NSUUID UUID] UUIDString]];

getBranchLinkPropertiesFromDictionary

MethodDescription
(BranchLinkProperties *)getBranchLinkPropertiesFromDictionary:(NSDictionary *)dictionary;Converts a given dictionary into a BranchLinkProperties object. This enables seamless mapping between dictionary-based data representations and the SDK's native data models, allowing for a more flexible and convenient way to handle link properties.

Returns a BranchLinkProperties object populated with the values from the provided dictionary.
ArgumentTypeDescription
dictionaryNSDictionaryA dictionary containing key-value pairs that map to the properties of a BranchLinkProperties object.

Example Usage

let lp = BranchLinkProperties.getBranchLinkProperties(from: lpDictionary)
// Example 1
NSDictionary *params = [self getFirstReferringParams];
if ([[params objectForKey:BRANCH_INIT_KEY_CLICKED_BRANCH_LINK] isEqual:@1]) {
	return [BranchLinkProperties getBranchLinkPropertiesFromDictionary:params];
}

// Example 2
BranchLinkProperties *lp = [BranchLinkProperties getBranchLinkPropertiesFromDictionary:lpDictionary];

initWithFrame (BranchPasteControl)

ArgumentTypeDescription
frameCGRectA CGRect specifying the dimensions and position for the view.
configUIPasteControlConfigurationAn optional UIPasteControlConfiguration object that contains settings for customizing the paste functionality.

Example Usage

// Inside the ViewController
if #available(iOS 16.0, *) {
	// Setup `UIPasteControl` configuration
	let pcConfig = UIPasteControl.Configuration()
	pcConfig.baseBackgroundColor = UIColor.blue
	pcConfig.displayMode = UIPasteControl.DisplayMode.iconOnly

	// Create frame and button
	let frameDimension = CGRect(x: 0, y: 0, width: 40, height: 40)
	let bc = BranchPasteControl(frame: frameDimension, andConfiguration: pcConfig)

	// Add `BranchPasteControl` button to superview
	view.addSubview(bc)
}
// Inside the ViewController
if (@available(iOS 16.0, *)) {
  // Setup `UIPasteControl` configuration
  UIPasteControlConfiguration *pcConfig = [[UIPasteControlConfiguration alloc] init];
  pcConfig.baseBackgroundColor = UIColor.blueColor;
  pcConfig.displayMode = UIPasteControlDisplayModeIconOnly;

  // Create frame and button
  CGRect frameDimension = CGRectMake(0, 0, 120.0, 30.0);
  BranchPasteControl *bc = [[BranchPasteControl alloc] initWithFrame:frameDimension AndConfiguration:pcConfig];

  // Add `BranchPasteControl` button to superview
  [view addSubview:bc];
}

showShareSheetWithQRCodeFromViewController

ArgumentTypeDescription
viewControllerUIViewControllerThe ViewController.
anchorViewOrButtonItemidSpecifies the anchor UI element for presenting the Share Sheet. Accepts either a UIView or a UIBarButtonItem. If nil, the Share Sheet will appear centered.
buoBranchUniversalObjectThe Branch Universal Object instance to share.
lpBranchLinkPropertiesThe Branch Link Properties object to associate with the Branch QR Code.
completionNSErrorCompletion handler containing any potential error.

Example Usage

let qrCode = BranchQRCode()
qrCode.codeColor = UIColor.white
qrCode.backgroundColor = UIColor.blue
qrCode.centerLogo = "https://cdn.branch.io/branch-assets/1598575682753-og_image.png"
qrCode.width = 1024
qrCode.margin = 1
qrCode.imageFormat = .JPEG

let buo = BranchUniversalObject(canonicalIdentifier: "item/12345")
let lp = BranchLinkProperties()

// Display the QR code directly in a share sheet
qrCode.showShareSheetWithQRCode(from: self, anchor: nil, universalObject: buo, linkProperties: lp) { error in
    // Showing a share sheet with the QR code
}
BranchQRCode *qrCode = [BranchQRCode new];
qrCode.codeColor = [[UIColor new] initWithRed:0.1 green:0.8392 blue:0.8667 alpha:1.0];
qrCode.backgroundColor = [UIColor whiteColor];
qrCode.width = @700;
qrCode.margin = @1;
qrCode.centerLogo = @"https://cdn.branch.io/branch-assets/1598575682753-og_image.png";
qrCode.imageFormat = BranchQRCodeImageFormatPNG;
    
BranchUniversalObject *buo =  [[BranchUniversalObject alloc] initWithCanonicalIdentifier:@"item/12345"];
BranchLinkProperties *lp = [BranchLinkProperties new];

// Display the QR code directly in a share sheet
[qrCode showShareSheetWithQRCodeFromViewController:self anchor:nil universalObject:buo linkProperties:lp completion:^(NSError * _Nullable error) {
    // Showing a share sheet with the QR code
}];

getQRCodeAsData

ArgumentTypeDescription
buoBranchUniversalObjectThe Branch Universal Object instance to share.
lpBranchLinkPropertiesThe Branch Link Properties object to associate with the Branch QR Code.
completionNSErrorCompletion handler containing a Branch QR Code image or an error.

Example Usage

let qrCode = BranchQRCode()
qrCode.codeColor = UIColor.white
qrCode.backgroundColor = UIColor.blue
qrCode.centerLogo = "https://cdn.branch.io/branch-assets/1598575682753-og_image.png"
qrCode.width = 1024
qrCode.margin = 1
qrCode.imageFormat = .JPEG

let buo = BranchUniversalObject(canonicalIdentifier: "item/12345")
let lp = BranchLinkProperties()

qrCode.getAsData(buo, linkProperties: lp) { qrCodeImage, error in
    // Do something with your QR code here...
}
BranchQRCode *qrCode = [BranchQRCode new];
qrCode.codeColor = [[UIColor new] initWithRed:0.1 green:0.8392 blue:0.8667 alpha:1.0];
qrCode.backgroundColor = [UIColor whiteColor];
qrCode.width = @700;
qrCode.margin = @1;
qrCode.centerLogo = @"https://cdn.branch.io/branch-assets/1598575682753-og_image.png";
qrCode.imageFormat = BranchQRCodeImageFormatPNG;
    
BranchUniversalObject *buo =  [[BranchUniversalObject alloc] initWithCanonicalIdentifier:@"item/12345"];
BranchLinkProperties *lp = [BranchLinkProperties new];

[qrCode getQRCodeAsData:buo linkProperties:lp completion:^(UIImage * _Nonnull qrCode, NSError * _Nonnull error) {
    // Do something with the QR code here...
}];

getQRCodeAsImage

ArgumentTypeDescription
buoBranchUniversalObjectThe Branch Universal Object instance to share.
lpBranchLinkPropertiesThe Branch Link Properties object to associate with the Branch QR Code.
completionNSErrorCompletion handler containing a Branch QR Code image or an error.

Example Usage

let qrCode = BranchQRCode()
qrCode.codeColor = UIColor.white
qrCode.backgroundColor = UIColor.blue
qrCode.centerLogo = "https://cdn.branch.io/branch-assets/1598575682753-og_image.png"
qrCode.width = 1024
qrCode.margin = 1
qrCode.imageFormat = .JPEG

let buo = BranchUniversalObject(canonicalIdentifier: "item/12345")
let lp = BranchLinkProperties()

qrCode.getAsImage(buo, linkProperties: lp) { qrCodeImage, error in
    // Do something with your QR code here...
}
BranchQRCode *qrCode = [BranchQRCode new];
qrCode.codeColor = [[UIColor new] initWithRed:0.1 green:0.8392 blue:0.8667 alpha:1.0];
qrCode.backgroundColor = [UIColor whiteColor];
qrCode.width = @700;
qrCode.margin = @1;
qrCode.centerLogo = @"https://cdn.branch.io/branch-assets/1598575682753-og_image.png";
qrCode.imageFormat = BranchQRCodeImageFormatPNG;
    
BranchUniversalObject *buo =  [[BranchUniversalObject alloc] initWithCanonicalIdentifier:@"item/12345"];
BranchLinkProperties *lp = [BranchLinkProperties new];

[qrCode getQRCodeAsImage:buo linkProperties:lp completion:^(UIImage * _Nonnull qrCode, NSError * _Nonnull error) {
    // Do something with the QR code here...
}];

initSessionWithLaunchOptions (UIScene)

This method is part of the BranchScene : NSObject interface. Learn more about apps using scenes.

ArgumentTypeDescription
optionsNSDictionaryThe launch options provided by your AppDelegate file's didFinishLaunchingW