Filters

iOS Full Reference

Available in CocoaPods

Branch is available through CocoaPods. To install it, simply add the following line to your Podfile:

// iOS SDK 2.0.0+
pod 'BranchSDK'

// iOS SDK <2.0.0
// pod 'Branch'

Then, from the command line, cd to your project directory, and do:

pod install
pod update

to install the Branch pod and update it to the latest version of the SDK.

Make sure to do the pod update. CocoaPods may not use the latest version of the SDK otherwise!

Carthage

To integrate Branch into your project using Carthage add the following to your Cartfile:

github "BranchMetrics/ios-branch-deep-linking"

Download the Raw Files

You can also install by downloading the raw files below.

Adding the Raw Files Branch SDK to Your Project

If you want to add the Branch SDK directly without using Cocoapods or Carthage, add Branch as a dynamic framework dependency to your project.

I'll add Branch to the project 'BareBones' as an example:

  1. Download or git clone the Branch SDK files to your computer.
  2. If you've already added Branch to your project, remove it.
  3. In the Xcode project navigator view, select your project, right-click, and select 'Add files to "<your project name>"...'
904

Add Files...

  1. The 'Add' file chooser will open. Navigate to your 'ios-branch-deep-linking > carthage-files' directory and select the BranchSDK.xcodeproj project.
2086

Add BranchSDK.xcodeproj

Xcode will add BranchSDK.xcodeproj to your project.

  1. In your project, reveal the 'BranchSDK.xcodeproj > Products' hierarchy. Then drag the Branch.framework product to the 'Embedded Binaries' section of your build product.
2086

Embed Binary

  1. Done! You can click on Build Phases of your project to make sure that Branch was added as a Target Dependency and is copied as an Embedded Framework.

Register Your App

You can sign up for your own app id at https://dashboard.branch.io.

Add Your Branch Key to Your Project

After you register your app, your Branch Key can be retrieved on the Settings page of the dashboard. Now you need to add it to YourProject-Info.plist (Info.plist for Swift).

  1. In plist file, mouse hover "Information Property List," which is the root item under the Key column.
  2. After about half a second, you will see a "+" sign appear. Click it.
    3 In the newly added row, fill in "branch_key" for its key, leave type as String, and enter your app's Branch Key obtained in above steps in the value column.
  3. Save the plist file.

Branch Key Demo

If you want to add a key for both your live and test apps at the same time, you need change the type column to Dictionary, and add two entries inside:

  1. For live app, use "live" (without double quotes) for key, String for type, and your live branch key for value.
  2. For test app, use "test" (without double quotes) for key, String for type, and your test branch key for value.

Branch Multi Key Demo

📘

Note

If you used Fabric to install Branch as a kit, your Branch keys will be in your Info.plist as an element under the Fabric > Kits array, as shown below.

Branch Fabric Keys

Register a URI Scheme

Register your app to respond to direct deep links (yourapp:// in a mobile browser) by adding a URI scheme in the YourProject-Info.plist file. Make sure to change yourapp to a unique string that represents your app name.

  1. In Xcode, click on YourProject-Info.plist on the left.
  2. Find URL Types and click the right arrow. (If it doesn't exist, right click anywhere and choose Add Row. Scroll down and choose URL Types).
  3. Add "yourapp," where yourapp is a unique string for your app, as an item in URL Schemes as below.

🚧

Warning

Your apps URI scheme must be the first scheme defined (item 0) in the list

If you have multiple schemes defined, such as a Facebook login URI, make your app's URI scheme the first one in the list so the Branch SDK knows the URI specific to your app.

789

URL Scheme Demo

Alternatively, you can add the URI scheme in your project's Info page.

  1. In Xcode, click your project in the Navigator (on the left side).
  2. Select the "Info" tab.
  3. Expand the "URL Types" section at the bottom.
  4. Click the "+" sign to add a new URI Scheme, as below:
1200

URL Scheme Demo

Support Universal Linking (iOS 9 and Above)

With iOS 9, Apple has added the ability to allow http links to directly open your app, rather than using the URI Schemes. This can be a pain to set up, as it involves a complicated process on your server. The good news is that Branch does this work for you with just two steps!

  1. In Xcode, click on your project in the Navigator (on the left side).
  2. Select the "Capabilities" tab.
  3. Expand the "Associated Domains" tab.
  4. Enable the setting (toggle the switch).
  5. Add applinks:xxxx.app.link and applinks:xxxx-alternate.app.link to the list. Make sure xxxx matches the 4 character subdomain for your app (you can find it on the dashboard here). If you use a custom subdomain, use that in place of the x's (eg imgur.app.link and imgur-alternate.app.link).
  6. Add any additional custom domains you have (e.g. applinks:vng.io)

Xcode Enable UL

  1. On the Dashboard, navigate to your app's link settings page.
  2. Check the "Enable Universal Links
  3. Ensure that your Apple Team ID and app Bundle ID are correct (we try to auto-harvest these for you).
  4. Be sure to save these settings updates.

Dashboard Enable UL

Custom Domain Name Configuration (Required if you don't use the Branch provided xxxx.app.link domain)

Branch provides a xxxx.app.link domain for your app, but you can use your own custom domain for app links instead. If you do use your own custom domain for your universal app links, you need to add it to your Info.plist.

Add the branch_universal_link_domains key with your custom domain as a string value:

Custom Domain Info.plist

URI Scheme Considerations

The Branch SDK will pull the first URI Scheme from your list that is not one of fb, db, or pin. This value will be used one time to set the iOS URI Scheme under your Link Settings in the Branch Dashboard.

For additional help configuring the SDK, including step-by-step instructions, please see the iOS Quickstart Guide.

Get a Singleton Branch Instance

All Branch methods require an instance of the main Branch object. Here's how you can get one. It's stored statically and is accessible from any class.

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

Testing

Test your Branch Integration

Test your Branch Integration by calling validateSDKIntegration in your AppDelegate. 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()
[[Branch getInstance] validateSDKIntegration];

Test Deeplink routing for your Branch links

Append ?bnc_validate=true to any of your app's Branch links and click it on your mobile device (not the Simulator!) to start the test. For instance, to validate a link like: "https://<yourapp\>.app.link/NdJ6nFzRbK" click on: "https://<yourapp\>.app.link/NdJ6nFzRbK?bnc_validate=true"

//TODO: Remove for launch
Branch.setUseTestBranchKey(true)
#warning Remove for launch
[Branch setUseTestBranchKey:YES];

Parameters

Branch key (NSString *) optional:
If you don't store the Branch key in the plist file, you have the option of passing this key as an argument.

Init Branch Session and Deep Link Routing Function

To deep link, Branch must initialize a session to check if the user originated from a link. This call will initialize a new session every time the app opens. 100% of the time the app opens, it will call the deep link handling block to inform you whether the user came from a link. If your app opens with keys in the params, you'll want to route the user depending on the data you passed in. Otherwise, send them to a generic screen.

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 -> was re-directed to this app
        print("params: %@", params.description)
    }
   })
  return true
}

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    // Pass the 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
}

func application(_ application: UIApplication, didReceiveRemoteNotification launchOptions: [AnyHashable: Any]) -> Void {
    Branch.getInstance().handlePushNotification(launchOptions)
}
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    Branch *branch = [Branch getInstance];
    [branch initSessionWithLaunchOptions:launchOptions andRegisterDeepLinkHandler:^(NSDictionary *params, NSError *error) {
        // route the user based on what's in 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;
}

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo {
    [[Branch getInstance] handlePushNotification:userInfo];
}

Note: If your application delegate declares the method:

optional func application(_ application: UIApplication, willFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey : Any]? = nil) -> Bool
- (BOOL) application:willFinishLaunchingWithOptions:

it must return YES for Branch to work.

Parameters

initSession

ParameterDescriptionRequired
launchOptions (NSDictionary *)These launch options are passed to Branch through didFinishLaunchingWithOptions and will notify us if the user originated from a URI call or not. If the app was opened from a URI like myapp://, we need to follow a special initialization routine.Y
deepLinkHandler ^(NSDictionary params, NSError error)This is the callback block that Branch will execute after a network call to determine where the user comes from. It is called 100% of the time the app opens up since Branch registers for lifecycle notifications.

NSDictionary *params : These params will contain any data associated with the Branch link that was clicked before the app session began. There are a few keys which are always present:
- '+isfirst_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

_NSError *error
: This error will be nil unless there is an error such as connectivity or otherwise. Check !error to confirm it was a valid link.
- BNCServerProblemError There was an issue connecting to the Branch service
- BNCBadRequestError The request was improperly formatted
N
isReferrable (BOOL)This boolean lets you control whether or not the user is eligible to be 'referred'. This is applicable for credits and influencer tracking. If isReferrable is set to NO | false, and the user clicks a link before entering the app, deep link parameters will appear, but that user will not be considered referred. If isReferrable is set to YES | true, and the user clicks a link, deep link params will appear and the user will be considered referred. Remove this argument to access the default, which only allows the user to be referred on a fresh install, but not on opens.N
automaticallyDisplayDeepLinkController (BOOL)This boolean lets you control whether or not the Branch should attempt to launch Deep Linked controllers (based on those registered with [branch registerDeepLinkController:forKey:]). The default is NO | false.N

Branch returns explicit parameters every time. Here is a list, and a description of what each represents.

  • ~ denotes analytics
  • + denotes information added by Branch
  • (for the curious, $ denotes reserved keywords used for controlling how the Branch service behaves)
ParameterDescription
~channelThe channel on which the link was shared, specified at link creation time
~featureThe feature, such as invite or share, specified at link creation time
~tagsAny tags, specified at link creation time
~campaignThe campaign the link is associated with, specified at link creation time
~stageThe stage, specified at link creation time
~creation_sourceWhere the 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 link click, if a link was clicked
+phone_numberThe phone number of the user, if the user texted himself/herself 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

ParameterDescriptionRequired
url (NSString *)This argument passes us the URI string so that we can parse the extra parameters. For example, 'myapp://open?link_click_id=12345'.Y

continueUserActivity

ParameterDescriptionRequired
userActivity (NSUserActivity *)This argument passes us the user activity so that we can parse the originating URL.Y

Returns

handleDeepLink

BOOL handleDeepLink will return a boolean indicating whether Branch has handled the URI. If the URI call is 'myapp://open?link_click_id=12345', then handleDeepLink will return YES because the Branch click object is present. If just 'myapp://', handleDeepLink will return NO.

continueUserActivity

BOOL continueUserActivity will return a boolean indicating whether Branch has handled the Universal Link. If Universal Link is powered by Branch, then continueUserActivity will return YES because the Branch click object is present.

If you use your own custom universal link domain, make sure you add it your Info.plist under the branch_universal_link_domains key as described here or this method may erroneously return NO when in fact the universal link will be opened.

Register a Deep Link Controller

Register a controller for Branch to show when specific keys are present in the Branch open / install dictionary. This is the mechanism to handle auto deep linking and should be called before initSession.

Branch.getInstance().registerDeepLinkController(myController forKey:"my-key" withPresentation: .optionShow)
[[Branch getInstance] registerDeepLinkController:myController forKey:@"my-key" withPresentation:BNCViewControllerOptionShow];

Parameters

ParameterDescriptionRequired
controller (UIViewController *)The controller to display when the key is present in the dictionary.Y
key (NSString *)The key checked for in open / install dictionaries.Y
Option (BNCViewControllerPresentationOption)BNCViewControllerOptionShow: This option pushes view controller onto the navigation stack in a similar way as the showViewController

BNCViewControllerOptionPush: This option pushes view controller onto the navigation stack in a similar way as the pushViewController

BNCViewControllerOptionPresent : This option presents view controller onto the root view controller of window in a similar way as the presentViewController
Y

Retrieve session (install or open) parameters

These session parameters will be available at any point later on with this command. If no parameters are available then Branch will return an empty dictionary. This refreshes with every new session (app installs AND app opens).

🚧

Warning

If the Branch SDK is retrieving the latest session parameters via a network call, this method will return the previous session's parameters. The best practice is to set a callback deep link handler at Branch initialization. That handler will be called when a Branch deep link is handled, and the most recent session parameters are available.

Otherwise, use the getLatestReferringParamsSynchronous method. This method always returns the latest session parameters. The downside is that it may block the calling thread until the current results are available.

// This is an example of `getLatestReferringParams`.
// Warning: It may return the previous results.
let sessionParams = Branch.getInstance().getLatestReferringParams()

// This is an example of `getLatestReferringParamsSynchronous`.
// Warning: It may block the current thread until the latest results are available.
let sessionParams = Branch.getInstance().getLatestReferringParamsSynchronous()
// This is an example of `getLatestReferringParams`.
// Warning: It may return the previous results.
NSDictionary *sessionParams = [[Branch getInstance] getLatestReferringParams];

// This is an example of `getLatestReferringParamsSynchronous`.
// Warning: It may block the current thread until the latest results are available.
NSDictionary *sessionParams = [[Branch getInstance] getLatestReferringParamsSynchronous];

Returns

NSDictionary*

When initSession returns a parameter set in the deep link callback, we store it in NSUserDefaults for the duration of the session in case you want to retrieve it later. Careful, once the app is minimized and the session ends, this will be cleared.

Retrieve Install (Install Only) Parameters

If you ever want to access the original session params (the parameters passed in for the first install event only), you can use this line. This is useful if you only want to reward users who newly installed the app from a referral link. Note that these parameters can be updated when setIdentity: is called and identity merging occurs.

let installParams = Branch.getInstance().getFirstReferringParams() // previously getInstallReferringParams
NSDictionary *installParams = [[Branch getInstance] getFirstReferringParams]; // previously getInstallReferringParams

Persistent Identities

Often, you might have your own user IDs, or want referral and event data to persist across platforms or uninstall/reinstall. It's helpful if you know your users access your service from different devices. This is where we introduce the concept of an 'identity'.

To identify a user, just call:

// previously identifyUser:
Branch.getInstance().setIdentity(your user id)  // your user id should not exceed 127 characters
// previously identifyUser:
[[Branch getInstance] setIdentity:your user id];    // your user id should not exceed 127 characters

Parameters

ParameterDescriptionRequired
identity (NSString *)This is the alias you'd like to label your user in the Branch system. Note that we only support a single alias per user.Y

Logout

If you provide a logout function in your app, be sure to clear the user when the logout completes. This will ensure that all the stored parameters get cleared, and all events are properly attributed to the right identity.

🚧

Warning

This call will clear the promo credits and attribution on the device.

Branch.getInstance().logout()   // previously clearUser
[[Branch getInstance] logout];  // previously clearUser

Tracking User Actions and Events

Use the BranchEvent interface to track special user actions or application specific events beyond app installs, opens, and sharing. You can track events such as when a user adds an item to an on-line shopping cart, or searches for a keyword, among others.

The BranchEvent interface provides an interface to add contents represented by BranchUniversalObject in order to associate app contents with events.

Analytics about your app's BranchEvents can be found on the Branch dashboard, and BranchEvents also provide tight integration with many third party analytics providers.

The BranchEvent class can be simple to use. For example:

BranchEvent.standardEvent(.addToCart).logEvent()
[[Branch getInstance] logout];  // previously clearUser

For best results, use the Branch standard event names defined in BranchEvent.h. But you can use your own custom event names too:

BranchEvent.customEventWithName("User_Scanned_Item").logEvent()
[[BranchEvent customEventWithName:@"User_Scanned_Item"] logEvent];

Extra event specific data can be tracked with the event as well:

let event = BranchEvent.standardEvent(.purchase)
event.transactionID    = "tx-12344555"
event.currency         = .USD
event.revenue          = 12.70
event.shipping         = 10.20
event.tax              = 2.50
event.coupon           = "coupon_code"
event.affiliation      = "store_affiliation"
event.eventDescription = "Shopper made a purchase."
event.searchQuery      = "Fashion Scarf"
event.contentItems     = [ branchUniversalObject ]
event.customData       = [
    "Item_Color": "Red",
    "Item_Size":  "Large"
]
event.logEvent()
BranchEvent *event    = [BranchEvent standardEvent:BranchStandardEventPurchase];
event.transactionID   = @"tx-12344555";
event.currency        = BNCCurrencyUSD;
event.revenue         = [NSDecimalNumber decimalNumberWithString:@"12.70"];
event.shipping        = [NSDecimalNumber decimalNumberWithString:@"10.20"];
event.tax             = [NSDecimalNumber decimalNumberWithString:@"2.50"];
event.coupon          = @"coupon_code";
event.affiliation     = @"store_affiliation";
event.eventDescription= @"Shopper made a purchase.";
event.searchQuery     = @"Fashion Scarf";
event.contentItems    = @[ branchUniversalObject ];
event.customData      = (NSMutableDictionary*) @{
    @"Item_Color": @"Red",
    @"Item_Size":  @"Large"
};
[event logEvent];

Apple Search Ads

Branch can help track your Apple Search Ad campaigns by fetching the search ad attribution from
Apple at app install. You can then use the parameters you've set in the Apple Search Ad dashboard,
parameters such as the campaign name, and take special action in you app after an install, or simply
track the effectiveness of a campaign in the Branch dashboard, along with other your other Branch
statistics, such as total installs, referrals, and app link statistics.

- (void) delayInitToCheckForSearchAds

Call this method to enable checking for Apple Search Ads before Branch initialization. This method
must be called before you initialize your Branch session.

More information on this can be referenced in the Apple Search Ads docs.

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

Enable or Disable User Tracking

In order to comply with tracking requirements, you can disable tracking at the SDK level. Simply call:

Branch.setTrackingDisabled(true)
[Branch setTrackingDisabled:YES];

This will prevent any Branch network requests from being sent, except when deep linking. If someone clicks a Branch link, but does not want to be tracked, we will return the deep linking data back to the app but without capturing any tracking information.

In do-not-track mode, you will still be able to create & share links. The links will not have identifiable information and will be long format links. Event tracking won’t pass data back to the server if a user has expressed to not be tracked. You can change this behavior at any time by calling the above function. The trackingDisabled state is saved and persisted across app runs.

Branch Universal Object (for deep links, content analytics and indexing)

As more methods have evolved in iOS, we've found that it was increasingly hard to manage them all. We abstracted as many as we could into the concept of a Branch Universal Object. This is the object that is associated with the thing you want to share (content or user). You can set all the metadata associated with the object and then call action methods on it to get a link or index in Spotlight.

Branch Universal Object best practices

Here are a set of best practices to ensure that your analytics are correct, and your content is ranking on Spotlight effectively.

  1. Set the canonicalIdentifier to a unique, de-duped value across instances of the app
  2. Ensure that the title, contentDescription and imageUrl properly represent the object
  3. Call showShareSheet and createShortLink later in the life cycle, when the user takes an action that needs a link
  4. Call the additional object events (purchase, share completed, etc) when the corresponding user action is taken
  5. Set the contentIndexMode to ContentIndexModePublic or ContentIndexModePrivate. If BranchUniversalObject is set to ContentIndexModePublic, then content would indexed using NSUserActivity, or else content would be index using CSSearchableIndex on Spotlight.

📘

Note

Content indexed using CSSearchableItem could be removed from Spotlight but cannot be removed if indexed using NSUserActivity.

Practices to avoid:

  1. Don't set the same title, contentDescription and imageUrl across all objects.
  2. Don't wait to initialize the object and register views until the user goes to share.
  3. Don't wait to initialize the object until you conveniently need a link.
  4. Don't create many objects at once and register views in a for loop.

Branch Universal Object

Methods and Properties

let branchUniversalObject: BranchUniversalObject = BranchUniversalObject(canonicalIdentifier: "item/12345")
branchUniversalObject.title = "My Content Title"
branchUniversalObject.contentDescription = "My Content Description"
branchUniversalObject.imageUrl = "https://example.com/mycontent-12345.png"
branchUniversalObject.contentMetadata.contentSchema = .product;
branchUniversalObject.contentMetadata.customMetadata["property1"] = "blue"
branchUniversalObject.contentMetadata.customMetadata["property2"] = "red"
#import "BranchUniversalObject.h"

  
  
BranchUniversalObject *branchUniversalObject = [[BranchUniversalObject alloc] initWithCanonicalIdentifier:@"item/12345"];
branchUniversalObject.title = @"My Content Title";
branchUniversalObject.contentDescription = @"My Content Description";
branchUniversalObject.imageUrl = @"https://example.com/mycontent-12345.png";
branchUniversalObject.contentMetadata.contentSchema = BranchContentSchemaCommerceProduct;
branchUniversalObject.contentMetadata.customMetadata[@"property1"] = @"blue";
branchUniversalObject.contentMetadata.customMetadata[@"property2"] = @"red";

Properties

PropertyDescription
canonicalIdentifierThis is the unique identifier for content that will help Branch de-dupe across many instances of the same thing. If you have a website with pathing, feel free to use that. Or, if you have database identifiers for entities, use those.
titleThis is the name for the content and will automatically be used for the OG tags. It will insert $og_title into the data dictionary of any link created.
contentDescriptionThis is the description for the content and will automatically be used for the OG tags. It will insert $og_description into the data dictionary of any link created.
imageUrlThis is the image URL for the content and will automatically be used for the OG tags. It will insert $og_image_url into the data dictionary of any link created.
keywordsKey words that describe the object. These are used for Spotlight search and web scraping so that users can find your content.
locallyIndexIf set to true, Branch will index this content on Spotlight on the user's phone.
publiclyIndexIf set to true, Branch will index this content on Google, Branch, etc.
expirationDateThe date when the content will not longer be available or valid. Currently, this is only used for Spotlight indexing but will be used by Branch in the future.
contentMetadataDetails that further describe your content. Set the properties of this sub-object depending on the type of content that is relevant to your content. See the Metadata Property table below for further information.

BranchUniversalObject.contentMetadata

The BranchUniversalObject.contentMetadata properties further describe your content. These properties are trackable in the Branch dashboard and will be automatically exported to your connected third-party app intelligence partners like Adjust or Mixpanel.

Set the properties of this sub-object depending on the type of content that is relevant to your content. The BranchUniversalObject.contentMetadata.contentSchema property describes the type of object content. Set other properties as is relevant to the type.

Metadata PropertyDescription
contentMetadata.contentSchemaSet this property to a BranchContentSchema enum that best describes the content type. It accepts values likeBranchContentSchemaCommerceProduct and BranchContentSchemaMediaImage.
contentMetadata.customMetadataThis dictionary contains any extra parameters you'd like to associate with the Branch Universal Object. These will be made available to you after the user clicks the link and opens up the app.
contentMetadata.priceThe price of the item to be used in conjunction with the commerce related events below.
contentMetadata.currencyThe currency representing the price in ISO 4217 currency code. The default is USD.
contentMetadata.quantityThe quantity.
contentMetadata.skuThe vendor SKU.
contentMetadata.productNameProduct name.
contentMetadata.productBrandProduct brand.
contentMetadata.productCategoryThe BNCProductCategory value, such as BNCProductCategoryAnimalSupplies or BNCProductCategoryFurniture.
contentMetadata.productVariantThe product variant.
contentMetadata.conditionThe BranchCondition value, such as BranchConditionNew or BranchConditionRefurbished.
ratingAverage, ratingCount, ratingMaxThe rating for your content.
addressStreet, addressCity, addressRegion, addressCountry, addressPostalCodeThe address of your content.
latitude, longitudeThe longitude and latitude of your content.
imageCaptionsImage captions for the content's images.

Shortened Links

Once you've created your Branch Universal Object, which is the reference to the content you're interested in, you can then get a link back to it with the mechanisms described below.

Encoding Note

One quick note about encoding. Since NSJSONSerialization supports a limited set of classes, we do some custom encoding to allow additional types. Current supported types include NSDictionary, NSArray, NSURL, NSString, NSNumber, NSNull, and NSDate (encoded as an ISO8601 string with timezone). If a parameter is of an unknown type, it will be ignored.

let linkProperties: BranchLinkProperties = BranchLinkProperties()
linkProperties.feature = "sharing"
linkProperties.channel = "facebook"
linkProperties.addControlParam("$desktop_url", withValue: "http://example.com/home")
linkProperties.addControlParam("$ios_url", withValue: "http://example.com/ios")



branchUniversalObject.getShortUrl(with: linkProperties) { (url, error) in
    if error == nil {
        NSLog("got my Branch link to share: %@", url)
    }
}
#import "BranchLinkProperties.h"
  
  
 BranchLinkProperties *linkProperties = [[BranchLinkProperties alloc] init];
linkProperties.feature = @"sharing";
linkProperties.channel = @"facebook";
[linkProperties addControlParam:@"$desktop_url" withValue:@"http://example.com/home"];
[linkProperties addControlParam:@"$ios_url" withValue:@"http://example.com/ios"];


[branchUniversalObject getShortUrlWithLinkProperties:linkProperties andCallback:^(NSString *url, NSError *error) {
    if (!error) {
        NSLog(@"success getting url! %@", url);
    }
}];

Link Properties Parameters

ParameterDescription
channelThe channel for the link. Examples could be Facebook, Twitter, SMS, etc., depending on where it will be shared.
featureThe feature the generated link will be associated with. Eg. sharing.
aliasThe alias for a link. Eg. myapp.com/customalias
matchDurationThe attribution window in seconds for clicks coming from this link.
stageThe stage used for the generated link, indicating what part of a funnel the user is in.
tagsAn array of tag strings to be associated with the link.
controlParamsA dictionary to use while building up the Branch link. Here is where you specify custom behavior controls as described in the table below.

You can do custom redirection by inserting the following optional keys in the dictionary:

KeyValue
"$fallback_url"Where to send the user for all platforms when app is not installed. Note that Branch will forward all robots to this URL, overriding any OG tags entered in the link.
"$desktop_url"Where to send the user on a desktop or laptop. By default it is the Branch-hosted text-me service.
"$android_url"The replacement URL for the Play Store to send the user if they don't have the app. Only necessary if you want a mobile web splash.
"$ios_url"The replacement URL for the App Store to send the user if they don't have the app. Only necessary if you want a mobile web splash.
"$ipad_url"Same as above, but for iPad Store.
"$fire_url"Same as above, but for Amazon Fire Store.
"$blackberry_url"Same as above, but for Blackberry Store.
"$windows_phone_url"Same as above, but for Windows Store.
"$after_click_url"When a user returns to the browser after going to the app, take them to this URL. iOS only; Android coming soon.

You have the ability to control the direct deep linking of each link by inserting the following optional keys in the dictionary:

KeyValue
"$deeplink_path"The value of the deep link path that you'd like us to append to your URI. For example, you could specify "$deeplink_path": "radio/station/456" and we'll open the app with the URI "yourapp://radio/station/456?link_click_id=branch-identifier". This is primarily for supporting legacy deep linking infrastructure.
"$always_deeplink"true or false. (default is not to deep link first) This key can be specified to have our linking service force try to open the app, even if we're not sure the user has the app installed. If the app is not installed, we fall back to the respective app store or $platform_url key. By default, we only open the app if we've seen a user initiate a session in your app from a Branch link (has been cookied and deep linked by Branch).

Get Short Url Parameters

ParameterDescription
linkPropertiesThe link properties created above that describe the type of link you'd like
callbackThe callback that is called with url on success, or an error if something went wrong. Note that we'll return a link 100% of the time. Either a short one if network was available or a long one if it was not.

UIActivityView Share Sheet

UIActivityView is the standard way of allowing users to share content from your app. Once you've created your Branch Universal Object, which is the reference to the content you're interested in, you can then automatically share it without having to create a link using the mechanism below.

Sample UIActivityView Share Sheet

307

UIActivityView Share Sheet

The Branch iOS SDK includes a wrapper on the UIActivityViewController, that will generate a Branch short URL and automatically tag it with the channel the user selects (Facebook, Twitter, etc.). Note that certain channels restrict access to certain fields. For example, Facebook prohibits you from pre-populating a message.

let linkProperties: BranchLinkProperties = BranchLinkProperties()
linkProperties.feature = "sharing"
linkProperties.addControlParam("$desktop_url", withValue: "http://example.com/home")
linkProperties.addControlParam("$ios_url", withValue: "http://example.com/ios")


branchUniversalObject.showShareSheet(with: linkProperties,
                                     andShareText: "Super amazing thing I want to share!",
                                     from: self) { (activityType, completed) in
    NSLog("done showing share sheet!")
}
#import "BranchLinkProperties.h"
  
  
BranchLinkProperties *linkProperties = [[BranchLinkProperties alloc] init];
linkProperties.feature = @"sharing";
[linkProperties addControlParam:@"$desktop_url" withValue:@"http://example.com/home"];
[linkProperties addControlParam:@"$ios_url" withValue:@"http://example.com/ios"];


[branchUniversalObject showShareSheetWithLinkProperties:linkProperties
                                           andShareText:@"Super amazing thing I want to share!"
                                     fromViewController:self
                                             completion:^(NSString *activityType, BOOL completed){
    NSLog(@"finished presenting");
}];

Show Share Sheet Parameters

ParameterDescription
linkPropertiesThe feature the generated link will be associated with.
andShareTextA dictionary to use while building up the Branch link.
fromViewController
completion

Further Customization

The majority of share options only include one string of text, except email, which has a subject and a body. The share text will fill in the body and you can specify the email subject in the link properties as shown below.

linkProperties.addControlParam("$email_subject", withValue: "Therapists hate him.")
[linkProperties addControlParam:@"$email_subject" withValue:@"This one weird trick."];

You can also optionally add HTML to the email option and customize the link text. If the link text is left out, the url itself is used

linkProperties.addControlParam("$email_html_header", withValue: "<style>your awesome CSS</style>\nOr Dear Friend,")
linkProperties.addControlParam("$email_html_footer", withValue: "Thanks!")
linkProperties.addControlParam("$email_html_link_text", withValue: "Tap here")
[linkProperties addControlParam:@"$email_html_header" withValue:@"<style>your awesome CSS</style>\nOr Dear Friend,"];
[linkProperties addControlParam:@"$email_html_footer" withValue:@"Thanks!"];
[linkProperties addControlParam:@"$email_html_link_text" withValue:@"Tap here"];

Changing share text on the fly

You can change the link shareText and other link parameters based on the choice the user makes on the sharesheet activity. First, set the BranchShareLink delegate with an object that follows the BranchShareLinkDelegate protocol.

The optional - (void) branchShareLinkWillShare: delegate method will be called just after the user selects a share action, like share by email for instance, and before the share action is shown to the user, like when the email composer is shown to the user with the share text. This is an ideal time to change the share text based on the user action.

The optional - (void) branchShareLink:didComplete:withError: delegate method will be called after the user has completed the share action. The didComplete boolean will be YES if the user shared the item, and NO if the user cancelled. The error value will indicate any errors that may have occurred.

Override the branchShareLinkWillShare function to change your shareText

class ViewController: UITableViewController, BranchShareLinkDelegate

func branchShareLinkWillShare(_ shareLink: BranchShareLink) {
    // Link properties, such as alias or channel can be overridden here based on the users'
    // choice stored in shareSheet.activityType.
    shareLink.shareText =
        "Shared through '\(shareLink.linkProperties.channel!)'\nfrom Branch's TestBed-Swift" +
        "\nat \(self.dateFormatter().string(from: Date()))."
}
@interface ViewController () <BranchShareLinkDelegate>
  

- (void) branchShareLinkWillShare:(BranchShareLink*)shareLink {
    // Link properties, such as alias or channel can be overridden here based on the users'
    // choice stored in shareSheet.activityType.
    shareLink.shareText = [NSString stringWithFormat:
        @"Shared through '%@'\nfrom Branch's Branch-TestBed\nat %@.",
        shareLink.linkProperties.channel,
        [self.dateFormatter stringFromDate:[NSDate date]]];
}

List Content On Spotlight

If you'd like to list your Branch Universal Object in Spotlight local and cloud index, this is the method you'll call. You'll want to register views every time the page loads as this contributes to your global ranking in search.

branchUniversalObject.automaticallyListOnSpotlight = true
branchUniversalObject.automaticallyListOnSpotlight = YES;
[branchUniversalObject userCompletedAction:BranchStandardEventViewItem];

Parameters

ParameterDescription
callbackWill return the URL that was used to list the content in Spotlight if you'd like to store it for your own records.

List Content On Spotlight with Link properties

If you'd like to list your Branch Universal Object with link properties in Spotlight local and cloud index, this is the method you'll call. You'll want to register views every time the page loads as this contributes to your global ranking in search.

universalObject.listOnSpotlight(with: linkProperty) { (url, error) in
    if (error == nil) {
        print("Successfully indexed on spotlight")
    }
}
[universalObject listOnSpotlightWithLinkProperties:linkProperties callback:^(NSString * _Nullable url, NSError * _Nullable error) {
    if (!error) {
         NSLog(@"Successfully indexed on spotlight");
    }
}];

Parameters

ParametersDescription
callbackWill return the URL that was used to list the content in Spotlight if you'd like to store it for your own records.

List Multiple Branch Universal Objects On Spotlight using CSSearchableIndex

Call this method on the Branch shared instance to list multiple Branch Universal Objects in Spotlight:

Branch.getInstance().indexOnSpotlight(usingSearchableItems: universalObjects,
                                                completion: { (universalObjects, error) in
      if (error) {
           // Successfully able to index all the BUO on spotloght
      }
})
[[Branch getInstance] indexOnSpotlightUsingSearchableItems:universalObjects
                                                    completion:^(NSArray<BranchUniversalObject *> *universalObjects,
                                                                 NSError *error) {
        if (!error) {
            // Successfully able to index all the BUO on spotloght
        }
    }];

Parameters

ParameterDescription
universalObjectsAn array of all the Branch Universal Object that would indexed using CSSearchableIdex
completionWill return Branch Universal Object with dynamic urls as Spotlight identifier when indexing completes.

Remove Branch Universal Object from Spotlight if privately indexed

Privately indexed Branch Universal Object can be removed from spotlight

universalObject.removeFromSpotlight { (error) in
    if(error == nil) {
    print("BUO successfully removed")
  }
 }
[universalObject removeFromSpotlightWithCallback:^(NSError * _Nullable error) {
        if (!error) {
            NSLog(@"universal Object removed from spotlight");
        }
    }];

Parameters

ParameterDescription
CallbackWill return once Branch Universal Object is removed from spotlight. If spotlight is removed, the spotlightIdentifier variable of Branch Universal Object would be nil.

Remove multiple Branch Universal Objects from Spotlight if privately indexed

Privately indexed multiple Branch Universal Objects can be removed from spotlight

Branch.getInstance().removeSearchableItems(with: [BUO1,BUO2]) { (error) in
    if (error == nil) {
        print("An array of BUOs removed from spotlight")
    }
}
[[Branch getInstance] removeSearchableItemsWithBranchUniversalObjects:@[BUO1,BUO2] callback:^(NSError *error) {
    if (!error) {
        NSLog(@"An array of BUOs removed from spotlight");
    }
}]

Parameters

ParameterDescription
CallbackWill return once all Branch Universal Object is removed from spotlight. If spotlight is removed, the spotlightIdentifier variable of all Branch Universal Object would be nil.

Remove all Branch Universal Objects from Spotlight if privately indexed

All Privately indexed Branch Universal Objects can be removed from spotlight

Branch.getInstance().removeAllPrivateContentFromSpotLight { (error) in
    if (error == nil) {
        print("All branch privately indexed content removed from spotlight")
    }
}
[[Branch getInstance] removeAllPrivateContentFromSpotLightWithCallback:^(NSError *error) {
    if (!error) {
      NSLog(@"All branch privately indexed content removed from spotlight");
    }
}];

Parameters

ParameterDescription
CallbackWill return once all Branch Universal Object is removed from spotlight.
Note: SpotlightIdentifer would not be nil of all the Branch Universal Object been removed from spotlight as Branch SDK doesn't cache the Branch Universal Objects.