Configuring User Reporting

The default settings for User Reporting are suitable for normal use, but as your project develops you might want to make changes for specific needs. You might build your own UI that matches your application to introduce custom fields or change the appearance of a user report form. The sample provided in the package is functional, but acts as a starting point.

User reports contain useful information such as metadata, events, sampled metrics, screenshots, and file attachments. For example, you could attach a user’s game save files to their report, or log an event every time the player performs a certain action. You can also sample performance metrics in performance-intensive gameplay situations.

Use the API to configure maximum values of each data type in your report. The UserReportExample file (found in the sample imported into your Unity project) provides a demonstration of the different means of adding data to reports.

For example, you might customize the following settings to limit the maximum of specific data types in a report:

  • FramesPerMeasure: A measure is a set of frames covered in each sample collected of a metric. The default measure length is 60 frames.
  • MaximumMeasureCount: A measure is a set of frames covered in metric samples, and counts the maximum number of measures in a report. The default value is 300 measures.
  • MaximumEventCount: This limit applies to the number of events included in a report. The default value is 100 events.
  • MaximumScreenshotCount: The limit of the most screenshots attached to a report. The default value is 10 screenshots.
  • MetricsGatheringMode: Represents a metric gathering mode. Some metrics, such as frames per second (Graphics.FramesPerSecond), can be included in reports using the Automatic mode, the default configuration. Manual will only include your own custom metrics in reports, while Disabled will prevent any sampled metrics from being sent in reports entirely.

There are no limits to these settings, but if you set higher values the collected data affects the size of your reports. In particular, large high resolution screenshots can quickly increase the size of the report.

To configure User report settings, call the UserReportingService.Instance..Configure(UserReportingClientConfiguration configuration) method:

var customConfig = new UserReportingClientConfiguration(5, 5, 100, 100, MetricsGatheringMode.Automatic);

Create and sending Reports

To create a report, call UserReportingService.Instance.UserReporting.CreateNewUserReport();.

To send a report, call UserReportingService.Instance.SendUserReport(Action<float> progressUpdate, Action<bool> result).

Observe the sample example to best understand action parameters. Sending a report is not required but recommended.

Add metadata

Use metadata to collect specific data for your game which appears with the device metadata included in User Reports by default.

To add custom metadata, call the UserReportingService.Instance.AddMetadata(string name, string value) method.

Adding metadata has negligible impact on performance.

Log events

To log custom events, call the UserReportingService.Instance.LogEvent(UserReportEventLevel level, string message) method.

Logging events has a negligible impact on performance.

Add sampling metrics

To add custom sampling metrics, call the UserReportingService.Instance.SampleMetric(string name, double value) method.

The SampleMetric method is designed for you to call every frame with a little impact on performance. However, if you call the above method for every frame, each distinct name can add significant size to the report.

Add screenshots

To add screenshots to your report, call the UserReportingService.Instance.TakeScreenshot(int maximumWidth, int maximumHeight) method. Screenshots are viewed as part of the report in the Dashboard.

Optionally you might specify a source for the screenshot, such as a Camera or RenderTexture using UserReportingService.Instance.TakeScreenshot(int maximumWidth, int maximumHeight, object source).

The image is scaled down until it fits within the size defined by the maximumWidth and maximumHeight parameters regardless of source.

When you select a maximum width and maximum height, user reports must be less than 10MB. The last screenshot taken serves as the thumbnail for the report in the Dashboard.

Note: Taking screenshots has an impact on performance. To avoid adverse effects for your users, take screenshots when performance isn't critical, for example if the player is idle.

Add attachments

Add attachments such as video and scene graphs.

Attachments are encoded as Base64 objects.

Use UserReportingService.Instance.AddAttachmentToReport(string title, string filename, byte[] data) to add attachments.

Organize report dimensions

Use dimensions to filter user reports on the Unity Dashboard. You can add dimensions and metrics to your report before sending it by adding items to a dimensions property. Each dimension or metric has a name and a value. You can add a new dimension to your report by calling:

UserReportingService.Instance.AddDimensionValue(string dimension, string value);

For example, see three reports with the following dimensions:


See the following filtering options on the Dashboard:

Dimension nameDimension value
Platform.VersionWindowsPlayer: 1

You can also add different dimensions to different reports. For example, you might only want to add SystemLanguage as a dimension for localized reports.

Users can also add a single hash tag to a report summary. This hashtag appears as a dimension.

For example, the summary "I fell through the floor #FloorBug" appears as:

Dimension nameDimension value
Hash TagFloorBug