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.

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.

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.

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)
{
	AnalyticsService.Instance.StartDataCollection();
}

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.

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.

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.