Unity

Integrate Branch

  • Configure Branch

  • Get the Branch SDK

  • Configure app

    • Add the Branch prefab asset to the first scene of your Unity project

    • Update your Branch prefab

      image

      Do not forget to click on the Update iOS Wrapper and the Update Android Manifest buttons once you are done.

    • Prefab fields
      Field name Description
      Simulate Fresh Installs This checkbox enables debug mode. This allows you to simulate fresh every time you uninstall and reinstall the app. Please make sure to uncheck this box before releasing your app.
      Test Mode This checkbox picks the test key from your Branch prefab. If this box is unchecked, by default, your live Branch key is used.
      Test Branch Key This is the test Branch key found on the App Settings page of your Test Branch app
      Test Branch URI This is the test URI scheme that you have set for your app on the Link Settings page for your Test Branch app
      Test Android Path Prefix This field is only applicable if you are on the bnc.lt domain of your Test Branch app. You can find it underneath the field labeled SHA256 Cert Fingerprints on the Link Settings page once you’ve enabled App Links. It will look something like this: /WSuf (the initial / character should be included).
      Test App Links This field is applicable if you want to enable APPLINKS and UNIVERSAL LINKS for your domain. Please make sure to add the correct domain found on the bottom of the Link Settings page of your Test Branch app. Add the -alternate domain to have your Branch links deeplink from your Deepviews and Journeys. If you are not using a app.links domain please write into integrations@branch.io
      Live Branch Key This is the Live Branch key found on the App Settings page of your Live Branch app
      Live Branch URI This is the Live URI scheme that you have set for your app on the Link Settings page for your Live Branch app
      Live Android Path Prefix This field is only applicable if you are on the bnc.lt domain Link Settings page for your Live Branch app. You can find it underneath the field labeled SHA256 Cert Fingerprints on the Link Settings page once you’ve enabled App Links. It will look something like this: /WSuf (the initial / character should be included).
      Live App Links This field is applicable if you want to enable APPLINKS and UNIVERSAL LINKS for your domain. Please make sure to add the correct domain found on the bottom of the Link Settings page of your Live Branch app. Add the -alternate domain to have your Branch links deeplink from your Deepviews and Journeys. If you are not using a app.links domain please write into integrations@branch.io
      • Note for Android

        Occasionally, Android will barf after you add our library due to generic issues unrelated to Branch. Please see this Android troubleshooting section

  • Initialize Branch

    • Add Branch to your Monobehavior script of your first Scene

      using UnityEngine;
      using System.Collections;
      
      public class Spin : MonoBehaviour {
      
          // Use this for initialization
          void Start () {
              Branch.initSession(CallbackWithBranchUniversalObject);
          }
      
          void CallbackWithBranchUniversalObject(BranchUniversalObject buo,
                                                  BranchLinkProperties linkProps,
                                                  string error) {
              if (error != null) {
                  System.Console.WriteLine("Error : "
                                          + error);
              } else if (linkProperties.controlParams.Count > 0) {
                  System.Console.WriteLine("Deeplink params : "
                                          + buo.ToJsonString()
                                          + linkProps.ToJsonString());
              }
          }
      
          // Update is called once per frame
          void Update () {
              //rotate 90 degress per second
              transform.Rotate(Vector3.up * Time.deltaTime*90);
          }
      }
      
    • Create a Quick link on the Branch Dashboard

    • Delete your app from the device

    • Paste Quick link in Google Hangouts (Android) or Notes (iOS)

    • Click on the Quick link to open your app

    • Compile and download your app to your device

    • You should see deferred deep link data show in your app

Implement features

  • Create content reference

    • The Branch Universal Object encapsulates the thing you want to share with your link

      BranchUniversalObject universalObject = new BranchUniversalObject();
      // Content index mode: 0 - private mode, 1 - public mode
      universalObject.contentIndexMode = 1;
      //Identifier that helps Branch dedupe across many instances of the same content.
      universalObject.canonicalIdentifier = "id12345";
      // OG title
      universalObject.title = "id12345 title";
      // OG Description
      universalObject.contentDescription = "My awesome piece of content!";
      // OG Image
      universalObject.imageUrl = "https://s3-us-west-1.amazonaws.com/branchhost/mosaic_og.png";
      // User defined key value pair
      universalObject.metadata.Add("foo", "bar");
      
    • After you have created a Branch Universal Object, Define Link Properties

      BranchLinkProperties linkProperties = new BranchLinkProperties();
      linkProperties.tags.Add("tag1");
      linkProperties.tags.Add("tag2");
      // Feature link is associated with. Eg. Sharing
      linkProperties.feature = "invite";
      // The channel where you plan on sharing the link Eg.Facebook, Twitter, SMS etc
      linkProperties.channel = "Twitter";
      // The Campaign that drives this link
      linkProperties.campaign = "referral";
      linkProperties.stage = "2";
      // Parameters used to control Link behavior
      linkProperties.controlParams.Add("$desktop_url", "http://example.com");
      
    • Generate a Branch link

      Branch.getShortURL(universalObject, linkProperties, (params, error) => {
          if (error != null) {
              Debug.LogError("Branch.getShortURL failed: " + error);
          } else if (params != null) {
              Debug.Log("Branch.getShortURL shared params: " + url);
          }
      });
      
    • Share deep links between users and apps

      Branch.shareLink(universalObject, linkProperties, "Sharing link: ", (parameters, error) => {
          if (error != null) {
              Debug.LogError("Branch.shareLink failed: " + error);
          } else if (parameters != null) {
                  Debug.Log("Branch.shareLink: " + parameters["sharedLink"].ToString() + " " + parameters["sharedChannel"].ToString());
      }
      });
      
    • Read Deeplink params from a BUO in your BranchInitSession callback

    • Returns deep link properties

      public void CallbackWithBranchUniversalObject(BranchUniversalObject universalObject, BranchLinkProperties linkProperties, string error) {
          if (error != null) {
              Debug.LogError("Branch Error: " + error);
          } else {
              Debug.Log("Branch initialization completed: ");
              Debug.Log("Universal Object: " + universalObject.ToJsonString());
              Debug.Log("Link Properties: " + linkProperties.ToJsonString());
          }
      }
      

      This refereshes with every session (App Installs and App Opens)

      Read install (install or open) parameters from anywhere after Branch initsession
      BranchUniversalObject obj = Branch.getFirstReferringBranchUniversalObject();
      BranchLinkProperties link = Branch.getFirstReferringBranchLinkProperties();
      
    • Use the link parameters to decide which view you wish to load

      public class MyCoolBehaviorScript : MonoBehaviour {
          void Start () {
              Branch.initSession(delegate(Dictionary<string, object> parameters, string error) {
                  if (parameters.ContainsKey("picture_id") {
                      // load the Scene to show the picture
                      SceneManager.LoadSceneAsync("ImageScene", LoadSceneMode.Additive);
                  } else {
                      // load your normal Scene
                      SceneManager.LoadSceneAsync("NormalScene", LoadSceneMode.Single);
                  }
              });
          }
      }
      
  • Track content

    • If you want to track the number of times a user views a BUO content

      Branch.registerView(universalObject);
      
  • Track users

    • Set User-Ids on Login/Register
      Branch.setIdentity("your user id");
      
    • UnSet User-Ids on logout
      Branch.logout();
      
  • Track events

    • Track custom events
      Branch.userCompletedAction("your_custom_event");
      
    • Store meta data with these custom events
      Dictionary<string, object> stateItems = new Dictionary<string, object>
      {
          { "username", "Joe" },
          { "description", "Joe likes long walks on the beach..." }
      };
      Branch.userCompletedAction("your_custom_event", stateItems); // same 63 characters max limit
      
  • Handle referrals

    • Typical Referral Flow
      1. Setup a Reward rule on your Branch Dashboard.
      2. Referrer has his/her identity set at login/signup
      3. Referrer creates a Branch link.
      4. Referrer shares the Branch link.
      5. Referee clicks on the Branch link, installs the app.
      6. The referee has his/her identity set at login/signup
      7. Referee triggers a custom event after login/Signup.
      8. Use the following SDK methods to see a user's current credits, redeem credits and check a user's entire credit history.
    • Get Reward balance
      Branch.loadRewards(delegate(bool changed, string error) {
          // changed boolean will indicate if the balance changed from what is currently in memory
      
          // will return the balance of the current user's credits
          int credits = Branch.getCredits();
      });
      
    • Redeem Rewards
      Branch.redeemRewards(5);
      
    • Get Credit History
      Branch.getCreditHistory(delegate(List<string> historyItems, string error) {
          if (error == null) {
          // process history
          }
      });
      

Troubleshoot issues

  • iOS + Unity 4.6 Note

    Branch requires ARC, and we don’t intend to add checks thoughout the SDK to try and support pre-ARC. However, you can add flags to the project to compile the Branch files with ARC. If you wish to do this add -fobjc-arc to all Branch files.

    Note: we by default have this flag checked, but please check before building for iOS.

  • Android - Using your own Custom Application Class

    If you are using your own Custom Application class, you will need to add Branch android library into your project and call the following in method OnCreate():

    Branch.getAutoInstance(this.getApplicationContext());
    

    If you are using your own custom Activity class, please make sure that you are overridding the following Activities:

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
    }
    
    @Override
    public void onNewIntent(Intent intent) {
        this.setIntent(intent);
    }
    
  • Support Branch with different Plugins

    The Branch SDK has its own custom activity and application class. Other plugins that use their own custom activity and application classes can cause "conflicts" between these classes. To resolve these conflicts:

    1. Create a empty android library
    2. Add the Branch plugin along with the other plugins into your project
    3. Create a custom Activity and Application class that will contain the custom logic for all your plugins
    4. Build your library
    5. Add your library into Unity project
    6. Change android:name to name of your custom Application class in the application tag of your Manifest
    7. Change android:name to name of your custom Activity class in the activity tag of your Manifest
  • Support several IMPL_APP_CONTROLLER_SUBCLASS

    The Branch Unity SDK plugin uses its own UnityAppController that expands default AppController. This is used to catch Universal Links.

    @interface BranchAppController : UnityAppController
    {
    }
    @end
    
    @implementation BranchAppController
    
    - (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray *))restorationHandler {
        BOOL handledByBranch = [[BranchUnityWrapper sharedInstance] continueUserActivity:userActivity];
        return handledByBranch;
    }
    
    @end
    
    IMPL_APP_CONTROLLER_SUBCLASS(BranchAppController)
    

    Some Plugins expand the default AppController the same was as Branch does like Cardboard SDK plugin. To resolve conflicts:

    1. Merge all custom AppControllers in one.
    2. Comment code in other AppControllers (or delete other AppControllers).
  • Sample app

Comments