Xamarin Android

Google Play服务版本17+

如果引用谷歌Play服务版本17或更高版本, MUST 完整的谷歌秒的更新说明这里

由于Google Play服务于2019年6月进行了重大更改,未完成更新步骤将导致Branch的Android SDK(以及其他各种跨平台SDK,例如Unity)停止收集我们用来确保准确的深度链接接的Android AID和归因。

如果您运行的Google Play服务版本低于17,则无需更新。

配置 Branch

图像
图像

安装 Branch

NuGet

Branch Xamarin SDK可作为NuGet软件包提供。必须将BranchNuGet程序包添加到每个将使用Branch方法的Xamarin项目中。

要将Branch NuGet包添加到项目中:

  1. 右键点击每个项目,然后选择 Add > Add NuGet Packages
  2. 如果尚不存在,请找到Microsoft BCL Build Components 软件包版本1.0.21并将其添加到项目中
  3. 找到Branch Xamarin SDK 软件包版本3.0并将其添加到项目中

手动地

如果不想使用NuGet而是直接构建和引用Branch程序集:

  1. 将此存储库克隆到本地计算机: https://github.com/BranchMetrics/xamarin-branch-deep-linking.git
  2. Branch-Xamarin-SDK 项目添加到解决方案中,并从Android,iOS和Forms(如果适用)项目中引用它
  3. Branch-Xamarin-SDK.Droid 项目添加到解决方案中,并从Android项目中引用(如果有)
  4. 添加Branch-Xamarin-SDK.iOS 项目并从iOS项目中引用(如果有)

配置应用

确保Android项目未使用Shared Mono Runtime

  1. 右键点击Android项目,然后选择: Options
  2. 选择: Android Build
  3. General 标签上,取消选中: Use Shared Mono Runtime

在app的清单文件中添加app功能

所需的权限AndroidManifest.xml ,配置以下权限:

  • AccessNetworkState
  • Internet

关于Android清单的其他阅读:

将应用的Branch键添加到Strings.xml文件

将Branch键添加到Android项目Resources/values/Strings.xml 文件。该文件包含可由app的Application类访问的值。

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <string name="app_name">TestXamarinFormsApp</string>
  <string name="branch_key">key_live_liAnF8k7gZUEZv76Rt9a4bffAzlC5zVW</string>
</resources>

初始化 Branch

*创建项目' s Application.cs *类

  1. 右键点击.Droid项目,然后选择 Add > New File...
  2. 选择: General > Empty File
  3. 命名文件: Application.cs
  4. 输入以下代码(将' TestAndroidApp '替换为应用程序的实际名称):
using System;
using Android.App;
using Android.Content;
using Android.Runtime;
using BranchXamarinSDK;

namespace TestAndroidApp.Droid
{
    [Application(AllowBackup = true, Icon = "@mipmap/icon", Label = "@string/app_name")]
    [MetaData("io.branch.sdk.auto_link_disable", Value = "false")]
    [MetaData("io.branch.sdk.TestMode", Value = "true")]
    [MetaData("io.branch.sdk.BranchKey", Value = "@string/branch_key")]

    public class TestAndroidApp : Application
    {
        public TestAndroidApp(IntPtr javaReference, JniHandleOwnership transfer) : base(javaReference, transfer)
        {
        }

        public override void OnCreate()
        {
            base.OnCreate();
            BranchAndroid.GetAutoInstance(this.ApplicationContext);
        }
    }
}
Key
io.branch.sdk.TestMode 将此参数设置为 true 启用Debug Mode,这将导致简单的卸载/重新安装应用程序来触发 install 事件。在部署到生产环境之前,请确保禁用此功能。请注意,如果已在项目中添加了该功能,则在Android上启用“调试模式”也会强制该应用使用“ Branch Test 键。使用 Test 键运行的应用程序将无法从使用 Live 键创建的Branch链接接收数据。
io.branch.sdk.BranchKey 应用的Branch键。 Live 键和 Test 键都可以添加到Strings.xml文件中。启用测试模式后,如果已指定测试键,则应用将自动使用测试键。

创建一个活动来处理Branch事件:BranchActivity

  1. 右键点击.Droid项目,然后选择 Add > New File...
  2. 选择: Android > Activity
  3. 重命名文件: BranchActivity.cs
  4. 输入以下代码(将' TestAndroidApp '替换为应用程序的实际名称):
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Newtonsoft.Json;
using BranchXamarinSDK;

using Android.App;
using Android.Content;
using Android.OS;
using Android.Runtime;
using Android.Views;
using Android.Widget;

namespace TestAndroidApp.Droid
{
    [Activity(Label = "BranchActivity")]
    public class BranchActivity : Activity

    {
        private string logString = "";

        protected override void OnCreate(Bundle savedInstanceState)
        {
            base.OnCreate(savedInstanceState);

            LogMessage("Branch initialization completed: ");

            Dictionary<string, object> data = JsonConvert.DeserializeObject<Dictionary<string, object>>(Intent.GetStringExtra("BranchData"));
            foreach (var key in data.Keys)
            {
                LogMessage(key + " : " + data[key].ToString());
            }
        }

        #region Utils

        void LogMessage(string message)
        {
            Console.WriteLine(message);
            logString += DateTime.Now.ToLongTimeString() + "> " + message + "\n";
        }

        #endregion
    }
}

创建一个活动来处理Branch错误:BranchErrorActivity

  1. 右键点击.Droid项目,然后选择 Add > New File...
  2. 选择: Android > Activity
  3. 重命名文件: BranchErrorActivity.cs
  4. 输入以下代码(将' TestAndroidApp '替换为应用程序的实际名称):
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

using Android.App;
using Android.Content;
using Android.OS;
using Android.Runtime;
using Android.Views;
using Android.Widget;

namespace TestAndroidApp.Droid
{
    [Activity(Label = "BranchErrorActivity")]
    public class BranchErrorActivity : Activity
    {
        private string logString = "";

        protected override void OnCreate(Bundle savedInstanceState)
        {
            base.OnCreate(savedInstanceState);

            LogMessage("Branch initialization failed");
            LogMessage("Error code: " + Intent.Extras.GetInt("ErrorCode").ToString());
            LogMessage(Intent.Extras.GetString("ErrorMessage"));
        }

        #region Utils

        void LogMessage(string message)
        {
            Console.WriteLine(message);
            logString += DateTime.Now.ToLongTimeString() + "> " + message + "\n";
        }

        #endregion
    }
}

初始化Branch并配置Branch会话管理

必须在Application类或应用程序启动的第一个Activity的OnCreate方法中初始化分支。当应用由于分支链接单击而激活时,必须添加OnNewIntent方法以检索最新的链接标识符。

如果初始化成功,则将调用InitSessionComplete方法。如果初始化失败,则将调用SessionRequestError方法。深层链接路由逻辑应位于InitSessionComplete方法中。

在下面的代码示例中,以下Branch初始化和会话管理步骤已添加到MainActivity.cs中:

  • 响应应用程序的URI方案的活动
  • 活动以singleTask 模式启动
  • 重写OnCreate方法并初始化Branch SDK
  • 重写OnNewIntent方法
  • 添加一个InitSessionComplete方法来处理Branch链接信息(这是深链接路由代码所在的位置)
  • 添加SessionRequestError方法以处理Branch无法初始化的情况
using Android.App;
using Android.Widget;
using Android.OS;
using BranchXamarinSDK;
using System;
using System.Collections.Generic;
using Android.Content;
using Newtonsoft.Json;

namespace TestAndroidApp.Droid
{
    [Activity(Label = "TestAndroidApp", MainLauncher = true, Icon = "@mipmap/icon", LaunchMode = Android.Content.PM.LaunchMode.SingleTask)]

    [IntentFilter(new[] { "android.intent.action.VIEW" },
    Categories = new[] { "android.intent.category.DEFAULT", "android.intent.category.BROWSABLE" },
    DataScheme = "testandroidapp",
    DataHost = "open")]

    [IntentFilter(new[] { "android.intent.action.VIEW" },
    Categories = new[] { "android.intent.category.DEFAULT", "android.intent.category.BROWSABLE" },
    DataScheme = "https",
    DataHost = "testandroidapp.app.link")]

    [IntentFilter(new[] { "android.intent.action.VIEW" },
    Categories = new[] { "android.intent.category.DEFAULT", "android.intent.category.BROWSABLE" },
    DataScheme = "https",
    DataHost = "testandroidapp-alternate.app.link")]

    public class MainActivity : Activity, IBranchSessionInterface
    {

        protected override void OnCreate(Bundle savedInstanceState)
        {
            base.OnCreate(savedInstanceState);

            BranchAndroid.Init(this, Resources.GetString(Resource.String.branch_key), this);
        }

        // Ensure we get the updated link identifier when the app becomes active
        // due to a Branch link click after having been in the background
        protected override void OnNewIntent(Intent intent)
        {
            this.Intent = intent;
        }

        public void InitSessionComplete(Dictionary<string, object> data)
        {
            //Handle custom logic based on deep link data in InitSessionComplete

            //View all the link data in the console
            Console.WriteLine("My Link Data: " + JsonConvert.SerializeObject(data));

                       //Preferred method: use BranchActivity created previously to handle the link data
            //Will need to update BranchActivity with desired custom logic, to open the correct page in the app
            (this, typeof(BranchActivity));
            intent.PutExtra("BranchData", JsonConvert.SerializeObject(data));

            StartActivity(intent);var intent = new Intent
        }

        public void SessionRequestError(BranchError error)
        {
            Console.WriteLine("Branch session initialization error: " + error.ErrorCode);
            Console.WriteLine(error.ErrorMessage);

            var intent = new Intent(this, typeof(BranchErrorActivity));
            intent.PutExtra("ErrorCode", error.ErrorCode);
            intent.PutExtra("ErrorMessage", error.ErrorMessage);

            StartActivity(intent);
        }
    }
}

使用Xamarin表单配置Branch

将C#项目的配置文件更改为PCL 4.5-Profile78

  1. 右键点击项目名称,然后选择: Options
  2. 浏览菜单至 Build > General
  3. Current Profile 更改为: PCL 4.5 - Profile78

使用NuGet添加Branch SDK

Branch Xamarin SDK可作为NuGet软件包提供。必须将BranchNuGet程序包添加到每个将使用Branch方法的Xamarin项目中。

  1. 右键点击每个项目,然后选择 Add > Add NuGet Packages
  2. 如果尚不存在,请找到Microsoft BCL Build Components 软件包版本1.0.21并将其添加到项目中
  3. 找到Branch Xamarin SDK 软件包版本3.0并将其添加到项目中

创建用于Branch会话处理的类

Branch异步初始化,在对Branch进行网络调用后返回Branch链接参数。如果初始化成功,则将调用InitSessionComplete方法。如果初始化失败,则将调用SessionRequestError方法。深度链接接路由逻辑应位于InitSessionComplete方法中。

  1. 右键点击C#项目,然后选择 Add > New File...
  2. 选择: General > Empty Class
  3. 重命名文件: TestXamarinFormsApp.cs
  4. 输入以下代码(将' TestXamarinFormsApp '替换为应用程序的实际名称):
using BranchXamarinSDK;
using System.Collections.Generic;
using System.ComponentModel;
using Xamarin.Forms;

namespace TestXamarinFormsApp
{
    public class TestXamarinFormsApp : Application, IBranchSessionInterface
    {

        public TestXamarinFormsApp()
        {
        }

        #region IBranchSessionInterface implementation

        public void InitSessionComplete(Dictionary<string, object> data)
        {
        }

        public void CloseSessionComplete()
        {
        }

        public void SessionRequestError(BranchError error)
        {
        }

        #endregion
    }
}

创建一个用于处理链接数据的类

Branch将链接数据存储在称为Branch Universal ObjectBUO

  1. 右键点击C#项目,然后选择 Add > New File...
  2. 选择: General > Empty Class
  3. 重命名文件: TestXamarinFormsAppBUO.cs
  4. 输入以下代码(将' TestXamarinFormsApp '替换为应用程序的实际名称):
using BranchXamarinSDK;
using System.Collections.Generic;
using System.ComponentModel;
using Xamarin.Forms;

namespace TestXamarinFormsApp
{
    public class TestXamarinFormsAppBUO : Application, IBranchBUOSessionInterface
    {

        public TestXamarinFormsAppBUO()
        {
        }

        #region IBranchBUOSessionInterface implementation

        public void InitSessionComplete(BranchUniversalObject buo, BranchLinkProperties blp)
        {
        }

        public void SessionRequestError(BranchError error)
        {
        }

        #endregion
    }
}

确保Android项目未使用Shared Mono Runtime

  1. 右键点击Android项目,然后选择: Options
  2. 选择: Android Build
  3. General 标签上,取消选中: Use Shared Mono Runtime

在AndroidManifest.xml文件中添加应用程序功能

所需的权限AndroidManifest.xml ,配置以下权限:

  • AccessNetworkState
  • 互联网

有关Android清单的更多阅读

将应用的Branch键添加到Strings.xml文件

创建一个Resources/values/Strings.xml 文件,可以由应用程序访问中的应用级的Android项目,并添加Branch关键文件。

  1. 在Android项目中,浏览到 Resources/values
  2. 右键点击values 文件夹,然后选择: Add > New File...
  3. 选择: XML > Empty XML File
  4. 命名文件: Strings
  5. 输入以下值:
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="app_name">TestXamarinFormsApp</string>
    <string name="branch_key">key_live_liAnF8k7gZUEZv76Rt9a4bffAzlC5zVW</string>
</resources>

配置.Droid项目的应用程序类

在.Droid项目的Application类中:

  • 设置Branch SDK 的初始化参数
  • 覆盖OnCreate() 方法以调用BranchAndroid.GetAutoInstance

如果该项目尚不存在Appplication类,请创建一个:

  1. 右键点击.Droid项目,然后选择: Add > New File...
  2. 选择: General > Empty Class
  3. 将该文件命名为: {app name} (例如' TestXamarinFormsApp ' )

该文件应具有以下内容:

using System;
using Android.App;
using Android.Content;
using Android.Runtime;
using BranchXamarinSDK;

namespace TestXamarinFormsApp.Droid
{

    [Application (AllowBackup = true, Icon = "@drawable/icon", Label = "@string/app_name")]
    [MetaData("io.branch.sdk.auto_link_disable", Value = "false")]
    [MetaData("io.branch.sdk.TestMode", Value = "true")]
    [MetaData("io.branch.sdk.BranchKey", Value = "@string/branch_key")]

    public class App : Application
    {
        public App(IntPtr javaReference, JniHandleOwnership transfer) : base(javaReference, transfer)
        {
        }

        public override void OnCreate()
        {
            base.OnCreate();
            BranchAndroid.GetAutoInstance(this.ApplicationContext);
        }
    }
}
Key
io.branch.sdk.TestMode 将此参数设置为 true 启用Debug Mode,这将导致简单的卸载/重新安装应用程序来触发 install 事件。在部署到生产环境之前,请确保禁用此功能。请注意,如果已在项目中添加了该功能,则在Android上启用“调试模式”也会强制该应用使用“ Branch Test 键。使用 Test 键运行的应用程序将无法从使用 Live 键创建的Branch链接接收数据。
io.branch.sdk.BranchKey 应用的Branch键。 Live 键和 Test 键都可以添加到Strings.xml文件中。启用测试模式后,如果已指定测试键,则应用将自动使用测试键。

初始化 Branch

必须在Application类或应用程序启动的第一个Activity的OnCreate方法中初始化分支。当应用由于分支链接单击而激活时,必须添加OnNewIntent方法以检索最新的链接标识符。

在下面的代码示例中,以下Branch初始化和会话管理步骤已添加到MainActivity.cs中:

  • 注册一个活动以响应应用的URI方案
  • 确保活动以singleTask 模式启动
  • 重写OnCreate方法并初始化Branch SDK
  • 重写OnNewIntent方法
using System;

using Android.App;
using Android.Content;
using Android.Content.PM;
using Android.Runtime;
using Android.Views;
using Android.Widget;
using Android.OS;

using BranchXamarinSDK;
using TestXamarinFormsApp;

namespace TestXamarinFormsApp.Droid
{
    [Activity(Label = "TestXamarinFormsApp.Droid", LaunchMode = LaunchMode.SingleTask, Icon = "@drawable/icon", Theme = "@style/MyTheme", MainLauncher = true, ConfigurationChanges = ConfigChanges.ScreenSize | ConfigChanges.Orientation)]

    [IntentFilter(new[] { "android.intent.action.VIEW" },
        Categories = new[] { "android.intent.category.DEFAULT", "android.intent.category.BROWSABLE" },
        DataScheme = "testxamarinformsapp",
        DataHost = "open")]

    [IntentFilter(new[] { "android.intent.action.VIEW" },
        Categories = new[] { "android.intent.category.DEFAULT", "android.intent.category.BROWSABLE" },
        DataScheme = "https",
        DataHost = "testxamarinformsapp.app.link")]

    public class MainActivity : global::Xamarin.Forms.Platform.Android.FormsApplicationActivity
    {
        protected override void OnCreate(Bundle savedInstanceState)
        {
            base.OnCreate(savedInstanceState);

            global::Xamarin.Forms.Forms.Init(this, savedInstanceState);

            TestXamarinFormsAppBUO linkData = new TestXamarinFormsAppBUO();
            BranchAndroid.Init(this, GetString(Resource.String.branch_key), linkData);
            LoadApplication(linkData);
        }

        protected override void OnNewIntent(Intent intent)
        {
            this.Intent = intent;
        }
    }
}

实现功能

创建内容引用

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

创建深度链接

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

分享深度链接

ShareLink (IBranchLinkShareInterface callback,
           BranchUniversalObject universalObject,
           BranchLinkProperties linkProperties,
           string message)

读取深度链接

  • 从深度链接中提取 Branch 数据

  • 最佳做法是从listener 接收数据(以防止出现race condition)

  • 返回深度链接属性

// latest
Dictionary<string, object> sessionParams = Branch.GetInstance().GetLatestReferringParams();

// first
Dictionary<string, object> installParams = Branch.GetInstance().GetFirstReferringParams();

跟踪用户

  • 设置事件、深度链接和推荐的用户标识(电子邮件、ID 和 UUID 等)

  • 使用 Branch 控制面板进行验证

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

跟踪事件

  • 注册自定义事件

  • 这些事件命名opencloseinstall ,和referred session 都是Branch预留的

  • 最佳方式之前跟踪用户跟踪事件以将自定义事件与用户相关联

  • 使用 Branch 控制面板进行验证

Branch branch = Branch.GetInstance ();
branch.LogEvent("the_custom_event");

追踪商业事件

  • 注册自定义商务活动

  • CurrencyCategory使用跟踪商务属性

  • 使用 Branch 控制面板进行验证

Branch branch = Branch.GetInstance ();
Dictionary<string, object> data = new Dictionary<string, object>();
data.Add("sku", "123456789");
branch.LogEvent("purchase_event", data);

测试应用

此存储库中包含四个功能齐全的演示应用程序:适用于iOS和Android平台的Xamarin Native和Xamarin Forms应用程序。将这些应用程序用作集成Branch SDK的参考模型。

  • Testbed-Xamarin (Native apps)

  • Testbed-XamarinForms (Forms apps)

解决问题

测试深度链接 Android

  • Branch营销仪表板创建深度链接接

  • 从设备中删除您的应用程序

  • 使用Android Studio编译您的应用

  • 粘贴深度链接到 Google Hangouts

  • 点击深度链接打开您的应用

无法将Branch所需的NuGet软件包添加到C#项目

如果尚未配置要使用的NuGet程序包,则可能无法将其添加到C#项目中 PCL 4.5 - Profile78

  1. 右键点击项目名称,然后选择: Options
  2. 浏览菜单至 Build > General
  3. Current Profile 更改为: PCL 4.5 - Profile78

Android应用无法构建并出现链接错误

添加Branch Xamarin SDK NuGet包后,Newtonsoft JSON NuGet包将自动添加到项目中。此软件包存在一个已知问题,导致在构建项目时链接错误。

错误XA0009:加载程序集时出错:/Users/david/Projects/TestXamarinFormsApp/Droid/obj/Debug/android/assets/mscorlib.dll

要使用Newtonsoft JSON NuGet包解决此问题,请执行以下操作:

  1. 右键点击项目,然后选择选项
  2. 转到Android Build 并选择Linker 标签
  3. 选择: Release
  4. 转到Ignore assemblies
  5. 加: System.Core
  6. 重建应用

4个月前更新

Xamarin Android


建议的编辑仅限于API参考页

您只能建议对Markdown正文内容进行修改,而不能建议对API规范进行修改。