In-App Routing
Overview
When a Branch link is opened, either your app launches or users are taken to the App/Play store to download it. Deep links improve this process by routing users directly to specific content after your app launches. With Branch, this works even if users have to stop and download the app first (a.k.a., "deferred deep links"). Deep links are an incredibly important part of delivering a high-quality user experience.
Below we will walk you through your 3 configuration options:
- Option 1: Build custom routing inside the routing callback - Route immediately on app open
- Option 2: Let Branch use your existing deep link routing
iOS Deferred Deep Linking
With the introduction of iOS 15 and iCloud+ Private Relay, Branch released support for deferred deep linking using NativeLink™
To implement iOS NativeLink™, follow the instructions in our developer documentation.
Please note that deferred deep linking is part of our Engagement package. Learn more on our pricing page.
Option 1: Build custom routing inside the routing callback
Route immediately on app open
Inside the deep link handler callback that you register in initSession, you will want to examine the parameters dictionary to determine whether the user opened a Branch link. Below is an example assuming that the links correspond to pictures. Below are some examples from iOS and Android where we're using the pictureId
key to route, but you can see more code snippets for the other platforms here.
iOS
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// initialize the session, setup a deep link handler
[[Branch getInstance] initSessionWithLaunchOptions:launchOptions
andRegisterDeepLinkHandler:^(NSDictionary *params, NSError *error) {
// start setting up the view controller hierarchy
UINavigationController *navC = (UINavigationController *)self.window.rootViewController;
UIStoryboard *storyboard = [UIStoryboard storyboardWithName:@"Main" bundle:nil];
UIViewController *nextVC;
// If the key 'pictureId' is present in the deep link dictionary
// then load the picture screen with the appropriate picture
NSString *pictureId = [params objectForKey:@"pictureId"];
if (pictureId) {
nextVC = [storyboard instantiateViewControllerWithIdentifier:@"PicVC"];
[nextVC setNextPictureId:pictureId];
} else {
nextVC = [storyboard instantiateViewControllerWithIdentifier:@"MainVC"];
}
// navigate!
[navC setViewControllers:@[nextVC] animated:YES];
}];
return YES;
}
Android
@Override
public void onStart() {
super.onStart();
Branch.sessionBuilder(this).withCallback(new BranchReferralInitListener(){
@Override
public void onInitFinished(JSONObject referringParams, Branch.BranchError error) {
if (error == null) {
// params are the deep linked params associated with the link that the user clicked before showing up
// params will be empty if no data found
String pictureID = referringParams.optString("picture_id", "");
if (pictureID.equals("")) {
startActivity(new Intent(this, HomeActivity.class));
}
else {
Intent i = new Intent(this, ViewerActivity.class);
i.putExtra("picture_id", pictureID);
startActivity(i);
}
} else {
Log.e("MyApp", error.getMessage());
}
}
}).withData(this.getIntent().getData()).init();
}
Branch-added parameters
In addition to any custom key/value pairs specified in the link data dictionary, Branch also returns some other useful parameters every time a session is initialized. These parameters will be returned every time session is initialized, even if the user has not clicked on a Branch link. Here is a list, and a description of what each represents.
~
denotes analytics+
denotes information added by Branch- This data will not be available for deeplinks from Facebook or other Self Attributing Networks
- For the curious, $ denotes reserved keywords used for controlling how the Branch service behaves. Read more about control parameters on the Configuring Links page
Parameter | Meaning |
---|---|
+is_first_session | Denotes whether this is the first session (install) or any other session (re-install, open) |
+clicked_branch_link | Denotes whether or not the user clicked a Branch link that triggered this session |
+match_guaranteed | True or false as to whether the match was made with 100% accuracy |
+referrer | The referrer for the link click, if a link was clicked |
+click_timestamp | Epoch timestamp of when the click occurred |
+url | The full URL of the link that drove the install/open, if present (e.g. yourapp.app.link/abcde12345) |
~channel | The channel on which the link was shared, specified at link creation time |
~feature | The feature, such as invite or share, specified at link creation time |
~tags | Any tags, specified at link creation time |
~campaign | The campaign the link is associated with, specified at link creation time |
~creation_source | Where the link was created ('API', 'Dashboard', 'SDK', 'iOS SDK', 'Android SDK', or 'Web SDK') |
~id | Automatically generated 18 digit ID number for the link that drove the install/open, if present (0 for dynamic and 3P links) |
Access deep link parameters later on
You can retrieve the deep link data at any time from the Branch singleton by calling one of the below methods. This would be the route to use if you wanted to deep link the user after prompting them to log in or something. You can see the code snippets for other platforms here.
Get latest session referring params
This returns the latest set of deep link data from the most recent link that was clicked. If you minimize the app and reopen it, the session will be cleared and so will this data.
iOS
NSDictionary *params = [[Branch getInstance] getLatestReferringParams];
Android
JSONObject sessionParams = Branch.getInstance().getLatestReferringParams();
Get first session referring params
This returns the first set of deep link data that ever referred the user. Once it's been set for a given user, it can never be updated. This is useful for referral programs.
iOS
NSDictionary *params = [[Branch getInstance] getFirstReferringParams];
Android
JSONObject installParams = Branch.getInstance().getFirstReferringParams();
Option 2: Let Branch use your existing deep link routing
If your app already supports deep linking using URI paths, you can populate the $deeplink_path
, $ios_deeplink_path
or $android_deeplink_path
link parameters with the URI path of the content to be displayed within the app. When the Branch SDK receives a link containing one of these parameters, it will automatically load the specified URI path.
Incomplete support on iOS
Universal Links and Spotlight do not support deep linking via URI paths. If you use
$deeplink_path
or$ios_deeplink_path
, you will need to implement some custom logic. Click here for more information.
How to insert custom deep link routes into a Branch link
All of the examples below create links that will cause Branch to display myapp://content/1234
after launch. Please do not add the URI scheme on the $deeplink_path
parameters; we automatically append the scheme specified in the Configuration page of the dashboard.
When creating links dynamically
If you're creating a link by appending query parameters, just append the control parameters to the URL. Please make sure to URL encode everything, else the link will break.
"https://[branchsubdomain]?%24deeplink_path=content%2F1234"
When using a mobile SDK
iOS
BranchLinkProperties *linkProperties = [[BranchLinkProperties alloc] init];
linkProperties.feature = @"sharing";
linkProperties.channel = @"facebook";
[linkProperties addControlParam:@"$deeplink_path" withValue:@"content/1234"];
Android
LinkProperties linkProperties = new LinkProperties()
.setChannel("facebook")
.setFeature("sharing")
.addControlParameter("$deeplink_path", "content/1234");
When Creating Quick Links on the Branch Dashboard
You can specify the control parameters for individual Quick Links by inserting the keys and values into the Deep Link Data (Advanced) section.
How to handle URI paths with Universal Links or App Links
Because Universal Links, Spotlight and Android App Links do not use URI schemes for deep link routing. If you populate $deeplink_path
, $ios_deeplink_path
or $android_deeplink_path
with a URI path, you will need to a bit of additional work to ensure that Branch links route according to your original schema.
- Initialize session as described in the app configuration steps.
- In the callback function, add some custom code to read the appropriate
$deeplink_path
parameter in theparams
- Use this value to call your existing routing logic to route users to the correct place in your app
Now whenever your app launches from a Branch link that has the product_picture
key set in its data dictionary, this Activity will be displayed!
Updated 6 days ago