SDK migration guide

Update your User Reporting implementation from version 1.0 to version 2.0 to access the latest features and updates.

Read time 3 minutes

Last updated a day ago

Important

Cloud Diagnostics is deprecated, and will be phased out in future versions of Unity. For more robust reports and device information, including information on Application Not Responding (ANR) errors for Android, use the diagnostics experience available in Unity 6.2 and later. For information about migrating from Cloud Diagnostics, refer to Migrate to Diagnostics in the Unity Dashboard.

The User Reporting SDK has been updated, affecting the entire API. Most significantly, the public API scope has been greatly reduced for development focus and support scope.

Warning

Critically this means if you're using the previous version of the SDK you won’t receive updates unless you move over to the new version. The old version might eventually become incompatible with future changes to the Unity Dashboard or User Reporting backend as we further develop new features.

User Reporting 1.0 refers to the old SDK; a reference distribution is available here. User Reporting 2.0 refers to the updated SDK available in the Unity Package Manager.

Significant changes

The entire API now lives in the
```
Unity.Services.UserReporting
```
namespace.
The API uses a single point of access, via
```
Unity.Services.UserReporting.Instance
```
.
The entire source code is no longer publicly accessible, making helpers like the
```
CyclicalList
```
no longer available in the SDK.
The SDK uses external dependencies instead of including and providing access to source code dependencies such as the
```
SimpleJSON
```
parser, or the
```
PngHelper
```
class; both have been removed.
There are several bug fixes that have not been backported, including fixing a memory leak that could occur when sending reports.
The
```
AsyncUnityUserReportingPlatform
```
has been removed.
The sample prefab GUI now scales with the display.

Outdated elements from the old SDK are no longer considered supported; although you can continue to use them if you rely on the helpers such as the

SimpleJSON

parser, we strongly encourage you to replace them with alternatives. Unity will not maintain or support such elements from the previous version of the SDK. If you consider relying on old SDK helpers for a new feature in your project, such as using the

PngHelper

, we encourage you to explore alternatives rather than depending on the outdated SDK. The User Reporting API focuses on User Report related functionality and helps prevent future API churn. It also helps Unity deliver meaningful support and improvements to the User Reporting aspect of the SDK exclusively.

Use the new example prefab

The example starting point included in the older version of the SDK has been updated and replaced. It provides identical end-user functionality and can be replaced in the scene.

Create a report

User Report objects are no longer hand-created. Instead, one report at a time can be created and sent - the report in progress is referred to as the “ongoing” report. If you create a new User Report, it clears the previous ongoing report (if a previous one exists).

UserReportingService.Instance.CreateNewUserReport();

If you want to collect and arrange data for more than one report at a time, you need to manage the responsibility of the data and then finally export said data into a report when ready to send.

Send a report

The SDK now handles only one report at a time. Rather than providing a UserReport object to the send method, the API instead has a single call for sending the ongoing report:

UserReportingService.Instance.SendUserReport(...)

. Additionally, instead of a single callback the ongoing report now offers two separate optional callbacks: one for submission progress updates, and another for when the report submission attempt ends.


UserReportingService.Instance.SendUserReport((uploadProgress) =>{	// The progressUpdate Action uses the uploadProgress float to indicate progress from 0.0 -> 1.0	Debug.Log("${uploadProgress:P}");},(success) =>{	// The result Action uses the success bool to indicate whether or not the submission succeeded	if (!success)	{		Debug.Log("Failed to send report!");	}});

General changes to adding data

Adding individual object values to a List on an individual report object, uses a specialized function with the same arguments as the constructors used in the past applies everywhere. See the following example, in this case adding a new report dimension: 1.0 adding a new report dimension example:


UserReport current;UnityUserReporting.CurrentClient.CreateUserReport((report) => {	current = report;});current.Dimensions.Add(new UserReportNamedValue("Category", “Value”));

2.0 adding a new report dimension example:

UserReportingService.Instance.AddDimensionValue("Category", “Value”);

Add custom attachments

The SDK now has a function to add attachments to the ongoing report, instead of directly adding attachments to the User Report object itself:


string content = "{}"; // An empty JSON object for example purposes.UserReportingService.Instance.AddAttachmentToReport("Sample Attachment JSON", "SampleAttachment.json", Encoding.UTF8.GetBytes(content), "application/json");

Add (device) metadata The moniker “Device Metadata” has been generalized to metadata. Again, there is now a function for this purpose.

UserReportingService.Instance.AddMetadata(“Example Name”, “Example Value”)

Conclusion

The User Reporting dashboard remains identical as of the writing of this document. See the official documentation for User Reporting when upgrading to the latest version of the SDK.

Documentation

Development

User Acquisition

Monetization

Industry