Ingest data using the Unity Plugin

This topic describes how to use the Unity Plugin to ingest crash and application data from mobile game apps on the Unity platform into Service Monitoring for Simple Log Service. Service Monitoring lets you monitor issues such as game crashes and Application Not Responding (ANR) errors in real time. It also supports intelligent analysis to help you identify various hidden risks in your application cost-effectively and efficiently.

Prerequisites

You have created a Service Monitoring application. For more information, see Add an application.

Step 1: Integrate the SDK

1. Download the latest version of the Unity Plugin.

2. Double-click the .unitypackage file to import the plugin files into your Unity project.

   The following table describes the folders in the .unitypackage file.

   File	Description
   Assets/Plugins/Unity4SLS	The Unity plugin scripts.
   Assets/Plugins/Unity4SLS/Android/libs	The software development kit (SDK) and Native Development Kit (NDK) that the Android platform depends on.
   Assets/Plugins/Unity4SLS/iOS/	The framework and static libraries that the iOS platform depends on.
   Assets/Scenes/	Sample scenes. You can delete them during integration.
   Assets/Scripts/	Sample scripts. You can delete them during integration.

Step 2: Initialize the SDK

Select the first or main scene. In any script file, call the following code to initialize the SDK. We recommend choosing a script that loads early.

// Initialize the credential information.
Credentials credentials = new Credentials();

#if UNITY_IPHONE || UNITY_IOS
credentials.instanceId = "Service Monitoring application (iOS) ID";
credentials.endpoint = "Endpoint of the project attached to the Service Monitoring application (iOS)";
credentials.project = "Project attached to the Service Monitoring application (iOS)";
#elif UNITY_ANDROID
credentials.instanceId = "Service Monitoring application (Android) ID";
credentials.endpoint = "Endpoint of the project attached to the Service Monitoring application (Android)";
credentials.project = "Project attached to the Service Monitoring application (Android)";
#endif

private void requestAccessKey() {
    // First, use the direct log upload service for mobile clients to configure the AccessKey information.
    // ...

    // After you obtain the AccessKey information, update it.
    updateAccessKey(accessKeyId, accessKeySecret, new-securityToken);
}

// Update the AccessKey information.
private void updateAccessKey(String accessKeyId, String accessKeySecret, String securityToken) {
    // An AccessKey obtained through the Security Token Service (STS) includes a security token. Update it as follows.
    Credentials credentials = new Credentials();
    credentials.accessKeyId = accessKeyID;
    credentials.accessKeySecret = accessKeySecret;
    credentials.securityToken = secretToken;

    Unity4SLS.SetCredentials(credentials);
}
// Initialize the Unity Plugin.
Unity4SLS.Initialize(credentials);

API list

FAQ

1. How do I obtain access credentials using STS and dynamically update them to the SDK?

Obtaining access credentials using STS prevents data breaches that can occur when you hardcode an AccessKey in your code. For more information, see Data collection - Build a direct log upload service for mobile clients.

After you obtain the access credentials using STS, update the information in the SDK as follows.

// Call the credential callback function. This function is called when the data writing or sending status changes, or when the credential becomes invalid or expires.
// feature: The plugin name. You can generally ignore this.
// result: The callback result.
public void credentialsCallback(string feature, string result)
{
    // During development, print logs to help with troubleshooting.
    Debug.Log("[Unity4SLS] <DEBUG> - credentialsCallback. feature: " + feature + ", result: " +  result);

    if ("LOG_PRODUCER_SEND_UNAUTHORIZED" == result || 
        "LOG_PRODUCER_PARAMETERS_INVALID" == result) {
    	  // LOG_PRODUCER_PARAMETERS_INVALID: The initial credential information is invalid.
        // LOG_PRODUCER_SEND_UNAUTHORIZED: The access credential has expired or is invalid.

         // If these two error codes occur, re-obtain the access credentials through STS and update them as follows.
         // 1. Obtain access credentials through STS.
         // 2. Update the credential information in the SDK.
        Credentials credentials = new Credentials();
        credentials.accessKeyId = accessKeyId;
        credentials.accessKeySecret = accessKeySecret;
        credentials.securityToken = securityToken;
        Unity4SLS.SetCredentials(credentials);
    }

}

// Call the following method to register the SDK's credential callback interface.
public void setCredentialsCallback()
{
    callback_delegate callback = new callback_delegate(credentialsCallback);
    Unity4SLS.RegisterCredentialsCallback(callback);
}

2. How do I collect exception information from scripts such as C# and Lua?

The Simple Log Service SDK does not automatically collect exceptions from scripts such as C# and Lua. You can refer to implementations in other products for guidance. After you collect the exception data, use the relevant APIs to report it. The following are examples:

• Report C# exception information

  Unity4SLS.ReportCSharpError("C# message", "C# stacktrace");

• Report Lua exception information

  Unity4SLS.ReportLuaError("lua message", "lua stacktrace");

• Report other types of exception information

  Unity4SLS.ReportError("stacktrace");
  Unity4SLS.ReportError("custom type, fill in based on your business needs", "stacktrace");
  Unity4SLS.ReportError("custom type, fill in based on your business needs", "message", "stacktrace");

3. How do I report custom business log information?

The SDK supports reporting custom business log information, including business data and log messages. The following is an example:

Unity4SLS.ReportCustomLog("custom type, fill in based on your business needs", "custom log 1");