Branch Universal Object
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
- This guide requires you to have already integrated the Branch SDK into your app.
Here are a set of best practices to ensure that your analytics are correct, and your content is ranking in search effectively.
- Set the
canonicalIdentifierto a unique, de-duped value across instances of the app
- Ensure that the
imageUrlproperly represent the object
- Initialize the Branch Universal Object and call
userCompletedActionwith the corresponding platform view event on page load
getShortUrllater in the life cycle, when the user takes an action that needs a link
- Call the additional object events (purchase, share completed, etc) when the corresponding user action is taken
Practices to avoid:
- Don’t set the same
imageUrlacross all objects
- Don’t wait to initialize the object and register views until the user goes to share
- Don’t wait to initialize the object until you conveniently need a link
- Don’t create many objects at once and register views in a
You build a
BranchUniversalObject by assembling parameters. After the parameters are assembled, you can create a link by referencing the
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 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.
|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
|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.
Please do not call
registerView anymore. Instead, call this method in
viewDidAppear to track how many times a piece of content is viewed.
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.
|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|
Create a link to a piece of content. Visit the Creating Links in Apps page to learn more.
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.
To implement it, use the following
showShareSheetWithLinkProperties method on your
List your piece of content on Spotlight. Visit the iOS Spotlight Indexing page to learn more.