Filters

📘

iOS 14 Implementation

In order to give you full control over the user experience, the Branch SDK will not trigger the IDFA permission modal.

However, we will still collect and use IDFAs when available if you do choose to trigger the modal.

LEARN MORE

🚧

Google Play Services version 17+

If you reference Google Play Services version 17 or higher, you MUST complete Google's update instructions here.

Due to a major Google Play Services change made in June 2019, not completing the update steps will cause Branch's Android SDK (and various other cross-platform SDKs, e.g. Unity) to stop collecting Android AID which we use to ensure accurate deep linking and attribution.

If you are running Google Play Services versions below 17, no update is necessary.

NOTE: To use Google Play Services versions below 17 for future app builds, follow these workaround implementation steps.

🚧

Using you own Android Manifest

If you use your own Manifest, and not the one provided with the Branch SDK, make sure you change the android:name field of your launcher activity you are referencing from com.unity3d.player.UnityPlayerActivity to BranchUnityActivity. BranchUnityActivity extends the UnityPlayerActivity but also contains code responsible for initializing the Branch SDK on Android.

Note: Not doing so will result in the callback in init() never getting hit

Configure Branch

  • Customize your app.link domain:

Configure the Branch SDK

Configure App

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

Update your Branch prefab

📘

Notes

  • Do not forget to click on the Apply Changes once you are done.
  • On Android, these values are used to generate Assets/Plugins/Android/AndroidManifest.xml. If you have any conflicts, you may manually enter these settings.
  • On iOS, these values are used to update the Info.plist, branch_domains.entitlements and update a few build settings to enable C++ exceptions. If you have any conflicts, you may manually enter these settings.

Prefab Fields

FieldDescription
Enable LoggingThis feature is currently NOT working. Workaround is to set this in the branch.json config file.
Test ModeThis feature is currently NOT working on iOS. Workaround is to set this in the branch.json config file.

Enables use of the Test Key.
Live Branch KeyThis is the Live Branch key found on the App Settings page of your Live Branch app
Live Branch URIThis 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 PrefixThis 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 LinksThis 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 contact our support team.
Test Branch KeyThis is the test Branch key found on the App Settings page of your Test Branch app.
Test Branch URIThis 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 PrefixThis 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 LinksThis 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 contact our support team

Configuration with branch.json

You may also configure the app by adding Assets/StreamingAssets/branch.json to your project.

KeyType
enableLoggingbooleanEnables Branch SDK logging
deferInitForPluginRuntimebooleanDefers underlying iOS and Android SDKs initialization until the C# layer registers a callback.
useTestInstancebooleanEnables using the Test Key on iOS

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) {
                Debug.LogError("Error : "
                                        + error);
            } else if (linkProps.controlParams.Count > 0) {
                Debug.Log("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);
        }
    }

Test Deep Link

  • 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.AddCustomMetadata("foo", "bar");

Create deep link

  • 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";
    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, (parameters, error) => {
        if (error != null) {
            Debug.LogError("Branch.getShortURL failed: " + error);
        } else if (params != parameters) {
            Debug.Log("Branch.getShortURL shared params: " + parameters["url"].ToString());
        }
    });

Share deep link

  • 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 deep link

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());
        }
    }

📘

Note

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

Retrieve link data from anywhere after Branch initsession

//get the latest referring params (last Branch link click)
BranchUniversalObject obj = Branch.getLatestReferringBranchUniversalObject();
BranchLinkProperties link = Branch.getLatestReferringBranchLinkProperties();

//get the first referring params (open or install)
BranchUniversalObject obj = Branch.getFirstReferringBranchUniversalObject();
BranchLinkProperties link = Branch.getFirstReferringBranchLinkProperties();

NativeLink™ Deferred Deep Linking (iOS Only)

  • Use iOS pasteboard to enable deferred deep linking via Branch NativeLink™

🚧

Prerequisites

Make sure the underlying iOS SDK Version is v1.39.4+

To use this feature you must:

Implement one of the pasteboard opt-in options in the native iOS SDK code.

Navigate and Display content

  • 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

Sets the identity of a user (ID, UUID, etc) for events, deep links, and referrals

Branch.setIdentity("your user id");

UnSet User-Ids on logout

Branch.logout();

Tracking User Actions and Events

Use BranchEvent class to track special user actions or application specific events beyond app installs, opens, and sharing. You can track events such as when a user adds an item to an on-line shopping cart, or searches for a keyword etc. BranchEvent provides an interface to add content(s) represented by a BranchUniversalObject in order to associate content(s) with events. You can view analytics for the BranchEvents you fire on the Branch dashboard. BranchEventType enumerate the most commonly tracked events and event parameters that can be used with BranchEvent for the best results. You can always use custom event names and event parameters.

BranchEvent e01 = new BranchEvent (BranchEventType.COMPLETE_REGISTRATION);

e01.SetAffiliation("my_affilation");
e01.SetCoupon("my_coupon");
e01.SetCurrency(BranchCurrencyType.USD);
e01.SetTax(10.0f);
e01.SetRevenue(100.0f);
e01.SetShipping(1000.0f);
e01.SetDescription("my_description");
e01.SetSearchQuery("my_search_query");
e01.AddCustomData("custom_data_key01", "custom_data_value01");
e01.AddContentItem(universalObject);

Branch.sendEvent (e01);


BranchEvent e02 = new BranchEvent ("MY_CUSTOM_EVENT");

e02.SetAffiliation("my_affilation");
e02.SetCoupon("my_coupon");
e02.SetCurrency(BranchCurrencyType.USD);
e02.SetTax(10.0f);
e02.SetRevenue(100.0f);
e02.SetShipping(1000.0f);
e02.SetDescription("my_description");
e02.SetSearchQuery("my_search_query");
e02.AddCustomData("custom_data_key01", "custom_data_value01");
e02.AddContentItem(universalObject);

Branch.sendEvent (e02);

Troubleshooting 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 -fobjectivec-arc to all Branch files.

📘

Note

By default this flag is 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 overriding the following functions:

@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

Workaround Implementation Steps for using Google Play Services < version 17

  1. Install BranchUnityWrapper.unitypackage.
  2. Delete android-support-customtabs-23.3.0.jar from the Assets->Plugins->Branch->Android->libs.
  3. Create a Assets->Plugins->Branch->Editor folder.
  4. Add the attached BranchPluginDependencies.xml to the new Editor folder.
  5. Install the latest Google Play Resolver from https://github.com/googlesamples/unity-jar-resolver
  6. It should auto resolve dependencies, but you may want to confirm by listing the libraries from the play resolver menu. You should see the following block:
dependencies {implementation 'com.android.installreferrer:installreferrer:1.0' // Assets/Plugins/Editor/BranchPluginDependencies.xml:11implementation 'com.android.support:customtabs:23.3.0' // Assets/Plugins/Editor/BranchPluginDependencies.xml:13implementation 'com.google.android.gms:play-services-ads:16.0.0' // Assets/Plugins/Editor/BranchPluginDependencies.xml:12}