Migrating to version 5.0.0

Update your code to migrate from Analytics SDK version 4.x to version 5.0.0.

Read time 3 minutes

Last updated 7 months ago

The 5.x versions of the Analytics SDK include numerous changes to the initialization and consent flow compared to 4.x versions. This guide will help you 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 includs 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 does not look up the player's location, and does not perform any activity automatically. The new initialization flow requires the SDK to 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 only 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

The legacy initialization flow is 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 5.0.0, services initialization makes a web request to look up the player's location to determine whether the player is in a region subject to certain privacy legislation. If this request fails, it is retried inside the

CheckForRequiredConsents()

call. If this second attempt fails, the SDK is unable to collect data at all. This effectively requires the application to be initialized with internet connectivity in order to collect data, regardless of whether or not consent has been given previously (which would allow events to be batched and stored for upload when connectivity is 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 privacy overview. You should also consult your own legal team.

The new initialization flow should 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){	AnalyticsService.Instance.StartDataCollection();}

You can call the

StartDataCollection()

method at any time after services initialization to begin data collection. You don't need to call it immediately at app start-up.

Warning

Events recorded while the SDK is dormant are ignored. They are not buffered for sending if

StartDataCollection()

is called later. Events are only 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

Under the legacy flow, the

OptOut()

method disables the SDK, removes it from memory and triggers a request for data deletion for the player. This makes it difficult for a player to change their mind and opt back in to data collection at a later date, because the SDK retains knowledge of its 'consent revoked' status and prevents further initialization. Requesting data deletion at this time is 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 discards 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.

Documentation

Development

User Acquisition

Monetization

Industry

Documentation

Development

User Acquisition

Monetization

Industry

Analytics

Analytics

Migrating to version 5.0.0

Initialization flow

Opting out