Migrating to version 5.0.0

The new 5.0.0 version of the Analytics SDK includes numerous changes to the SDK initialization and consent flow. This guide will help navigate these changes.

Note: The legacy initialization and consent logic is still present in version 5.0.0 for backwards compatibility during migration, but you should switch to the new logic as early as possible to ensure the SDK is working as intended. The legacy flow operations are marked with the Obsolete attribute and will be removed in a future version of the SDK.

The legacy initialization flow included a number of automatic steps, including looking up the player's location (using GeoIP) to determine whether or not consent is required for data collection, and if data collection is allowed until explicitly revoked. This is changing.

In the new initialization flow, the SDK will not look up the player's location, and will not perform any activity automatically. The new initialization flow requires the SDK be explicitly activated by calling the StartDataCollection() method. This method should only be called if one of the following is true:

  • You've asked the player for and received their consent to collect their data under the appropriate data privacy legislation that affects them.
  • The player is affected by data privacy legislation that does not require explicit consent, and they have not explicitly opted out.
  • The player is not affected by any data privacy legislation.

Calling UnityServices.InitializeAsync() still initializes the Analytics SDK. However, this initialization onlys bring the SDK into memory and it remains 'dormant' until you explicitly activate it with a call to StartDataCollection(). Similarly, if you deactivate the SDK with the StopDataCollecton() method, the SDK stays in memory, so you can reactivate it later if the player provides or reinstates consent some time after initialization.

Note: When you invoke a method from either the new or old flow, this locks the SDK into only accepting further calls associated with that flow. If you attempt to call methods from both flows together, these will throw exceptions.

Initialization flow

Previously, the initialization flow was similar to this:

await UnityServices.InitializeAsync();
List<string> requiredConsents = await AnalyticsService.Instance.CheckForRequiredConsents();

if (consents.Count > 0)
	// Show UI element asking the user for their consent //

	bool userGaveConsent = ...

	foreach (string legislationIdentifier in requiredConsents)
		AnalyticsService.Instance.ProvideOptInConsent(identifier, userGaveConsent);

In versions of the SDK prior to versions 5.0.0, services initialization made a web request to look up the player's location (and determine whether the player is in a region subject to certain privacy legislation). If this request failed, it was retried inside the CheckForRequiredConsents() call. If this second attempt failed, the SDK was unable to collect data. This effectively required the application to be initialized with internet connectivity in order to collect data, regardless of whether or not consent had been given before and that events could be batched and stored for upload when connectivity might be restored.

The new initialization flow does not make any web requests. In exchange, you must build your own logic to determine if a player is located in a region where consent is required to collect their personal data as required by certain data privacy legislation. Once you're certain you have the player's consent, call the StartDataCollection() method to enable the SDK and start personal data collection. If the player does not give consent, no action is required as the SDK remains dormant until explicitly given the StartDataCollection() signal.

Note: For more information about proper compliance with data privacy legislation, see our pages: Data Privacy, Complying with GDPR and CCPA and Complying with PIPL. You should also consult your own lawyer.

The initialization flow should now look like this:

await UnityServices.InitializeAsync();

// Show UI element asking the user for their consent OR retrieve prior consent from storage //

bool userGaveConsent = ...

if (userGaveConsent)

The StartDataCollection() method can be called at any time after Services initialization to begin data collection. It doesn't need to be called immediately at app start-up.

Note: Events recorded while the SDK is dormant will be discarded. They will not be buffered for sending if StartDataCollection() is called later. Events will only be recorded once you have called StartDataCollection().

Note: Start-up events such as gameStarted and clientDevice are now recorded when the StartDataCollection() method is called, not before. If data collection is started, then stopped and started again within a single session, they are recorded only once on the first StartDataCollection().

Opting out

Previously, the OptOut() method disabled the SDK, removed it from memory and triggered a request for data deletion for the player. This made it difficult for a player to change their mind and opt back in to data collection at a later date, because the SDK retained knowledge of its 'consent revoked' status and prevented further initialization. Requesting data deletion at this time was also unnecessary, as a player opting out of further personal data collection doesn't necessarily mean they also want their previously collected data to be purged.

When you call the new StopDataCollection() method, this only disables the SDK, leaving it in memory for later reactivation if needed. The SDK attempts to make a final upload of any events that have been recorded up to that point and then discard any further events.

If the player also wishes to request their data be purged from the back-end, you must call the RequestDataDeletion() method separately.

Note: The data deletion mechanism continues to attempt to send the request until it's successful, even across sessions if necessary. The Analytics SDK remembers this status using the PlayerPrefs API, so calling PlayerPrefs.DeleteAll() might disrupt the process.

If a player opts out without requesting data deletion, you can still use the RequestDataDeletion() method to request their data be purged later. You can call this at any time, regardless of whether the SDK is active or dormant.