{% highlight %}
Please visit dev.branch.io for the most up to date version of this guide and other learning resources for Branch. {% endhighlight %}
This guide will help you integrate content sharing with deeplinking into your app. We will also cover several customizations you can perform. The sections are as follows:
- Dashboard: App Setup
- Dashboard: Marketing Links
- Configuring Your App to Track Installs
- Example: Facebook Ads
- Personalizing A User's First Experience
- Custom Events and Funnels
To get started, create an account in https://dashboard.branch.io/.
Navigate to the Settings page and fill in information in each of the fields, which at the very minimum includes:
- App Name
- App Store / Play Store information
- URI Scheme
If you've already done this, you can skip ahead to section 2, Dashboard: Marketing Links. Otherwise follow the instructions below.
To get started, point your browser to https://dashboard.branch.io/. If you haven't created an account before, you can signup and get taken through the basic setup right away. If you've signed up already, simply navigate to the Summary page and click the dropdown button in the top right. Choose "Create new app."
You will be prompted to enter a name for your new app. Do so and press "Create."
Navigate to the Settings page. Scroll down to App Store Information and search for your app by name--this is the same name listed on iTunesConnect. With this information, Branch will automatically redirect users without your app installed on their devices to the App Store.
In the case that your app cannot be found on the App Store (e.g. if you are distributing an enterprise app over the Internet, or you're not listed in the US app stores), you can also enter a custom URL by choosing "Custom URL to TestFlight/Other Host"
On the Settings page, scroll down to URI Schemes (advanced), click to expand, and add in the unique string you've chosen for your app (e.g. yourapp://). Be sure to press "Save" when you're finished.
For further instructions, pop over to the iOS SDK Readme.
When you create links on the dashboard, you have a subset of these overall labels available to you. Visit dashboard.branch.io and select the Marketing tab. Then click + Add link to get started.
The minimum required information is a Link Description. Creating links is actually this simple!
The following sections will walk through various options and their implications.
One example description if you want to treat this guide is: "Facebook ad for blue sneakers - summer 2015" -- type that in the box.
The more information you enter, the better you'll be able to segment data on the Dashboard and in exports. We recommend setting Channel and Campaign. Tags allows you to easily add tags that don't need to be categorized. For information of the form [key]: [value] such as "product": "shoes", we recommend adding them to "Deep Link Data (Advanced)", discussed below.
Hint: Press the 'comma' or 'return' key after each tag.
This is more important for links that will be visible. For ads, this URL will be buried in the add and most users won't see it. However, you still have the option to customize it.
This allows you to direct the user to somewhere other than the App Store or Play Store if he does not have the app installed. This gives you flexibility as a marketer. You may decide for certain links that if they do not have the app, the user should be sent to www.yourwebsite.com/a_particular_campaign.
Note that these redirects only come into play if the user does not have the app installed.
While our URL Creation Guide details how to set the default social media tags that will be used app-wide, you can customize these on a per-link basis as well.
For more information on the optimal format for the title and description, see Facebook's Sharing Best Practices.
This is a great place to specify any other information that you think will be of use either in-app or in when combing through data later on. If you are treating this guide like a tutorial, go ahead and enter key "ad_id" and value "abc123".
Press the green "Save" button when you are done editing the link.
Based on what you've built so far, you will be able to track your ad campaign's clicks by device -- how many people on each platform (desktop, iOS, Android) have clicked your ads.
If you integrate our SDK into your app, you can:
- See exactly how many people are installing your app based on each of your ads.
- Personalize a user's experience after clicking on an ad. This works regardless of whether the user previously had your app installed. Examples include:
- display a campaign-specific message
- automatically take the user to the same pair of shoes that were featured in the ad that was clicked on
- apply a certain coupon towards a purchase of a new pair of shoes, with a coupon icon at the top of the screen
- Track events and create funnels so you can see which ads are performing best on concrete measures such as # of completed signups or number/type of purchases even if the app was not previously installed.
For iOS, you need to add it to YourProject-Info.plist (Info.plist for Swift). Create a key called branch_key, with string value: YOUR_BRANCH_KEY. Here are instructions with graphics.
URI scheme is also set in the plist, and you may already have one. Make sure it matches the URI scheme you entered on the Dashboard. If this is your first time setting a URI scheme, see these instructions with graphics
Branch is available through CocoaPods, to install it simply add the following line to your Podfile:
pod "Branch"
For alternative methods including installing from a framework, click here.
Add the following to your AppDelegate.m file. For Swift, or more in-depth instructions, click here.
#import <Branch/Branch.h>- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// anything else you need to do in this method
// ...
Branch *branch = [Branch getInstance];
[branch initSessionWithLaunchOptions:launchOptions andRegisterDeepLinkHandler:^(NSDictionary *params, NSError *error) { // previously initUserSessionWithCallback:withLaunchOptions:
if (!error) {
// params are the deep linked params associated with the link that the user clicked -> was re-directed to this app
// params will be empty if no data found
// ... insert custom logic here ...
}
}];
}- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
// pass the url to the handle deep link call
// if handleDeepLink returns YES, and you registered a callback in initSessionAndRegisterDeepLinkHandler, the callback will be called with the data associated with the deep link
if (![[Branch getInstance] handleDeepLink:url]) {
// do other deep link routing for the Facebook SDK, Pinterest SDK, etc
}
return YES;
}You can now see exactly how many people are installing your app based on each of your ads!
We are now going to take a break from code to offer an example of how to place your ad on Facebook (Section 4).
To personalize a user's first experience after tapping the ad, skip down to section 5, Personalizing A User's First Experience (Advanced).
Skip ahead to section 6, Custom Events and Funnels (Advanced), if you want to track events and create funnels. Again, this allows you to see which ads are performing best on concrete measures such as # of completed signups or number/type of purchases.
Navigate to https://www.facebook.com/ads/create while logged in to your Facebook page. (If you don't yet have a Facebook page, you will need to create one before advertising on Facebook.)
Choose "Send people to your website". Unfortunately due to a bug with Facebook's API, you cannot currently run campaigns for app downloads through the option "Get installs of your app."
On the next page, you need to enter the Branch link that was generated in the last step. Here's a gif to help:
You can now customize your ad per the usual Facebook ad creation interface.
Notice that any OG tag information your provided has prepopulated in the interface.
Last step is to make sure you target the mobile app, not the desktop! If you need help, see the gif below:
Now make sure you have a picture of the appropriate size, then order up that ad!
The following example gives one example for customizing a user's first experience. Because it is highly app-dependent, we only provide the Branch code and a bit of example code to get a developer on her way.
The following implementation can tell if a user wanted to view a picture - even if the user just installed the app and this is the first open! If the user clicked on a Branch link with the parameter ad_id attached, the application redirects to a screen that shows a custom message based on the ad. This screen could encourage the user to "Purchase these blue sneakers now to get 20% off!" Otherwise the default view controller is shown. Obviously routing logic is heavily implementation-specific, so the code below is just an example (this example uses Storyboards). See our iOS sample project Branchster for another example of routing.
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// Initalize Branch and register the deep link handler
// The deep link handler is called on every install/open to tell you if the user had just clicked a deep link
Branch *branch = [Branch getInstance];
[branch initSessionWithLaunchOptions:launchOptions isReferrable:@YES andRegisterDeepLinkHandler:^(NSDictionary *params, NSError *error) { // previously initUserSessionWithCallback:withLaunchOptions:
UINavigationController *navController = (UINavigationController *)self.window.rootViewController;
NSString * storyboardName = @"Main";
UIStoryboard *storyboard = [UIStoryboard storyboardWithName:storyboardName bundle: nil];
UIViewController *nextVC;
// If the key 'ad_id' is present in the deep link dictionary
// then load the a screen corresponding to the ad
NSString *adId = [params objectForKey:@"ad_id"];
if (adId) {
[MyAppPreferences setAdViewed: adId];
// Choose the ad follow-up view controller as the next VC
nextVC = [storyboard instantiateViewControllerWithIdentifier:@"AdFollowUpViewController"];
// Else, the app is being opened up from the home screen or from the app store
// Load the next logical view controller
} else {
nextVC = [storyboard instantiateViewControllerWithIdentifier:@"MainViewController"];
}
// launch the next view controller
[navController setViewControllers:@[nextVC] animated:YES];
}];
return YES;
}What you do with ad_id is highly specific to your app, but we already brainstormed a few use cases:
- display a campaign-specific message
- automatically take the user to the same pair of shoes that were featured in the ad that was clicked on
- apply a certain coupon towards a purchase of a new pair of shoes, with a coupon icon at the top of the screen
Feel free to shoot us anything you think up!
You can track custom user actions such as viewing the shoes, adding to cart and making a purchase. This will allow you to track the effectiveness of various ads (or no ads) in leading to purchases.
To track events, simply add a single line of code:
[[Branch getInstance] userCompletedAction:@"clicked ad"];You can also include state, such as the ad_id from the link!
NSMutableDictionary *params = [NSMutableDictionary dictionary];
if (adId) params[@"ad_id"] = adId;
[[Branch getInstance] userCompletedAction:@"clicked ad" withState:params];You can also track purchases or any other event in the same way:
NSMutableDictionary *params = @{@"product_id": @"2976"};
[[Branch getInstance] userCompletedAction:@"purchase" withState:params];If you track these two events, you can now create a funnel on the Dashboard. At the bottom of the Summary page, add a funnel and choose the following events:
If you locate the above lines of code next to the actual ad click and purchase events, you should now have an accurate funnel showing the conversion from ad clicks to actual purchases.
That's all you need for custom events and funnels.
If you still have questions about how to implement deeplinked-ads, please send a note to [email protected].