Branch Universal Object


A BranchUniversalObject is a container that Branch uses to organize and track pieces of content within your app. As a single, self-contained object associated with each thing that you want to share, it provides convenient methods for sharing, deep linking, and tracking how often that thing is viewed.

Prerequisite: Complete the SDK Integration Guide first

linkBest Practices for using Branch Universal Object

Here are a set of best practices to ensure that your analytics are correct, and your content is ranking in search 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. Initialize the Branch Universal Object and call userCompletedAction with the corresponding platform view event on page load
  4. Call showShareSheet and getShortUrl later in the life cycle, when the user takes an action that needs a link
  5. Call the additional object events (purchase, share completed, etc) when the corresponding user action is taken

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.

linkDefining a Branch Universal Object

You build a BranchUniversalObject by assembling parameters. After the parameters are assembled, you can create a link by referencing the BranchUniversalObject.

BranchUniversalObject *branchUniversalObject = [[BranchUniversalObject alloc] initWithCanonicalIdentifier:@"item/12345"];
branchUniversalObject.title = @"My Content Title";
branchUniversalObject.contentDescription = @"My Content Description";
branchUniversalObject.imageUrl = @"";
[branchUniversalObject addMetadataKey:@"property1" value:@"blue"];
[branchUniversalObject addMetadataKey:@"property2" value:@"red"];


Some of these parameters automatically populate the link parameters of any link created from that BranchUniversalObject. Specifying via BranchUniversalObject is preferred.

Parameter Usage Link Parameter
canonicalIdentifier This is the unique identifier for content that will help Branch dedupe across many instances of the same thing. Suitable options: a website with pathing, or a database with identifiers for entities $canonical_identifier
canonicalUrl The canonical URL, used for SEO purposes  
title The name for the piece of content $og_title
contentDescription A description for the content $og_description
imageUrl The image URL for the content $og_image_url
metadata 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, and are used for Deep Link Routing.  
price The price of the item  
currency The currency representing the price in ISO 4217 currency code. Default is USD.  
contentIndexMode Can be set to either ContentIndexModePublic or ContentIndexModePrivate. Public indicates that you’d like this content to be discovered by other apps* $publicly_indexable
expirationDate The date when the content will not longer be available or valid* $exp_date

Currently, this parameter is only used for iOS Spotlight Indexing but will be used by Branch in the future


After you’ve assembled parameters to create your BranchUniversalObject, there are a number of methods you can call on it.

linkRegister a content view

Please do not call registerView anymore. Instead, call this method in viewDidLoad or viewDidAppear to track how many times a piece of content is viewed.

[branchUniversalObject userCompletedAction:BNCRegisterViewEvent];


We’ve added a series of custom events that you’ll want to start tracking for rich analytics and targeting. Here’s a list below with a sample snippet that calls the register view event.

Key Value
BNCRegisterViewEvent User viewed the object
BNCAddToWishlistEvent User added the object to their wishlist
BNCAddToCartEvent User added object to cart
BNCPurchaseInitiatedEvent User started to check out
BNCPurchasedEvent User purchased the item
BNCShareInitiatedEvent User started to share the object
BNCShareCompletedEvent User completed a share
[branchUniversalObject userCompletedAction:BNCRegisterViewEvent];


Create a link to a piece of content. Visit the Creating Links in Apps page to learn more.

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


Use Branch’s preconfigured UIActivityItemProvider to share a piece of content without having to create a link. Calling this method will automatically generate a Branch link with the appropriate analytics channel when the user selects a sharing destination. Note that certain channels restrict access to certain fields. For example, Facebook prohibits you from pre-populating a message.

ios share sheet

To implement it, use the following showShareSheetWithLinkProperties method on your branchUniversalObject

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


List your piece of content on Spotlight. Visit the iOS Spotlight Indexing page to learn more.

branchUniversalObject.automaticallyListOnSpotlight = YES;
[branchUniversalObject userCompletedAction:BNCRegisterViewEvent];