The BUO is used to tell Branch about a piece of content within your application, whether it’s a pair of shoes for sale, a hotel room in Prague, a recipe for veal picatta, or tonight’s Earthquakes game. Branch uses the BUO to send data from one user who wants to share a piece of content within your app to another users who wants to view it.

The BUO isn’t just limited to your app. Branch also provides tools to get the same context from your desktop or mobile web pages and use that context to drive your users to your mobile app.

When set up properly, in your Branch dashboard you’ll be able to see exactly which content is being viewed most frequently, how often links to that content are being shared, and how well those links perform at driving users to install or re-open your app.

How to Use It

At a high level, this is how the BUO works:

1. When your user navigates to view a piece of content, you create a BUO.
2. You provide some detail about the content within the BUO.
3. We pack that BUO into a link and share it somewhere.
4. The receiving user clicks the link, opens the app, and receives the BUO upon initializing a Branch session.
5. The app then uses those details to route to the appropriate part of your app to display the desired content.

The data on the BUO is represented as a dictionary of key/value pairs. You’re able to pack in any sort of data you want into the BUO, but Branch has pre-defined a number of useful variables on the BUO. In your log files, you can see these keys all start with a dollar sign. You can see a full list of all of the pre-defined configuration keys here.

One of the things that is important to both Branch and your app is how you identify your content. Your app likely has a lot of content, and you’ll want to give each piece of content an ID that Branch can use to uniquely identify it. This is different than the title of your content. You can use your content’s title as its identifier, but if two pieces of content can have the same title, you should use a different approach, such as a UUID, the url to of the item on your web site, or some other name which uniquely identifies it. This is known as the “canonical identifier” of the content, and Branch automatically deduplicates these values on the back end to help keep your analytics data clean. Here is an example of how to specify the canonical identifier using the Branch SDKs.

iOS – Objective-C

buo = [[BranchUniversalObject alloc] initWithCanonicalIdentifier: @"item/1234"];

Android

buo = new BranchUniversalObject().setCanonicalIdentifier("item/1234");

An example of how you use this data is to determine routing logic. Say your app is a food app, and as content, it has recipes, menus, and chefs. You want to create a BUO for a recipe for Veal Piccata. So you define the key “recipeId” to tell you that this BUO represents a recipe. The way you’ve identified this particular recipe within your own system is with the name “Veal-Piccata-440885.” So you assign that as the value for the key “recipeId” on the BUO.

Then, when your app receives the BUO data, it sees the recipeId key and knows to route to the recipe viewing page within your app. That page will then pull out the actual ID and display it accordingly.

The same function will work for your menus and chefs, provided those types of content use their own key. The Branch Android and iOS SDKs actually provide you a way to associate a specific ViewController or Activity with a given key, and will handle the routing automatically! (Documentation)

We’ll talk a little more about other uses for data in a bit.

Social Media and the BUO

You’ll also probably want to share your content over social networks, and it would be nice to be able to customize how it would appear. To do that, you’ll need to set some Open Graph (or OG) and Twitter Cards data on the BUO. Open Graph is how most social networks determine what to display when a link is shared. Twitter Cards are the Twitter-specific equivalent.

Every BUO has its own title, imageUrl, and contentDescription, which in turn map to their respective OG and Twitter Card tags in Branch.

iOS – Objective-C

buo.title = @"My Content Title";
buo.contentDescription = @"My Content Description";
buo.imageUrl = @"https://example.com/mycontent-12345.png";

Android

buo.setTitle("My Content Title");
buo.setContentDescription("My Content Description")
buo.setContentImageUrl("https://example.com/mycontent-12345.png")

Let’s use a news article as an example. In this case, you might set the image to something relevant to the article – or maybe your company logo, if the article doesn’t have pictures. The title would be the headline of the article, and the description might be a brief synopsis of the article. Then, whenever and wherever you share that content on social media, viewers will get a nice preview of the content being linked to.

Sharing the BUO

With the identifying parameter and social media information, the BUO is now ready to be shared. But we still need more information in order to pack it into a Branch link. We’ll need information like the channel that it’s being shared through. Maybe you want a customized address for the link. Or maybe this particular link should fall back to the web page instead of the app store if the user doesn’t have your app installed. All of this information is contained within the LinkProperties object.

iOS – Objective-C

BranchLinkProperties *linkProperties = [[BranchLinkProperties alloc] init];
linkProperties.feature = @"sharing";
linkProperties.channel = @"facebook";
[linkProperties addControlParam:@"$desktop_url" withValue:@"https://example.com/home"];

Android

LinkProperties linkProperties = new LinkProperties()
              .setChannel("facebook")
              .setFeature("sharing")
              .addControlParameter("$desktop_url", "https://example.com/home");

Both a BUO and a LinkProperties are required to generate a link, and each combination of the two will form a unique Branch link.

There are two methods on the BUO that can be used to generate links.

Method 1 – showShareSheet (Recommended)

This method will present the user with a native share sheet with options for sharing the link, including email, sms, and social media platforms.

The benefit of this method is that the Branch SDK will automatically set the channel of the link based on the user’s selection (e.g. if the user selects to share the link via Facebook, the channel will be set to “Facebook”).

iOS – Objective-C

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

Android

branchUniversalObject.showShareSheet(this, linkProperties, shareSheetStyle, new Branch.BranchLinkShareListener() {
   @Override
   public void onShareLinkDialogLaunched() {
   }
   @Override
   public void onShareLinkDialogDismissed() {
   }
   @Override
   public void onLinkShareResponse(String sharedLink, String sharedChannel, BranchError error) {
   }
   @Override
   public void onChannelSelected(String channelName) {
   }
});

Method 2: createShortUrl

This method will return a Branch link for you to share or store for later. This can be useful if you already have a sharing mechanism (i.e. a share sheet) built into your app, or if you want to pre-generate links (for example, if you want to create “Invite” links for new users when they register) that are meant to be stored and shared later.

The main difference from the showShareSheet method is that with this method you will need to manually set the channel that the link is being shared through in the LinkProperties object. If you leave it blank, the channel will appear as “Unspecified” in your dashboard analytics.

iOS – Objective-C

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

Android

buo.generateShortUrl(this, linkProperties, new BranchLinkCreateListener() {
   @Override
   public void onLinkCreate(String url, BranchError error) {
       if (error == null) {
           Log.i("MyApp", "got my Branch link to share: " + url);
       }
   }
});

Custom Onboarding with the BUO

You’re not limited to just Open Graph data and identifying parameters on the BUO. We give you the flexibility to define any key/value pairs you want. When creating a BUO and generating a link, you could also pack in some additional information about the user who is creating the link. You can even pack in this data without linking directly to a piece of content. A BUO set up like this is no longer associated with any of your specific content (aside from the referring user). And that’s okay! Because the BUO is infinitely flexible in what data you store on it, it can be used for any number of purposes.

Then, when a new user installs the app from that link, that data can be used to provide them a personalized onboarding experience.

Best Practices

To get the most value out of the BUO, there are a few guidelines you should follow. (Note that these practices are intended for content-specific BUOs).

Create the BUO when the Page Opens

You want to create the BUO as soon as the page loads rather than later. This will allow you to register events on the BUO as soon as the user performs some action (e.g. sharing, adding to cart, etc.).

Set All of the Identifying Information

Be sure to set the canonical identifier, the Open Graph image/title/description, and any fallback URLs that you need.

Protip: If your content is on the web, set the $fallback_url to the web page of the content. We’ll automatically visit that page and scrape all of the relevant Open Graph data when we create the link, so you won’t have to do it manually!

Set the Canonical URL

If your content lives both on the web and in the app, make sure you set its canonical URL (i.e. the URL of this piece of content on the web) when building any BUO. By doing so, we’ll attribute clicks on the links that you generate back to their original web page, even if the user goes to the app instead of your website! This will help your SEO efforts.

Register Actions

Branch has pre-defined a number of actions that the user can take on a piece of content. This includes things like Viewed, Added to Cart, Added to Wishlist, Shared, etc. By calling userCompletedAction and registering these actions, you’ll gain additional insight about how your users interact with your content.

One BUO at a Time

You should only build BUOs one at a time, as building several and registering actions on multiple BUOs in succession will clog up your network and slow down your app. We’re working on better supporting clusters of pieces of content (e.g. shopping carts, search results, etc.), so for now, stick with BUOs for single pieces of content!

Conclusion

The BUO is an easy, powerful way to catalog the content in your application, and its proper usage provides you with clear-cut analytics about how your users are interacting with that content. At the same time, its easy link generation capabilities empower your users to bring more readers, shoppers, or subscribers directly into the app. These users are going to be much more engaged because they were invited by a friend and were able to see the content they wanted to see immediately after installing the app.

You’re not going to find these kinds of capabilities with any other deep linking solution. Get started integrating Branch today!

The post Branch Concepts: The Branch Universal Object appeared first on Branch.

Simply bringing a user to the app is all well and good, but how valuable is that referred user? If all they do is install the app and then forget about it, then not very valuable. But shouldn’t User B also be rewarded when User A engages with your app in some meaningful way? A Reward Rule can be set up to reward User A when User B purchases something within your app for the first time. Similarly, a Reward Rule can be used so that when, for instance, User A reads their 10th piece of content, User B gets rewarded. There are all sorts of use-cases for Reward Rules to incentivize your users to bring in high-value users to your app. But what if you wanted to also reward a user when someone they’ve driven to the app drives others to the app?

For example, if User A from the above example were to invite another user, User C to the app, you can set up Reward Rules to reward User A  when User C installs, but Reward Rules only affect the referring and referred users. There’s no way for User B, the original referrer, to be rewarded for User A’s referral, is there?

Au contraire. Here is a recipe to do just that.

Setting Up Referrals of Referrals

What you will need:

• 3 Reward Rules
• 2 Custom In-app Events
• 2 Forms of Currency

Reward Rule 1

Referring users get 10 default credits the first time users they’ve referred trigger the event installAfterReferral

The first Reward Rule should look pretty familiar, as it’s a standard setup to give a referring user some credits when they get someone new to install your app.* This rule will reward User A with 10 credits when User C (whom she invited to the app) fires the “installAfterReferral” event. And how does that happen?

* Branch doesn’t merge identities, so if you trigger rewards on `open` or `install`, there could be lost or duplicated rewards for your users.

Custom Event 1

Android

JSONObject params = Branch.getInstance().getFirstReferringParams();

if ((params.has(“+clicked_branch_link”)) && (params.getBoolean(“+clicked_branch_link”)))
   Branch.getInstance(getApplicationContext()).userCompletedAction(“installAfterReferral”);

iOS

NSDictionary *params = [[Branch getInstance] getFirstReferringParams];

if (([params objectForKey:@”+clicked_branch_link”]) && ([[params objectForKey:@”+clicked_branch_link”] boolValue]))
    [[Branch getInstance] userCompletedAction:@”installAfterReferral”]

The above code block will trigger the event “installAfterReferral” if the user clicked a Branch link to install the app. This will in turn trigger the first Reward Rule for the referring user. If you’re using setIdentity to identify your users, this block should appear shortly after that.

Reward Rule 2

Referring users get 1 referralToken credit the first time users they’ve referred trigger the event installAfterReferral

This looks almost exactly like the first Reward Rule, just with a different type of credit. Now, if User A refers User C to the app, and User C  triggers the “installAfterReferral” event, User A  will be awarded 10 default credits and 1 referralToken. But the default credits are what we use to actually give User A in-app rewards, so what do we do with the referralTokens?

Custom Event 2

Android

Branch.getInstance(getApplicationContext()).loadRewards(new BranchReferralStateChangedListener() {
    @Override
    public void onStateChanged(boolean changed, Branch.BranchError error) {
        if (error == null) {
            String referralRewardBucket = “referralToken”;
            int referralCredits = Branch.getInstance(getApplicationContext()).getCreditsForBucket(referralRewardBucket);
            
            while (referralCredits-- > 0) {
                Branch.getInstance(getApplicationContext()).redeemRewards(1, referralRewardBucket, new BranchReferralStateChangedListener() {
                @Override
                public void onStateChanged(boolean isChanged, Branch.BranchError err) {
                    Branch.getInstance(getApplicationContext()).userCompletedAction(“redeemReferralToken”);
                });
            }
        }
    }
});

iOS

[[Branch getInstance] loadRewardsWithCallback: ^(BOOL changed, NSError *error) {
    if (!error) {
        NSString *referralRewardBucket = @”referralToken”;
        int referralCredits = [[Branch getInstance] getCreditsForBucket: referralRewardBucket];

        while (referralCredits-- > 0) {
            [[Branch getInstance] redeemRewards:1 forBucket:referralRewardBucket callback: ^(BOOL chng, NSError *err) {
                [[Branch getInstance] userCompletedAction:@”redeemReferralToken”];
            }];
        }
    }
}];

This code block (which should probably be performed once per session for the user) will observe the user’s current credit balance with Branch. If they have any referralTokens in their account, it will attempt to redeem each one, triggering the event “redeemReferralToken” for each successful redemption.

So, that’s what the referralToken credits are for, but what does the redeemReferralToken event do?

Reward Rule 3

Referring users get 5 default credits each time users they’ve referred trigger the event redeemReferralToken

This is the money maker rule, otherwise known as a credit-maker. That referralToken that User A was given from Reward Rule 2 will now be redeemed automatically when she launches the app, and User B gets 5 credits for each of those redemptions.

So the full flow is: User B invites User A to the app and is rewarded for that with 10 credits. (Reward Rule #1) User A then invites User C to the app and is rewarded with 10 credits. (Reward Rule #1) User A also gets a referralToken credit for inviting User C. (Reward Rule #2) User A’s referralToken gets redeemed the next time they launch the app, giving User B an additional 5 credits for his part in driving User C to the app. (Reward Rule #3)

Now you have second-order referral rewards!

The number of credits awarded for the referrals (both first- and second-order) can be changed, of course, and the concept could even be extended to reward User B for just about any other event that User C performs (firstTransaction, tenArticlesViewed, etc.). All that is required is another “token” type of currency which gets awarded to the referring user, which is then automatically redeemed by that user in the same way as the referralRewardToken, thereby rewarding their referring user.

This is a recipe that will expand your referral reward program to better incentivize your organic growth, something all apps need to succeed.

The post How to Set Up Rewards for Referrals of Referrals appeared first on Branch.