Initialize a Branch session with your app's specific launch options, and handle the completion with a callbackWithBranchUniversalObject object.
Argument
Type
Description
options
NSDictionary
The launch options provided by your AppDelegate file's didFinishLaunchingWithOptions: method.
callback
callbackWithParams or callbackWithBranchUniversalObject
A 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.
Parameter
Description
~channel
The channel on which the link was shared, specified at Branch Link creation time.
~feature
The feature, such as invite or share, specified at Branch Link creation time.
~tags
Any tags, specified at Branch Link creation time.
~campaign
The campaign the link is associated with, specified at Branch Link creation time.
~stage
The stage, specified at Branch Link creation time.
~creation_source
Where the Branch Link was created ('API', 'Dashboard', 'SDK', 'iOS SDK', 'Android SDK', or 'Web SDK').
+match_guaranteed
True or false as to whether the match was made with 100% accuracy.
+referrer
The referrer for the Branch Link click, if a Branch Link was clicked.
+phone_number
The phone number of the user, if the user texted themself the app.
+is_first_session
Denotes whether this is the first session (install) or any other session (open).
+clicked_branch_link
Denotes whether or not the user clicked a Branch Link that triggered this session.
+click_timestamp
Epoch 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.
Allow Branch to handle a link that opens the app, and to parse the parameters from it.
Returns true if Branch handled the link.
Argument
Type
Description
url
NSURL
The 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];
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.
Argument
Type
Description
userInfo
NSDictionary
The 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;
}
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.
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];
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.
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;
}
Set the AppGroup used to share data between the App Clip and your full app.
Argument
Type
Description
appGroup
NSString
The 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;
}
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];
}];
}
}
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.
Argument
Type
Description
disableCallouts
BOOL
When set to true, callouts to ad networks will be disabled.
Add key-value pairs to the metadata of every request.
Some Data Integration Partnersrequire specific identifiers to be set prior to Branch initialization. Use this function to set those identifiers.
Argument
Type
Description
key
NSString
Key to be included in request metadata.
value
NSString
Value 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.
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.
Argument
Type
Description
disabled
BOOL
When set to true, tracking will be disabled.
Implications of Using setTrackingDisabled
Action
Will work?
Opening Branch Deep Links with an explicit URL
Y
Deferred deep linking
N
Generating short links
N (returns long links)
Sending user tracking events such as userCompletedAction, BranchCommerceEvents, and BranchEvents
N
User rewards and credits
N
Setting a user identity and logging a user identity out
N
Example Usage
// Call takes place at the SDK level
Branch.setTrackingDisabled(true)
// Call takes place at the SDK level
[Branch setTrackingDisabled:YES];
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.
Argument
Type
Description
validityWindow
NSTimeInterval
The 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.
Sets the value of parameters required by Google Conversion APIs for DMA Compliance in the EEA region.
Argument
Type
Description
eeaRegion
Boolean
Set 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.
adPersonalizationConsent
Boolean
Set to true if user has granted consent for ads personalization.
Set to false if user has denied consent for ads personalization.
adUserDataUsageConsent
Boolean
Set 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.
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];
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];
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];
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];
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.
Argument
Type
Description
userId
NSString
The ID that Branch should use to identify this user.
callback
callbackWithParams
The callback to be called once the request has completed (success or failure).
Get a short URL with specified parameters, channel, feature, stage, and match duration.
Argument
Type
Description
params
NSDictionary
Dictionary of parameters to include in the short URL.
channel
NSString
Channel for the short URL. Examples include Facebook, Twitter, and SMS (depending on where it will be shared).
feature
NSString
Feature that the short URL is utilizing. Examples could be Sharing, Referring, Inviting, etc.
stage
NSString
The stage used for the short URL, indicating what part of a funnel the user is in.
alias
NSString
The alias for a short URL. Warning: If you pass an alias that is already taken, the method call will fail.
type
BranchLinkType
The type of short URL this is, either single use or unlimited use. Single use means once per user.
duration
NSUInteger
How 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.
Get a short URL with specified params, channel, feature, stage, campaign and match duration.
Argument
Type
Description
params
NSDictionary
Dictionary of parameters to include in the short URL.
tags
NSArray
An array of tags to associate with this short URL. Useful for tracking.
channel
NSString
Channel for the short URL. Examples include Facebook, Twitter, and SMS (depending on where it will be shared).
feature
NSString
Feature that the short URL is utilizing. Examples could be Sharing, Referring, Inviting, etc.
stage
NSString
The stage used for the short URL, indicating what part of a funnel the user is in.
alias
NSString
The alias for a short URL. Warning: If you pass an alias that is already taken, the method call will fail.
type
BranchLinkType
The type of short URL this is, either single use or unlimited use. Single use means once per user.
duration
NSUInteger
How long to keep an unmatched link click in Branch's backend server queue before discarding.
campaign
campaign
Use this field to organize the links by actual marketing campaign.
ignoreUAString
NSString
The User Agent string to tell the server to ignore the next request - prevents it from treating a preview scrape as a link click.
forceLinkCreation
BOOL
Whether 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"]];
Get a long URL with specified parameters, channel, tags, feature, stage, and alias.
Argument
Type
Description
params
NSDictionary
Dictionary of parameters to include in the long URL.
tags
NSArray
An array of tags to associate with this long URL. Useful for tracking.
channel
NSString
Channel for the long URL. Examples include Facebook, Twitter, and SMS (depending on where it will be shared).
feature
NSString
Feature that the long URL is utilizing. Examples could be Sharing, Referring, Inviting, etc.
stage
NSString
The stage used for the long URL, indicating what part of a funnel the user is in.
alias
NSString
The alias for a long URL. Warning: If you pass an alias that is already taken, the method call will fail.
campaign
campaign
Use 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"];
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.
Argument
Type
Description
params
NSDictionary
Dictionary of parameters to include in the long app.link URL.
channel
NSString
Channel for the long app.link URL. Examples include Facebook, Twitter, and SMS (depending on where it will be shared).
tags
NSArray
An array of tags to associate with this long app.link URL. Useful for tracking.
feature
NSString
Feature that the long app.link URL is utilizing. Examples could be Sharing, Referring, Inviting, etc.
stage
NSString
The stage used for the long app.link URL, indicating what part of a funnel the user is in.
alias
NSString
The 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 afterinitSession() 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.
// 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 afterinitSession() 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.
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.
Get a short URL with the specified parameters, channel, feature, stage, and match duration.
Argument
Type
Description
params
NSDictionary
Dictionary of parameters to include in the short URL.
callback
callbackWithUrl
Callback called with the short URL.
channel
NSString
The channel for the short URL. Examples include Facebook, Twitter, and SMS, depending on where it will be shared.
feature
NSString
The feature the short URL is utilizing. Examples include Sharing, Referring, Inviting, etc.
stage
NSString
The stage used for the generated short URL, indicating what part of a funnel the user is in.
alias
NSString
The alias for the short URL. Warning: If you pass an alias that is already taken, the method call will fail.
type
BranchLinkType
The type of short URL this is, either single use or unlimited use. Single use means once per user.
duration
NSUInteger
How 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 getShortUrl(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 afterinitSession() 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.
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.
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.
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.
Argument
Type
Description
params
NSDictionary
Dictionary of parameters to include in the short URL.
tags
NSArray
An array of tags to associate with the short URL. Useful for tracking.
callback
callbackWithUrl
Callback called with the short URL.
channel
NSString
The channel for the short URL. Examples include Facebook, Twitter, and SMS, depending on where it will be shared.
feature
NSString
The feature the short URL is utilizing. Examples include Sharing, Referring, Inviting, etc.
stage
NSString
The stage used for the generated short URL, indicating what part of a funnel the user is in.
alias
NSString
The alias for the short URL. Warning: If you pass an alias that is already taken, the method call will fail.
type
BranchLinkType
The type of short URL this is, either single use or unlimited use. Single use means once per user.
duration
NSUInteger
How 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 afterinitSession() 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.
Dictionary of parameters to include in the Spotlight URL.
callback
callbackWithParams
Callback 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Argument
Type
Description
title
NSString
Title for the Spotlight preview item.
description
NSString
Description for the Spotlight preview item.
callback
callWithUrl
Callback called with the Branch URL this will fallback to.
publiclyIndexable
BOOL
Whether or not this item should be added to Apple's public search index.
type
NSString
The type to use for the NSUserActivity, taken from the list of constants provided in the MobileCoreServices framework.
thumbnailUrl
NSURL
URL to an image to be used for the thumbnail in Spotlight.
keywords
NSSet
A set of keywords to be used in Apple's search index.
linkParams
NSDictionary
Additional params to be added to the NSUserActivity. These will also be added to the Branch link.
expirationDate
NSDate
Expiration date after which this will not appear in Apple's search index
canonicalId
NSString
The canonical identifier for the content for deduplication.
spotlightCallback
callbackWithUrlAndSpotlightIdentifier
Callback called with the Branch URL this will fallback to.
Index multiple Branch Universal Object instances using SearchableItem from Apple's CoreSpotlight. Content indexed is private irrespective of the ContentIndexMode value of the BUOs.
Argument
Type
Description
universalObjects
NSArray<BranchUniversalObject>
Multiple Branch Universal Object instances are indexed on Spotlight using Spotlight metadata.
completion
NSArray<BranchUniversalObject> or NSError
Callback 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.")
}
Remove indexing of a Branch Universal Object instance, which is indexed using SearchableItem from Apple's CoreSpotlight.
Argument
Type
Description
universalObject
BranchUniversalObject
The Branch Universal Object instance that is to be removed from indexing.
completion
void (^_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.")
}
Remove indexing of an array of Branch Universal Object instances, which are indexed using SearchableItem from Apple's CoreSpotlight.
Argument
Type
Description
universalObjects
NSArray<BranchUniversalObject>
The Branch Universal Object instances to remove from Spotlight indexing. Note: The Spotlight identifier of the BUO is used to remove indexing.
completion
void (^_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.")
}
Remove all content Spotlight indexed, through either SearchableItem or privately indexed Branch Universal Object instances.
Argument
Type
Description
completion
void (^_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.
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.
Argument
Type
Description
itemProviders
NSArray<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]
}
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));
}];
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];
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.
Argument
Type
Description
dictionary
NSDictionary
A 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];
Create a Branch QR Code image and display it in a Share Sheet.
Argument
Type
Description
viewController
UIViewController
The ViewController.
anchorViewOrButtonItem
id
Specifies the anchor UI element for presenting the Share Sheet. Accepts either a UIView or a UIBarButtonItem. If nil, the Share Sheet will appear centered.
buo
BranchUniversalObject
The Branch Universal Object instance to share.
lp
BranchLinkProperties
The Branch Link Properties object to associate with the Branch QR Code.
completion
NSError
Completion 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
}];
Initialize a Branch session with your app's specific launch options. Callback may contain a UIScene object.
Argument
Type
Description
options
NSDictionary
The launch options provided by your AppDelegate file's didFinishLaunchingWithOptions: method.
callback
NSDictionary or NSError or UIScene
A 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
@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
// Override point for customization after application launch
BranchScene.shared().initSession(launchOptions: launchOptions, registerDeepLinkHandler: { (params, error, scene) in
})
return true
}
}
class SceneDelegate: UIResponder, UIWindowSceneDelegate {
var window: UIWindow?
// Use `scene` to optionally configure and attach the UIWindow `window` to the provided UIWindowScene `scene`
// If using a storyboard, the `window` property will automatically be initialized and attached to the scene
// This delegate does not imply the connecting scene or session are new (see `application:configurationForConnectingSceneSession` instead)
func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
guard let _ = (scene as? UIWindowScene) else { return }
// Workaround for SceneDelegate `continueUserActivity` not getting called on cold start:
if let userActivity = connectionOptions.userActivities.first {
BranchScene.shared().scene(scene, continue: userActivity)
} else if !connectionOptions.urlContexts.isEmpty {
BranchScene.shared().scene(scene, openURLContexts: connectionOptions.urlContexts)
}
}
}
@interface AppDelegate ()
@interface SceneDelegate ()
@end
@implementation SceneDelegate
// Use `scene` to optionally configure and attach the UIWindow `window` to the provided UIWindowScene `scene`
// If using a storyboard, the `window` property will automatically be initialized and attached to the scene
// This delegate does not imply the connecting scene or session are new (see `application:configurationForConnectingSceneSession` instead)
- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions {
// Workaround for SceneDelegate `continueUserActivity` not getting called on cold start
NSUserActivity *activity = [[connectionOptions userActivities] allObjects].firstObject;
if (activity) {
[[BranchScene shared] scene:scene continueUserActivity:activity];
} else if ([[connectionOptions URLContexts] count] != 0) {
[[BranchScene shared] scene:scene openURLContexts: [connectionOptions URLContexts]];
}
}
@end
initWithUniversalObject
This method is part of the BranchShareLink : NSObject <UIActivityItemSource> interface.
Use a BranchShareLink instance to retrieve an array of activity item providers: one for the Branch Universal Object instance, one for the share text (if provided), and one for the shareObject (if provided).
Example Usage
let buo = BranchUniversalObject(canonicalIdentifier: "item/12345")
let lp = BranchLinkProperties()
let shareLink = BranchShareLink(universalObject: buo, linkProperties: lp)
shareLink.activityItems()
Callback containing a dictionary of parameters or an error.
Example Usage
let buo = BranchUniversalObject(canonicalIdentifier: "item/12345")
buo.registerView { (params: [AnyHashable: Any]?, error: Error?) in
print("BUO was listed on spotlight and event was logged: \(String(describing: params))")
}
BranchUniversalObject *buo = [BranchUniversalObject new];
buo.canonicalIdentifier = @"Uniq!";
buo.title = @"Object Title";
// Example 1
[buo registerViewWithCallback:^(NSDictionary * _Nullable params, NSError * _Nullable error) {
XCTAssertNil(error);
}];
// Example 2
[buo registerViewWithCallback:^(NSDictionary * _Nullable params, NSError * _Nullable error) {
NSLog(@"BUO was listed on spotlight and event was logged: %@", params);
}];
getShortUrlWithLinkProperties
This method is part of the BranchUniversalObject : NSObject interface.
Returns a Branch short URL for the specified Branch Universal Object instance and includes the passed Link Properties object. Callback may contain URL or error.
Argument
Type
Description
linkProperties
BranchLinkProperties
The Branch Link Properties object to associate with the Branch short URL.
callback
NSString or NSError
Callback containing a string URL or an error.
Example Usage
let buo = BranchUniversalObject(canonicalIdentifier: "item/12345")
let lp = BranchLinkProperties()
buo.getShortUrl(with: lp) { (url, error) in
if (error == nil) {
print("Got my Branch link to share: (url)")
} else {
print(String(format: "Branch error : %@", error! as CVarArg))
}
}
BranchUniversalObject *buo = [[BranchUniversalObject alloc] initWithCanonicalIdentifier:@"item/12345"];
BranchLinkProperties *lp = [BranchLinkProperties new];
[buo getShortUrlWithLinkProperties:lp andCallback:^(NSString *url, NSError *error) {
if (!error) {
NSLog(@"got my Branch invite link to share: %@", url);
}
}];
getShortUrlWithLinkPropertiesAndIgnoreFirstClick
This method is part of the BranchUniversalObject : NSObject interface.
Returns a Branch short URL for the specified Branch Universal Object instance and includes the passed Link Properties object.
Ignores the first access of the item (usually due to a robot indexing the item) for statistics.
Argument
Type
Description
linkProperties
BranchLinkProperties
The link properties to include with the Branch short URL.
Example Usage
let buo = BranchUniversalObject(canonicalIdentifier: "item/12345")
let lp = BranchLinkProperties()
buo.getShortUrl(with: lp) { (url, error) in
if (error == nil) {
print("Got my Branch link to share: (url)")
} else {
print(String(format: "Branch error : %@", error! as CVarArg))
}
}
BranchUniversalObject *buo = [[BranchUniversalObject alloc] initWithCanonicalIdentifier:@"item/12345"];
BranchLinkProperties *lp = [BranchLinkProperties new];
[buo getShortUrlWithLinkPropertiesAndIgnoreFirstClick:lp andCallback:^(NSString *url, NSError *error) {
if (!error) {
NSLog(@"got my Branch invite link to share: %@", url);
}
}];
getLongUrlWithChannel
This method is part of the BranchUniversalObject : NSObject interface.
Show the user a Share Sheet and specify the text to display.
Argument
Type
Description
shareText
NSString
The message associated with the shareable Branch Deep Link.
completion
NSString and/or BOOL
The activityType as a string (nullable) and a boolean representing completion state.
Example Usage
let buo = BranchUniversalObject(canonicalIdentifier: "item/12345")
buo.showShareSheet(withShareText: "Share Your Monster!") { (activityType, success) in
if (success) {
print("Log an event here")
}
}
BranchUniversalObject *buo = [[BranchUniversalObject alloc] initWithCanonicalIdentifier:@"item/12345"];
[self.buo
showShareSheetWithShareText:@"Super amazing thing I want to share"
completion:^(NSString *activityType, BOOL completed) {
if (completed) {
NSLog(@"%@", [NSString stringWithFormat:@"Completed sharing to %@", activityType]);
}
}
}];
showShareSheetWithLinkProperties
This method is part of the BranchUniversalObject : NSObject interface.
On iPad, show the user a Share Sheet and specify the text to display as well as the link properties. Include activityError in completion.
Argument
Type
Description
linkProperties
BranchLinkProperties
The Branch Link Properties object to associate with the Branch Link.
shareText
NSString
The message associated with the shareable Branch Deep Link.
viewController
UIViewController
The UIViewController to use to share the Branch Deep Link.
anchor
UIBarButtonItem
For iPads.
completion
NSString and/or NSError BOOL
May contain activityType, activityError, and/or completion status.
Example Usage
let buo = BranchUniversalObject(canonicalIdentifier: "item/12345")
let lp = BranchLinkProperties()
let message = "Check out this link"
buo.showShareSheet(with: lp, andShareText: message, from: self) { (activityType, completed) in
print(activityType ?? "")
}
List content on iOS Spotlight and include a callback.
Argument
Type
Description
callback
NSString or NSError
A callback including either the URL for the content or an error.
Example Usage
let buo = BranchUniversalObject(canonicalIdentifier: "item/12345")
buo.listOnSpotlight { (url, error) in
if let spotlightUrl = url {
print("BUO was listed on spotlight: \(spotlightUrl)")
}
}
BranchUniversalObject *buo = [[BranchUniversalObject alloc] initWithCanonicalIdentifier:@"item/12345"];
// Example 1
[buo listOnSpotlightWithCallback:^(NSString *url, NSError *error) {
if (!error) {
NSLog(@"shortURL: %@", url);
} else {
NSLog(@"error: %@", error);
}
}];
// Example 2
[buo listOnSpotlightWithCallback:^(NSString * _Nullable url, NSError * _Nullable error) {
NSLog(@"BUO was listed on spotlight: %@", url);
}];
listOnSpotlightWithLinkProperties
This method is part of the BranchUniversalObject : NSObject interface.