Note
In order to give iOS 14 developers 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.
Warning
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.
To use Google Play Services versions below 17 for future app builds, follow these workaround implementation steps.
Warning
If you use your own Android 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 fromcom.unity3d.player.UnityPlayerActivity
toBranchUnityActivity
.BranchUnityActivity
extends theUnityPlayerActivity
but also contains code responsible for initializing the Branch SDK on Android.
Not doing so will result in the callback ininit()
never getting hit.
Configure Branch
Configure your Branch Dashboard.
Customize your app.link domain:
Configure the Branch SDK
Download the latest SDK version or clone our open-source GitHub repository.
Import the 1BranchUnityWrapper.unitypackage1 into your project by clicking
Assets -> Import Package
.
Configure app
You can configure your Unity app to work with Branch by either using a Branch prefab asset or by adding a branch.json
file.
Warning
Please ensure that the Activity checkbox is checked in Project Settings → Player, because the Unity SDK currently uses
UnityPlayerActivity
.
Not doing so will cause a build error on Android.
Configure with Branch prefab
Add the Branch prefab asset to the first scene of your Unity project.
Note
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
Field | Description |
---|---|
Enable Logging | This feature is currently NOT working. Workaround is to set this in the |
Test Mode | This feature is currently NOT working on iOS. Workaround is to set this in the |
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 |
Live App Links | This field is applicable if you want to enable |
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 |
Test App Links | This field is applicable if you want to enable |
Configuration with branch.json
You may also configure the app by adding Assets/StreamingAssets/branch.json
to your project.
Key | Type | |
---|---|---|
enableLogging | boolean | Enables Branch SDK logging |
deferInitForPluginRuntime | boolean | Defers underlying iOS and Android SDKs initialization until the C# layer registers a callback. |
useTestInstance | boolean | Enables 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 Branch Deep Link
Create a Branch 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");
Then, 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 Branch 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
Read Deep Link 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());
}
}
Note
This refereshes with every session (App Installs and App Opens).
Retrieve link data
Warning
Make sure you run this code after
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 using Branch NativeLinkâ„¢.
To use this feature you must:
Enable NativeLinkâ„¢ Deep Linking in the Branch Dashboard Configuration tab
or
Manually configure your Branch Link to use $ios_nativelink.
Warning
Make sure the underlying iOS SDK Version is v1.39.4+.
Implement one of the pasteboard opt-in options in the native iOS SDK code.
Access
Please note that deferred deep linking is part of our Engagement package. Learn more on our packaging page.
Navigate to 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 piece of content associated with a Branch Universal Object, use the following snippet:
Branch.registerView(universalObject);
Track users
Set user IDs on login
Set the identity of a user (ID, UUID, etc) for events, deep links, and referrals:
Branch.setIdentity("your user id");
Unset user IDs on logout
To log a user out, use the logout()
method:
Branch.logout();
Tracking user actions and events
Use the BranchEvent
class to monitor unique user interactions beyond app installations and openings. Use it to log Branch Events like adding items to a shopping cart or completing a registration form. The class links content via a BranchUniversalObject
and allow for metric analytics on the Branch Dashboard. BranchEventType
will enumerate frequently tracked events and parameters. You can also use custom names and custom parameters using a Branch Custom Event.
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
Branch requires ARC, and we don’t intend to add checks throughout 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
classes. Other plugins that use their own
custom activity and application classes can cause conflicts between these classes.
To resolve these conflicts:
Create a empty android library.
Add the Branch plugin along with the other plugins into your project.
Create a custom
activity
andapplication
class that will contain the custom logic for all your plugins.Build your library.
Add your library into your Unity project.
Change
android:name
to name of your customapplication
class in theapplication
tag of your Manifest.Change
android:name
to name of your customactivity
class in theactivity
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 the Cardboard SDK plugin. To resolve conflicts:
Merge all custom
AppControllers
in one.Comment code in other
AppControllers
(or delete otherAppControllers
).
Sample app
Workaround implementation steps for using Google Play Services < Version 17
Install
BranchUnityWrapper.unitypackage
.Delete
android-support-customtabs-23.3.0.jar
from Assets->Plugins->Branch->Android->libs.Create a Assets->Plugins->Branch->Editor folder.
Add the attached
BranchPluginDependencies.xml
to the new Editor folder.Install the latest Google Play Resolver from https://github.com/googlesamples/unity-jar-resolver.
Dependencies will now auto-resolve, but you may want to confirm by listing the libraries from the play resolver menu. You will 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}