With Branch’s custom on-boarding capabilities, you can personalize your users first interaction with your app. We’ve seen that users who are served a personalized experience on their first app open are more likely to convert within 10 days, not to mention the increase in app loyalty and brand trust overall that comes from persisting context through install.

Here are some common scenarios for building personalized on-boarding. 

  • Increase app retention and improve app loyalty
  • Improve the new users' on-boarding experience

  • I need to block certain users from specific content

Level of Effort - Advanced

Resources required

  • Access to update iOS/Android app 

  • Admin access to Branch Dashboard 



  • Before you begin

    1. Determine what types of custom onboarding you’d like to implement. Some possibilities include:

      • Display the same page a user was viewing on web previously

      • Showing the name / profile picture of a user who referred the installing user (see here for our guide on setting up referrals)

      • Automatically apply a coupon code or offer to a user’s account, and let them know that’s been done.

      • Automatically log a user in, or prefill certain account details

      • Automatically add an item to cart

      • Set a specific user role. For example, if your app supports both 

      • Anything else you could think of!

    2. Decide on what parameters are necessary to direct a user to the necessary page or item. These could be a page/item id, a referring user name, or a coupon code.

  • App iOS:

    1. In your branch.initSession method, add the following code to look for the necessary parameter(s), and route users appropriately.*

  • App Android:

    1. In your branch.initSession method, add the following code to look for the necessary key(s), and route users appropriately.*

  • Dashboard: When creating links, be sure to incorporate these parameters. Depending on how you’re creating Branch links, this may look different. Some examples:

    • Journeys:

  • Dynamic Links:



  • Quick Links (Manual Links):


In order to view the effect of your custom onboarding campaigns, use the sources tab of your Branch dashboard. If you followed our pro tip from the implementation steps, be sure to compare by tags to get the most informative view!


  1. Make sure you’ve completed the prerequisites steps.

  2. If your test links (from the prerequisite steps) are not opening the app correctly, refer to this troubleshooting guide.

  3. If your links are not opening the proper page or applying the correct code, examine the parameters being returned by the branch.initSession call.

    1. If those contain the “+clicked_branch_link” key with the value “false”, be sure you’re not using test links with your live key, or vice-versa. More on live and test mode here.

Next Steps:

If you’re not already using Branch across your email, web, social, referral, and ads channels, add support for those to get the most holistic view of your traffic. When integrating those other channels, be sure to specify the correct custom on-boarding parameters, as we’ve set up here!