App Center Analytics (Unity)
Important
Visual Studio App Center is scheduled for retirement on March 31, 2025. While you can continue to use Visual Studio App Center until it is fully retired, there are several recommended alternatives that you may consider migrating to.
App Center Analytics helps you understand user behavior and customer engagement to improve your app. The SDK automatically captures session count and device properties like model, OS version, etc. You can define your own custom events to measure things that matter to you. All the information captured is available in the App Center portal for you to analyze the data.
Follow the instructions in the Unity Get started section if you haven't set up the SDK in your application yet.
Note
To use the APIs presented below, you must add the following using
statement to your .cs
file:
using Microsoft.AppCenter.Unity.Analytics;
You also must make sure that Use Analytics is checked in the settings of your App Center game object.
Once you add App Center Analytics and start the SDK, it will automatically track sessions and device properties like OS Version, model, etc. without requiring any additional code in your app.
You can track your own custom events with up to 20 properties to know what's happening in your app, understand user actions, and see the aggregates in the App Center portal.
Use the TrackEvent()
method to track your events with properties. You can send up to 200 distinct event names. There's a maximum limit of 256 characters per event name and 125 characters per event property name and value.
Analytics.TrackEvent("Video clicked", new Dictionary<string, string> {
{ "Category", "Music" },
{ "FileName", "favorite.avi" }
});
Properties for events are optional – if you just want to track an event, use this sample instead:
Analytics.TrackEvent("Video clicked");
Warning
Analytics.TrackEvent()
will behave inconsistently across platforms if it's called prior to the Awake()
method in the script AppCenterBehavior.cs
. To be safe, you should only rely on events to be sent after the first scene in your application has awakened all of the MonoBehaviour
scripts. To track an event in conjunction with a MonoBehavour
's initialization, consider adding the API to your script's Start()
method instead of Awake()
.
You can enable and disable App Center Analytics at runtime. If you disable it, the SDK will stop collecting analytics information for the app. To disable Analytics, use the following API, passing false
as a parameter.
Analytics.SetEnabledAsync(false);
To enable App Center Analytics again, use the same API but pass true
as a parameter.
Analytics.SetEnabledAsync(true);
The state is persisted in the device's storage across application launches.
This API is asynchronous, you can read more about in our App Center Asynchronous APIs guide.
You can also check if App Center Analytics is enabled or not.
bool isEnabled = await Analytics.IsEnabledAsync();
You can track business critical events that have higher importance than other events.
Developers can set persistence of events as Normal (Flags.PersistenceNormal
in the API) or Critical (Flags.PersistenceCritical
in the API).
You can use the following API to track an event as Critical:
Analytics.TrackEvent("eventName", Flags.PersistenceCritical);
If you're using properties:
Analytics.TrackEvent("eventName", new Dictionary<string, string> {
{ "Category", "Music" },
{ "FileName", "favorite.avi" }
}, Flags.PersistenceCritical);
Pausing the event transmission can be useful in scenarios when the app needs to control the network bandwidth for more business critical needs. You can pause sending logs to the App Center backend. When paused, events can still be tracked and saved, but they aren't sent right away. Any events your app tracks while paused will only be sent once you call Analytics.Resume
.
Analytics.Pause();
Analytics.Resume();
This API is asynchronous, you can read more about in our App Center Asynchronous APIs guide.
By default, the session ID depends on the lifecycle of the application. If you want to control the start of a new session manually, follow the next steps:
Note
Pay attention that each call of Analytics.StartSession() API will generate a new session. If in manual session tracker mode this API will not be called then all sending logs will have a null session value.
Note
Pay attention that after a new application launch the session id will be regenerated.
- Uncheck the Enable Manual Session Tracker checkbox under Analytics section on the game object with AppCenterBehavior attached.
- Then you can use the
StartSession
API after theAppCenter.Start
:
Analytics.StartSession();
By default, the SDK stores up to 10 MB of logs in the storage.
When there isn't any network connectivity, the SDK saves up to 10 MB of logs in the local storage. Once the storage is full, the SDK will start discarding old logs to make room for the new logs. Once the device gets internet access back, the SDK will send logs in the batch of 50 or after every 6 seconds.
The App Center SDK uploads logs in a batch of 50 and if the SDK doesn't have 50 logs to send, it will still send logs after 6 seconds. There can be a maximum of three batches sent in parallel.
App Center SDK supports back-off retries on recoverable network errors. Below is the retry logic:
- 3 tries maximum per request.
- Each request has its own retry state machine.
- All the transmission channels are disabled (until next app process) after one request exhausts all its retries.
Back-off logic
- 50% randomization, first retry between 5s and 10s, second retry between 2.5 and 5 minutes, last try between 10 and 20 minutes.
- If network switches from off to on (or from wi-fi to mobile), retry states are reset and requests are retried immediately.