Overview

While Branch configuration steps for Xamarin and MAUI applications differ, both types of applications use the same set of Branch SDK methods for feature implementation. These methods can be used to support both the iOS and Android components of your .NET application.

IMPORTANT: Please note that both Xamarin and MAUI applications need to use the Branch-Xamarin-Linking-SDK NuGet package, but that versions 9.0.0+ are only for MAUI apps. Earlier versions are for Xamarin.

Deep Link

The Branch SDK has a collection of methods that make creating, sharing, and reading Branch Deep Links simple.

Create Content Reference

The BranchUniversalObject (BUO) class is a central concept in Branch event tracking and logging. You can create a BUO instance and fill in its properties in the following way:

BranchUniversalObject buo = new BranchUniversalObject();
buo.canonicalIdentifier = "id12345";
buo.title = "id12345 title";
buo.contentDescription = "My awesome piece of content!";
buo.imageUrl = "https://s3-us-west-1.amazonaws.com/branchhost/mosaic_og.png";
buo.metadata.AddCustomMetadata("foo", "bar");

Create Deep Link

To create a Branch Deep Link, start by creating a link properties object with new BranchLinkProperties(); and adding relevant data to it. Then pass that object, as well as a BUO instance, to the GetShortUrl() method to actually create the link.

You can verify Branch Deep Link creation in the Liveview section of the Branch Dashboard.

BranchLinkProperties linkProperties = new BranchLinkProperties();
linkProperties.tags.Add("tag1");
linkProperties.tags.Add("tag2");
linkProperties.feature = "sharing";
linkProperties.channel = "facebook";
linkProperties.controlParams.Add("$desktop_url", "http://example.com");

Branch.GetInstance().GetShortURL(callback,
                                  universalObject,
                                  linkProperties);

Share Deep Link

The ShareLink() method will generate a Branch Deep Link and tag it with the channel the user selects. You will need to pass this method a BUO instance and a link properties object.

Branch.GetInstance().ShareLink (callback,
           universalObject,
           linkProperties,
           message)

Read Deep Link

Reading a Branch Deep Link means retrieving properties about that specific Deep Link.

Please note that Branch recommends receiving data from the listener to prevent a race condition.

// Get the parameters used the most recent time this user was referred
Dictionary<string, object> sessionParams = Branch.GetInstance().GetLatestReferringParams();

// Get the parameters used the first time this user was referred
Dictionary<string, object> installParams = Branch.GetInstance().GetFirstReferringParams();

Deferred Deep Linking

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

🚧

Prerequisites

Make sure you are on v7.1.2+

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

To use the iOS pasteboard, implement one of the pasteboard opt-in options.

Track Events

Branch SDK event tracking methods allow you to log events that take place in your app.

Before tracking events with Branch, you'll want to familiarize yourself with the concept of a Branch Universal Object (BUO).

You can use the Branch Dashboard to verify that your Branch Events are being captured correctly.

Track Commerce Events

Commerce events describe events that relate to a customer interacting with your products and whether those interactions convert to a purchase. That conversion would be represented by a PURCHASE event. Other commerce events include things like adding payment information and viewing products.

You can track commerce event by creating a BUO for each product that is associated with the event you're tracking.

From there, add the BUO to the tracked event with AddContentItem, and use the right predefined BranchEventType for the event you want to track:

BranchUniversalObject universalObject = new BranchUniversalObject();
buo.canonicalIdentifier = "id12345";
buo.canonicalUrl = "https://branch.io/item/id12345";
buo.title = "Item 12345";
buo.contentDescription = "My awesome piece of content!";
buo.imageUrl = "https://s3-us-west-1.amazonaws.com/branchhost/mosaic_og.png";

buo.metadata.price = (float)23.20;
buo.metadata.quantity = 1;
buo.metadata.sku = "1994329302";
buo.metadata.productName = "my_product_name1";
buo.metadata.productBrand = "my_product_brand1";
buo.metadata.productCategory = 				        BranchProductCategory.APPAREL_AND_ACCESSORIES;
buo.metadata.productVariant = "XL";
buo.metadata.condition = BranchCondition.NEW;
buo.metadata.AddCustomMetadata("foo", "bar");

BranchEvent branchCommerceEvent = new BranchEvent(BranchEventType.PURCHASE);
branchCommerceEvent.SetAlias("new_user_purchase");
branchCommerceEvent.AddContentItem(buo); 
branchCommerceEvent.SetRevenue((float)1.5);
branchCommerceEvent.SetShipping((float)10.5);
branchCommerceEvent.SetCurrency(BranchCurrencyType.USD);
branchCommerceEvent.SetTax((float)12.3);

Branch.GetInstance().SendEvent(branchCommerceEvent);

Track Content Events

Content events occur when a user engages with your in-app content. This includes user searches, content viewing, content rating, and sharing. This can apply to a wide variety of in-app content, such as blog posts, music, videos, pictures, and e-commerce catalogue items.

BranchEvent branchContentEvent = new BranchEvent(BranchEventType.SEARCH);
branchContentEvent.SetAlias("my_custom_alias");
branchContentEvent.SetDescription("Product Search");
branchContentEvent.SetSearchQuery("user search query terms for product xyz");
branchContentEvent.AddCustomData("content_event_property_key1", "content_event_property_val1");

Branch.GetInstance().SendEvent(branchContentEvent);

Track Lifecycle Events

Lifecycle events represent actions the user takes in your app to continue progressing through it. These events can apply to game apps as well as non-game apps, and includes actions like a user completing a profile, registering for something, or going through a tutorial.

BranchEvent branchLifecycleEvent = new BranchEvent(BranchEventType.COMPLETE_REGISTRATION);
branchLifecycleEvent.SetAlias("registration_flow_xyz"); branchLifecycleEvent.SetDescription("Existing User Registration");
branchLifecycleEvent.AddCustomData("lifeycle_event_property_key1", "lifecycle_event_property_val1");

Branch.GetInstance().SendEvent(branchLifecycleEvent);

Track Custom Events

If you want to track an event that isn't predefined, you have the option to create a custom event.

Important: Branch strongly recommends using custom event names that contain no more than 40 characters, contain only letters, numbers, hyphens, spaces and underscores, and do not start with a hyphen.

BranchEvent branchCustomEvent = new BranchEvent("custom_event");
branchCustomEvent.SetAlias("custom_event_alias");
branchCustomEvent.SetDescription("Custom Event Description");
branchCustomEvent.AddCustomData("custom_event_property_key1", "custom_event_property_val1");
branchCustomEvent.AddCustomData("custom_event_property_key2", "custom_event_property_val2");

Branch.GetInstance().SendEvent(branchCustomEvent);

Set User Tracking

You can set the identity of a user with the SetIdentity() method. This method sets the identity of a user (ID, UUID, etc.) for events, deep links, and referrals.

You can validate that user identities are being set properly using the Branch Dashboard.

Branch branch = Branch.GetInstance ();
branch.SetIdentity("the user id", this);  // Where this implements IBranchIdentityInterface
branch.Logout(this); // Where this implements IBranchIdentityInterface

Troubleshoot

Xamarin: Troubleshooting

MAUI: Troubleshooting