Interface IAnalyticsService
Namespace: Unity.Services.Analytics
Assembly: Unity.Services.Analytics.dll
Syntax
public interface IAnalyticsService
Properties
PrivacyUrl
This is the URL for the Unity Analytics privacy policy. This policy page should be presented to the user in a platform-appropriate way along with the ability to opt out of data collection.
Declaration
string PrivacyUrl { get; }
Property Value
Type | Description |
---|---|
string |
SessionID
Gets the session ID that is currently recording into the sessionID field of events.
Declaration
string SessionID { get; }
Property Value
Type | Description |
---|---|
string | The session ID as a string |
Methods
AcquisitionSource(AcquisitionSourceParameters)
Record an acquisitionSource event, if the player has opted in to data collection (see OptIn method).
Declaration
[Obsolete("Please create an AcquisitionSourceEvent and use RecordEvent(...) instead.")]
void AcquisitionSource(AcquisitionSourceParameters acquisitionSourceParameters)
Parameters
Type | Name | Description |
---|---|---|
AcquisitionSourceParameters | acquisitionSourceParameters | (Required) Helper object to handle parameters. |
AdImpression(AdImpressionParameters)
Record an adImpression event, if the player has opted in to data collection (see OptIn method).
Declaration
[Obsolete("Please create an AdImpressionEvent and use RecordEvent(...) instead.")]
void AdImpression(AdImpressionParameters parameters)
Parameters
Type | Name | Description |
---|---|---|
AdImpressionParameters | parameters | (Required) Helper object to handle parameters. |
CheckForRequiredConsents()
Returns identifiers of required consents we need to gather from the user
in order to be allowed to sent analytics events.
This method must be called every time the game starts - without checking the geolocation,
no event will be sent (even if the consent was already given).
If the required consent was already given, an empty list is returned.
If the user already opted out from the current legislation, an empty list is returned.
It involves the GeoIP call.
ConsentCheckException
is thrown if the GeoIP call was unsuccessful.
Declaration
[Obsolete("This method is part of the old consent flow and should no longer be used. For more information, please see the migration guide: https://docs.unity.com/ugs/en-us/manual/analytics/manual/sdk5-migration-guide")]
Task<List<string>> CheckForRequiredConsents()
Returns
Type | Description |
---|---|
Task<List<string>> | A list of consent identifiers that are required for sending analytics events. |
Exceptions
Type | Condition |
---|---|
ConsentCheckException | Thrown if the GeoIP call was unsuccessful. |
ConvertCurrencyToMinorUnits(string, double)
Converts an amount of currency to the minor units required for the objects passed to the Transaction method. This method uses data from ISO 4217. Note that this method expects you to pass in currency in the major units for conversion - if you already have data in the minor units you don't need to call this method. For example - 1.99 USD would be converted to 199, 123 JPY would be returned unchanged.
Declaration
long ConvertCurrencyToMinorUnits(string currencyCode, double value)
Parameters
Type | Name | Description |
---|---|---|
string | currencyCode | The ISO4217 currency code for the input currency. For example, USD for dollars, or JPY for Japanese Yen |
double | value | The major unit value of currency, for example 1.99 for 1 dollar 99 cents. |
Returns
Type | Description |
---|---|
long | The minor unit value of the input currency, for example for an input of 1.99 USD 199 would be returned. |
CustomData(string)
Record a custom event that does not have any parameters, if the player has opted in to data collection (see OptIn method).
A schema for this event must exist on the dashboard or it will be ignored.
Declaration
[Obsolete("Please use RecordEvent(string) instead.")]
void CustomData(string eventName)
Parameters
Type | Name | Description |
---|---|---|
string | eventName |
CustomData(string, IDictionary<string, object>)
Record a custom event, if the player has opted in to data collection (see OptIn method).
A schema for this event must exist on the dashboard or it will be ignored.
Declaration
[Obsolete("Please use RecordEvent(...) instead, by passing in either an instance of CustomEvent, or an instance of your own sub-class of Event.")]
void CustomData(string eventName, IDictionary<string, object> eventParams)
Parameters
Type | Name | Description |
---|---|---|
string | eventName | |
IDictionary<string, object> | eventParams |
Flush()
Forces an immediately upload of all recorded events to the server, if there is an internet connection and a flush is not already in progress. Flushing is triggered automatically on a regular cadence so you should not need to use this method, unless you specifically require some queued events to be uploaded immediately.
Declaration
void Flush()
Exceptions
Type | Condition |
---|---|
ConsentCheckException | Thrown if the required consent flow cannot be determined.. |
GetAnalyticsUserID()
Gets the user ID that Analytics is currently recording into the userId field of events.
Declaration
string GetAnalyticsUserID()
Returns
Type | Description |
---|---|
string | The user ID as a string |
OptOut()
Opts the user out of sending analytics and disables the SDK. A final 'forget me' signal will be uploaded which will trigger purge of analytics data for this user from the back-end. If this 'forget me' event cannot be uploaded immediately (e.g. due to network outage), it will be reattempted regularly until successful upload is confirmed. This status is mainted between sessions to ensure that the signal will be uploaded eventually.
Declaration
[Obsolete("This method is part of the old consent flow and should no longer be used. Please use StopDataCollection() and/or RequestDataDeletion() instead as appropriate. For more information, please see the migration guide: https://docs.unity.com/ugs/en-us/manual/analytics/manual/sdk5-migration-guide")]
void OptOut()
ProvideOptInConsent(string, bool)
Sets the consent status for the specified opt-in-based legislation (PIPL etc).
The required legislation identifier can be found by calling CheckForRequiredConsents
method.
If this method is tried to be used for the incorrect legislation (PIPL outside China etc),
the ConsentCheckException
is thrown.
Declaration
[Obsolete("This method is part of the old consent flow and should no longer be used. For more information, please see the migration guide: https://docs.unity.com/ugs/en-us/manual/analytics/manual/sdk5-migration-guide")]
void ProvideOptInConsent(string identifier, bool consent)
Parameters
Type | Name | Description |
---|---|---|
string | identifier | The legislation identifier for which the consent status should be changed. |
bool | consent | The consent status which should be set for the specified legislation. |
Exceptions
Type | Condition |
---|---|
ConsentCheckException | Thrown if the incorrect legislation was being provided or the required consent flow cannot be determined. |
RecordEvent(string)
Record an event that has no parameters, if the player has opted in to data collection (see StartDataCollection method).
A schema for this event must exist on the dashboard or it will be ignored.
Declaration
void RecordEvent(string eventName)
Parameters
Type | Name | Description |
---|---|---|
string | eventName |
RecordEvent(Event)
Record an event, if the player has opted in to data collection (see StartDataCollection method).
Once the event has been serialized, the Event instance will be cleared so it can be safely reused.
A schema for this event must exist on the dashboard or it will be ignored.
Declaration
void RecordEvent(Event e)
Parameters
Type | Name | Description |
---|---|---|
Event | e | (Required) The event to be recorded. |
RecordInternalEvent(Event)
Allows other sources to write events with common analytics parameters to the Analytics service. This is primarily for use
by other packages - as this method adds common parameters that may not be expected in the general case, for custom events
you should use the CustomData
method instead.
Declaration
[Obsolete("This mechanism is no longer supported and will be removed in a future version. Use the new Core IAnalyticsStandardEventComponent API instead.")]
void RecordInternalEvent(Event eventToRecord)
Parameters
Type | Name | Description |
---|---|---|
Event | eventToRecord | Internal event to record |
RequestDataDeletion()
Requests that all historic data for this user be purged from the back-end and disables data collection. This can be called regardless of whether data collection is currently enabled or disabled.
If the purge request fails (e.g. due to the client being offline), it will be retried until it is successful, even across multiple sessions if necessary.
Declaration
void RequestDataDeletion()
SetAnalyticsEnabled(bool)
Allows you to disable the Analytics service. When the service gets disabled all currently cached data both in RAM and on disk will be deleted and any new events will be voided. By default the service is enabled so you do not need to call this method on start. Will return instantly when disabling, must be awaited when re-enabling.
Declaration
[Obsolete("This method is part of the old consent flow and should no longer be used. For more information, please see the migration guide: https://docs.unity.com/ugs/en-us/manual/analytics/manual/sdk5-migration-guide")]
Task SetAnalyticsEnabled(bool enabled)
Parameters
Type | Name | Description |
---|---|---|
bool | enabled |
Returns
Type | Description |
---|---|
Task |
Examples
To disable the Analytics Service before the game starts
[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
static void DisableAnalytics()
{
AnalyticsService.Instance.SetAnalyticsEnabled(false);
}
StartDataCollection()
Signals that consent has been obtained from the player and enables data collection.
By calling this method you confirm that consent has been obtained or is not required from the player under any applicable data privacy laws (e.g. GDPR in Europe, PIPL in China). Please obtain your own legal advice to ensure you are in compliance with any data privacy laws regarding personal data collection in the territories in which your app is available.
Declaration
void StartDataCollection()
StopDataCollection()
Disables data collection, preventing any further events from being recorded or uploaded. A final upload containing any events that are currently buffered will be attempted.
Data collection can be re-enabled later, by calling the StartDataCollection method.
Declaration
void StopDataCollection()
Transaction(TransactionParameters)
Record a transaction event, if the player has opted in to data collection (see OptIn method).
Declaration
[Obsolete("Please create a TransactionEvent and use RecordEvent(...) instead.")]
void Transaction(TransactionParameters parameters)
Parameters
Type | Name | Description |
---|---|---|
TransactionParameters | parameters | (Required) Helper object to handle parameters. |
TransactionFailed(TransactionFailedParameters)
Record a transactionFailed event, if the player has opted in to data collection.
Declaration
[Obsolete("Please create a TransactionFailedEvent and use RecordEvent(...) instead.")]
void TransactionFailed(TransactionFailedParameters parameters)
Parameters
Type | Name | Description |
---|---|---|
TransactionFailedParameters | parameters | (Required) Helper object to handle parameters. |