腾讯Bugly Unity3D Plugin使用指南

概述

Bugly Unity Plugin是专为基于Unity引擎开发的跨移动平台(iOS/Android)游戏APP而开发的异常监控插件，它能够自动捕获Unity项目中脚本（如JavaScript、C#）和本地代码（如Objective-C、Java）抛出的异常，并提供实时、准确的错误分析服务。

准备工作 如果你之前已经在[Bugly]或[腾讯移动开放平台]注册了应用，并获取到AppID，可以继续使用它。如果你尚未注册应用，可以通过QQ登录Bugly网站，点击”用户名”，选择”我的App”，点击[注册新App]，填写完应用基本信息完成注册，即可得到Bugly AppID。 注意： 导出的Android和iOS项目分别需要注册两个不同的AppID

通用部分集成步骤

1、下载并导入Bugly Unity Plugin到Unity项目工程

下载最新版本[Bugly Unity Plugin]，双击.unitypackage文件，即可导入Bugly Unity Plugin的相关文件到您的Unity工程中。

如果你已经接入过Bugly的SDK，你可以只导入.cs和.dll文件，然后在网站上下载最新的SDK版本替换即可。 注意:

请根据项目的支持平台选择导入Android或iOS目录
导入过程文件如果已经存在不会进行覆盖，所以更新版本时，请务必先删除插件的内容

2、初始化Bugly

选择第一个或主场景(Scene)，在任意脚本文件(建议选择较早加载的脚本)中调用如下代码进行初始化。

    // 开启SDK的调式开关        
    Bugly.EnableLog (true);    // 设置C#堆栈日志捕获的级别，默认为Exception，可以选择为Assert、Error等
    Bugly.RegisterHandler (LogSeverity.Exception);    
    #if UNITY_IPHONE
    // 设置版本
    Bugly.SetAppVersion ("1.0(12)");    // 设置渠道
    Bugly.SetChannel ("bugly_channel");    // 使用AppID初始化SDK
    Bugly.InitSDK ("bugly_appid"); 
    #endif      

    #if UNITY_ANDROID
    Bugly.SetAppVersion ("1.0");
    Bugly.SetChannel ("bugly_channel");
    Bugly.SetReportDelayTime("0");    // 使用AppID初始化SDK
    Bugly.InitSDK ("bugly_appid");    
    #endif

    // 如果你已经在Unity项目导出的Android或iOS工程中进行了SDK的初始化，则只需调用此方法完成C#堆栈捕获功能的开启
    Bugly.EnableExceptionHandler();

3、挂载脚本并初始化

您也可以采用此方法初始化Bugly，如果您采用步骤2的方法在代码中初始化，请忽略此步骤!

3.1. 挂接Bugly组件(Component)到主场景的游戏对象

选择第一个或主场景(Scene)，新建一个空游戏对象(GameObject)，命名为Bugly
打开Plugins目录，将BuglyInit.cs脚本文件拖动到新建的游戏对象上进行脚本挂接（或菜单栏选择 Component -> Scripts -> com.tencent.bugly.unity3d -> BuglyInit）

3.2. 配置应用的App ID

最后，在检查器(Inspector)界面中配置Bugly组件的初始化信息（包括应用的Bugly AppID、版本、渠道等）

你可以在Bugly网站的[应用配置]页面中查看注册应用的App ID

iOS部分集成步骤

导出iOS项目时，必须修改如下设置项才能让未处理的异常(Uncaught Exceptions)被捕获上报

1、在Unity中修改项目的编译设置(Build Settings)

按下Ctrl+Shift+B打开Build Settings面板，点击Player Settings …，切换到Setting for iOS选项卡，选择Other Settings栏，修改Optimization配置项Script Call Optimization的值为Slow and Safe

2、在XCode中修改导出的iOS工程的编译配置

此部分的配置你可以参考[iOS SDK接入指南]

在TARGETS下选择编译的目标配置，切换到Build Settings选项卡，修改配置如下： Enable Objective-C Exceptions = YES Enable C++ Exceptions = YES Enable C++ Runtime Types = Yes
切换到Build Phases选项卡，在Link Binary With Libraries栏目下添加如下依赖项： libz.dylib - 用于对上报数据进行压缩 libstdc++.dylib - 用于支持c++，如果你的项目需依赖libc++.dylib，请更新替换framework Security.framework - 用于存储keychain SystemConfiguration.framework - 用于读取异常发生时的系统信息 CFNetwork.framework - 用于读取网络状态和网络访问 注意：如果项目已经添加过这些依赖项，请勿重复添加

至此，Unity项目的iOS工程配置完成。你可以在Unity中触发C#的异常验证崩溃上报功能。注意：请在真机上进行调式验证。

Android部分集成步骤

导出Android项目时，请修改如下配置：

1、在Unity中修改项目导出的选项

按下Ctrl+Shift+B打开Build Settings面板，选择Android平台，勾选Development Build 和 Script Debugging选项
点击Player Settings …，切换到Setting for Android选项卡，选择Other Settings栏，确认Internet Access是否置为Require状态

2、在Eclipse/ADT-Bundle IDE中修改Android工程的配置文件

此部分的配置你可以参考[Android SDK接入指南] 修改导出的Android工程的AndroidManifest.xml文件中的权限声明，添加如下权限：

  <!-- 网络通信-->
  <uses-permission android:name="android.permission.INTERNET" />
  <!-- 获取网络状态 -->
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  <!-- 获取MAC地址-->
  <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
  <!-- 获取设备信息 -->
  <uses-permission android:name="android.permission.READ_PHONE_STATE" /> 
  <!-- 可选的权限： -->
  <!-- 获取logcat日志 -->
  <uses-permission android:name="android.permission.READ_LOGS" />

注意：如果权限声明已经添加，请勿重复加入

至此，Unity项目的Android工程配置完成。你可以在Unity项目中触发C#的异常进行测试验证。注意：请在真机上进行调式验证。

API列表

1、通用接口

Bugly.InitSDK(string)

初始化Bugly SDK，传入Bugly注册得到的 App ID

Bugly.EnableLog(bool)

是否开启SDK的日志打印，如果开启，则会打印sdk的调式信息，默认关闭。请在调式阶段打开，发布版本中关闭。在初始化方法之前调用。

Bugly.SetAppVersion(string)

设置应用的版本，如果不设置，默认取工程的配置在初始化方法之前调用。

Bugly.SetChannel(string)

设置应用的渠道名。在初始化方法之前调用。

Bugly.SetUserId(string)

设置用户标识，如果不设置，默认为10000 在初始化方法之后调用。

Bugly.RegisterHandler(LogSeverity)

设置捕获C#堆栈的级别，默认为Exception，即Exception的堆栈日志才会捕获上报。

Bugly.HandleException(Exception)

主动上报C#的异常

Bugly.SetGameObjectForCallback(string)

设置处理回调的游戏对象

2、iOS专用接口

Bugly.SetBundleId(string)

设置应用bundle id，默认读取工程的配置

Bugly.SetDeviceId(string)

设置设备的标识，默认由SDK计算open uuid

Bugly.EnableCrashAndSymbolicateInProcess(bool, bool)

是否开启异常合并上报和进程内堆栈还原，默认关闭。如果开启异常合并，同一天同一异常只会上报一次。

Bugly.SetCrashHappenCallback(string)

设置异常发生回调处理

Bugly.SetUserData(string, string)

添加用户自定义数据上报

3、Android专用接口

Bugly.SetReportDelayTime(string)

设置启动上报时的延时时间，单位毫秒