SDK migration guide#

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.

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.