Skip to content

Unity Application Integration

Collect metrics data from Unity applications and analyze application performance through visualization.

Reading Path

Prerequisites

Note

If the RUM Headless service has been activated, the prerequisites are automatically configured, and you can proceed directly with application integration.

Application Integration

  1. Navigate to RUM > Create > Android/iOS
  2. Create two separate applications for Unity Android and Unity iOS to receive RUM data from the Android and iOS platforms respectively
  3. Enter the corresponding application name and application ID for each platform's application

  4. Choose the application integration method:

    • Public DataWay: Directly receives RUM data without installing the DataKit collector
    • Local Environment Deployment: Receives RUM data after meeting the prerequisites

Installation

Source Code Address: https://github.com/GuanceCloud/datakit-unity

Demo Address: https://github.com/GuanceCloud/datakit-unity/blob/dev/Assets/Scenes

  1. Download the latest ft-sdk-unity.unitypackage
  2. Import ft-sdk-unity.unitypackage via Assets -> Import Package -> Custom Package...
  3. Add the JSON parsing third-party library "com.unity.nuget.newtonsoft-json", which can be done in Package Manager -> Add Package by name ...
  4. Drag FTSDK.prefab to the first scene page and initialize the SDK within the _InitSDK method in FTSDK.cs
  5. Drag FTViewObserver.prefab to other scene pages to monitor the page View lifecycle, as well as application suspension and resumption
  6. Monitor and convert Unity crash data and regular log data via Application.logMessageReceived. For examples, refer to Quick Start and Custom Data Collection Rules
Assets/Plugins
├── Android
│   ├── FTUnityBridge.java                // Android bridge
│   ├── InnerClassProxy.java              // Android Inner Setting Proxy
│   ├── ft-sdk-release.aar                // Android SDK
│   ├── gson-2.8.5.jar                    // Android SDK dependent third-party library
├── iOS
│   ├── FTMobileSDK.xcframework           // iOS SDK
│   ├── FTUnityBridge.mm                  // iOS bridge
├── FTSDK.cs                              // Script bound to FTSDK.prefab
├── FTSDK.prefab                          // SDK initialization prefab
├── FTUnityBridge.cs                      // Unity bridge connecting iOS, Android, and other platform methods
├── FTViewObserver.cs                     // Script bound to FTViewObserver.prefab
├── FTViewObserver.prefab                 // View page monitoring prefab
├── UnityMainThreadDispatcher.cs          // Script bound to UnityMainThreadDispatcher.prefab
├── UnityMainThreadDispatcher.prefab      // Main thread consumer queue prefab
  • If the native Android and iOS projects have already integrated the native SDK, you need to comment out the _InitSDK method to avoid duplicate settings. For specific scenarios, refer to Native and Unity Hybrid Development
  • iOS Plugin Inspector Settings: FTMobileSDK.xcframework is a dynamic library, and Add to Embedded Binaries must be checked. Selecting this option will cause Unity to set the Xcode project options to copy the plugin files into the final application bundle.

unity_ios_plugin_embedded

If the native SDK is already integrated, gson-2.8.5.jar, ft-sdk-release.aar for Android, and FTMobileSDK.framework for iOS can be removed from the Unity project. Android's OkHttp request and startup time-consuming features require the use of ft-plugin. For detailed configuration, see Android SDK.

Initialization Instructions

For a minimal initialization example, read Quick Start.

For a complete explanation of SDKConfig parameters, read SDK Initialization.

Detailed Configuration Entries

Custom Data Collection Rules

The Unity SDK currently primarily implements custom RUM data collection through manual method calls.

Action

Usage

/// <summary>
/// Add an Action
/// </summary>
/// <param name="actionName">action name</param>
/// <param name="actionType">action type</param>
public static void StartAction(string actionName, string actionType)

/// <summary>
/// Add an Action
/// </summary>
/// <param name="actionName">action name</param>
/// <param name="actionType">action type</param>
/// <param name="property">additional property parameters</param>
public static void StartAction(string actionName, string actionType, Dictionary<string, object> property)

/// <summary>
/// Add an Action
/// </summary>
/// <param name="actionName">action name</param>
/// <param name="actionType">action type</param>
public static void AddAction(string actionName, string actionType)

/// <summary>
/// Add an Action
/// </summary>
/// <param name="actionName">action name</param>
/// <param name="actionType">action type</param>
/// <param name="property">additional property parameters</param>
public static void AddAction(string actionName, string actionType, Dictionary<string, object> property)

Code Example

FTUnityBridge.StartAction("click", "test");

View

Usage

/// <summary>
/// Start View
/// </summary>
/// <param name="viewName">current page name</param>
public static void StartView(string viewName)

/// <summary>
/// Start View
/// </summary>
/// <param name="viewName">current page name</param>
/// <param name="property">additional property parameters</param>
public static void StartView(string viewName, Dictionary<string, object> property)

/// <summary>
/// Stop View
/// </summary>
public static void StopView()

/// <summary>
/// Stop View
/// </summary>
/// <param name="property">additional property parameters</param>
public static void StopView(Dictionary<string, object> property)

Code Example

FTUnityBridge.StartView("TEST_VIEW_ONE");

FTUnityBridge.StopView();

Resource

Usage

/// <summary>
/// Start resource
/// </summary>
/// <param name="resourceId">resource Id</param>
public static async Task StartResource(string resourceId)

/// <summary>
/// Start resource
/// </summary>
/// <param name="resourceId">resource Id</param>
/// <param name="property">additional property parameters</param>
public static async Task StartResource(string resourceId, Dictionary<string, object> property)

/// <summary>
/// Stop resource
/// </summary>
/// <param name="resourceId">resource Id</param>
public static async Task StopResource(string resourceId)

/// <summary>
/// Stop resource
/// </summary>
/// <param name="resourceId">resource Id</param>
/// <param name="property">additional property parameters</param>
public static async Task StopResource(string resourceId, Dictionary<string, object> property)

/// <summary>
/// Add network transmission content and metrics
/// </summary>
/// <param name="resourceId">resource Id</param>
/// <param name="resourceParams">data transmission content</param>
public static async Task AddResource(string resourceId, ResourceParams resourceParams)

ResourceParams

Method Name Type Required Description
url string Yes url address
requestHeader string No request header parameters, no format restrictions
responseHeader string No response header parameters, no format restrictions
responseConnection string No response connection
responseContentType string No response ContentType
responseContentEncoding string No response ContentEncoding
resourceMethod string No request method GET, POST, etc.
responseBody string No returned body content

Code Example

FTUnityBridge.StartResource(resourceId);

FTUnityBridge.StopResource(resourceId);

ResourceParams resourceParams = new ResourceParams();
resourceParams.url = url;
resourceParams.requestHeader = client.DefaultRequestHeaders.ToDictionary(header => header.Key, header => string.Join(",", header.Value));
resourceParams.responseHeader = response.Headers.ToDictionary(header => header.Key, header => string.Join(",", header.Value));
resourceParams.resourceStatus = (int)response.StatusCode;
resourceParams.responseBody = responseData;
resourceParams.resourceMethod = "GET";

FTUnityBridge.AddResource(resourceId, resourceParams);

Error

Usage

/// <summary>
/// Add error information
/// </summary>
/// <param name="log">log</param>
/// <param name="message">message</param>
public static async Task AddError(string log, string message)

/// <summary>
/// Add error information
/// </summary>
/// <param name="log">log</param>
/// <param name="message">message</param>
/// <param name="property">additional property parameters</param>
public static async Task AddError(string log, string message, Dictionary<string, object> property)

Code Example

void OnEnable()
{
    Application.logMessageReceived += LogCallBack;
}

void OnDisable()
{
    Application.logMessageReceived -= LogCallBack;
}

void LogCallBack(string condition, string stackTrace, LogType type)
{
    if (type == LogType.Exception)
    {
        FTUnityBridge.AddError(stackTrace, condition);
    }
}

LongTask

Usage

/// <summary>
/// Add a long-duration task
/// </summary>
/// <param name="log">log content</param>
/// <param name="duration">duration, in nanoseconds</param>
public static async Task AddLongTask(string log, long duration)

/// <summary>
/// Add a long-duration task
/// </summary>
/// <param name="log">log content</param>
/// <param name="duration">duration, in nanoseconds</param>
/// <param name="property">additional property parameters</param>
public static async Task AddLongTask(string log, long duration, Dictionary<string, object> property)

Code Example

FTUnityBridge.AddLongTask("long task test", 100002);

Advanced Scenarios

Frequently Asked Questions

Add Prefix to Variables to Avoid Conflicting Fields

To avoid conflicts between custom fields and SDK data, it is recommended to add a project abbreviation prefix to tag names, such as df_tag_name. The key values used in the project can be queried from the source code. When variables in the SDK global variables conflict with those in RUM or Log, the RUM and Log variables will override the global variables in the SDK.

Others