Migrating to version 5.0.0#

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.

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 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.

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.

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.

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.

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.