Overview

A Native Android SDK does not exist for Unity Analytics, however the Unity Analytics REST API can be used to send Analytics events from your native game client to Unity Analytics. This will require you implement your own REST API wrapper in your game client, taking into account offline caching, back-off & retry and session management etc..

Alternatively, the source code for the existing deltaDNA Android SDK is publically available on the deltaDNA GitHub repository if you would prefer to download or fork, modify and maintain it yourself. It can be patched to send event data to Unity Analytics instead of the deltaDNA endpoint.

Regardless of whether you intend to implement UGS Services or modify the deltaDNA SDK to work with them, you will need to follow the DELTADNA TO UNITY DASHBOARD MAPPING FLOW before 3rd March 2024 and pay attention to the player’s userID, to ensure you have a contiguous data record for each player that migrates from deltaDNA to Unity Analytics.

Analytics REST API Migration

The native Android SDK can be replaced with the Unity Analytics REST API, but there are a few things you will need to take into consideration when implementing this approach:

• • Privacy : You will need to implement player consent and data privacy checks to comply with the store and territory legislation relevant for your game.

 

• userID consistency : To ensure a contiguous data record for the player as they move to Unity Analytics, you will need to use the same userID that the native Android SDK previously used. You can retrieve the userID from the SDK by reading the userID property from it
  
  C#

  DDNA.instance().getUserId()

  1	DDNA.instance().getUserId()

• Session management : The deltaDNA Android SDK generates a new sessionID parameter that it uses on each event for the duration of the current gameplay session. A new sessionID is generated on each App launch or when it returns from being backgrounded for more than 5 minutes. The sessionID is just a string that is unique to that user session, you will need to generate this yourself.
• eventUUID : Each event can contain an optional eventUUID parameter, if this parameter is present the Unity Analytics ingestion pipeline will use it to de-duplicate events. It is just a string that is unique to this user event. It is particularly important if you are using event caching and retries.
• eventTimestamp : Each event should contain an eventTimestamp parameter representing the UTC timestamp when the player performed a particular action. If this is omitted a timestamp will be applied on the server when the event is received, causing batched or cached events to look incorrect in the dataset.
• Offline event caching : The Unity Analytics REST API will respond with a 204 status code if your event POST is received successfully. If you don’t get this response you should consider caching the event(s) and retrying later when connectivity is restored. Be sure to use the eventUUID to avoid duplicate events from retries on bad connections.
• Back off and retry and Timeouts : If you implement event caching you should also implement your own backoff and retry mechanism.
• Standard event and parameter consistency : The Android SDK sends several standard events that are used to populate the Analytics dashboards, you will be required to record these, populating all the relevant parameters correctly, yourself. You can view the event definitions in the Event Manager tool in the deltaDNA dashboard, or in the same tool in the Unity Dashboard after successfully mapping your deltaDNA game to Unity Analytics. Take a look at the Android SDK source code to see how each of the parameter values is populated, searching the repository for the specific event name or parameter name will help you find them.

Additional documentation

• deltaDNA Android SDK GitHUb Repository
• deltaDNA REST API
• deltaDNA Event Management
• deltaDNA Event Browser tool
• Unity Analytics REST API
• Unity Analytics Event Management
• Unity Analytics Event Browser tool
• deltaDNA to UGS project Mapping Guide
• deltaDNA to UGS Analytics SDK Migration Guide
• deltaDNA Migration Guide : Rest API 
• Unity Remote Config Documentation
• Unity Remote Config client REST API
• Unity Game Overrides

We recommend using a network proxy tool like Fiddler or Charles to check event posts during development and the Event Browser dashboard tool to check that they are passing event validation.

deltaDNA SDK Modification

The existing deltaDNA Android SDK is simply a wrapper for the deltaDNA Analytics REST API.

The specifications for the deltaDNA and Unity Analytics REST APIs are very similar. The format of the JSON analytics events is identical, it is just the REST API endpoint that differs.

The following details show how to modify deltaDNA SDK v5.0.2 for Android to make it send events to the Unity Analytics REST API endpoint instead of deltaDNA. These modifications may save you the effort of implementing your own REST API wrapper from scratch.

A version of Android SDK v5.0.2 that has already been modified can also be downloaded from here

android-sdk-5.0.2 – Modified for UGS Analytics.zip

SDK Integration

The deltaDNA Android SDK can be downloaded as a .zip file from the releases page of the deltaDNA repository on GitHub, you will find source code in the .zip file along with some SDK examples. There have been numerous versions of the SDK over the years and a few different ways of integrating it (Gradle, Mavern etc..). This guide has been written using v5.0.2 of the deltaDNA Android SDK, there may be some differences with earlier versions, but the theory is the same. In order to patch the SDK you are going to need to modify a few source files, so we recommend downloading the .zip file in order to get access to the SDK source. Once modified you can then replace the SDK in your game.

1. Download the deltaDNA Android SDK v5.0.2 zip file from the Releases page of the deltaDNA GitHub repository and extract it.
2. Launch Android Studio then Open the android-sdk-5.0.2 folder
   Note – this guide was written with Android Studio Hedgehog 2023.1.1 patch 1
   
   A Gradle error will likely be received at this point. Clicking on the Upgrade Gradle wrapper to 7.2 .. link should resolve this and re-import the project.
   
   
   Selecting the example-demo project and running it on connected device should now result in a successful build that sends Analytics events to deltaDNA.
   
   

SDK Modifications

1. Change the version number in the sdk gradle.properties file so we can identify analytics events coming from the modified SDK, then resync the project
   VERSION_NAME=5.0.2 (UGS)
2. We need to provide a couple of additional parameters to Unity Analytics when the SDK is started. These parameters need to be added in a few places, then used by the REST API in the URL endpoints for Unity Analytics and Remote Config to ensure that data is sent to the correct project environment.
   Open the sdk\DDNA.java file and replace the Configuration Class with the following code. It adds projectId and environmentName declarations then sets them in the constructor. A couple of precondition checks are also added.
   
   public static final class Configuration { protected final Application application; final String projectId; final String environmentName; final String environmentKey; final String collectUrl; final String engageUrl; @Nullable String hashSecret; @Nullable String clientVersion; @Nullable String userId; @Nullable String platform; protected final Settings settings; public Configuration( Application application, String projectId, String environmentName, String environmentKey, String collectUrl, String engageUrl) { Preconditions.checkArg( application != null, "application cannot be null"); Preconditions.checkArg( !TextUtils.isEmpty(projectId), "projectId cannot be null or empty"); Preconditions.checkArg( !TextUtils.isEmpty(environmentName), "environmentName cannot be null or empty"); Preconditions.checkArg( !TextUtils.isEmpty(environmentKey), "environmentKey cannot be null or empty"); Preconditions.checkArg( !TextUtils.isEmpty(collectUrl), "collectUrl cannot be null or empty"); Preconditions.checkArg( !TextUtils.isEmpty(engageUrl), "engageUrl cannot be null or empty"); this.application = application; this.projectId = projectId; this.environmentName = environmentName; this.environmentKey = environmentKey; this.collectUrl = fixUrl(collectUrl); this.engageUrl = fixUrl(engageUrl); this.settings = new Settings(); }

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56

   public static final class Configuration {       protected final Application application;    final String projectId;    final String environmentName;    final String environmentKey;    final String collectUrl;    final String engageUrl;       @Nullable    String hashSecret;    @Nullable    String clientVersion;    @Nullable    String userId;    @Nullable    String platform;       protected final Settings settings;       public Configuration(            Application application,            String projectId,            String environmentName,            String environmentKey,            String collectUrl,            String engageUrl) {               Preconditions.checkArg(                application != null,                "application cannot be null");        Preconditions.checkArg(                !TextUtils.isEmpty(projectId),                "projectId cannot be null or empty");        Preconditions.checkArg(                !TextUtils.isEmpty(environmentName),                "environmentName cannot be null or empty");        Preconditions.checkArg(                !TextUtils.isEmpty(environmentKey),                "environmentKey cannot be null or empty");        Preconditions.checkArg(                !TextUtils.isEmpty(collectUrl),                "collectUrl cannot be null or empty");        Preconditions.checkArg(                !TextUtils.isEmpty(engageUrl),                "engageUrl cannot be null or empty");               this.application = application;        this.projectId = projectId;        this.environmentName = environmentName;        this.environmentKey = environmentKey;        this.collectUrl = fixUrl(collectUrl);        this.engageUrl = fixUrl(engageUrl);               this.settings = new Settings();    }

    
3. The new projectId and environmentName also need to be added to the DDNAImpl & DDNANonTracking delegates in the DDNA.java file (Around Line 94 in SDK v5.0.2)
   
   new DDNAImpl( configuration.application, configuration.projectId, configuration.environmentName, configuration.environmentKey, configuration.collectUrl, configuration.engageUrl, configuration.settings, configuration.hashSecret, configuration.clientVersion, configuration.userId, configuration.platform, eventListeners, iEventListeners), new DDNANonTracking( configuration.application, configuration.projectId, configuration.environmentName, configuration.environmentKey, configuration.collectUrl, configuration.engageUrl, configuration.settings, configuration.hashSecret, configuration.platform, eventListeners, iEventListeners));

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26

   new DDNAImpl(        configuration.application,        configuration.projectId,        configuration.environmentName,        configuration.environmentKey,        configuration.collectUrl,        configuration.engageUrl,        configuration.settings,        configuration.hashSecret,        configuration.clientVersion,        configuration.userId,        configuration.platform,        eventListeners,        iEventListeners), new DDNANonTracking(        configuration.application,        configuration.projectId,        configuration.environmentName,        configuration.environmentKey,        configuration.collectUrl,        configuration.engageUrl,        configuration.settings,        configuration.hashSecret,        configuration.platform,        eventListeners,        iEventListeners));

    
4. Next the DDNA Constructor can be updated with the two new parameters, in DDNA.java file (around Line 161 in SDKv5.0.2)
   
   DDNA( Application application, String projectId, String environmentName, String environmentKey, String collectUrl, String engageUrl, Settings settings, @Nullable String hashSecret, @Nullable String platform, Set eventListeners, Set iEventListeners) {

   1 2 3 4 5 6 7 8 9 10 11

   DDNA(   Application application,        String projectId,        String environmentName,        String environmentKey,        String collectUrl,        String engageUrl,        Settings settings,        @Nullable String hashSecret,        @Nullable String platform,        Set eventListeners,        Set iEventListeners) {

    
5. Then the delegates can be updated. First the DDNADelegate.java file (Around line 46 in SDK v5.0.2)
   
   DDNADelegate( Configuration configuration, Set eventListeners, Set iEventListeners, DDNA tracking, DDNA nonTracking) { super( configuration.application, configuration.projectId, configuration.environmentName, configuration.environmentKey, configuration.collectUrl, configuration.engageUrl, configuration.settings, configuration.hashSecret, configuration.platform, eventListeners, iEventListeners);

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

   DDNADelegate(        Configuration configuration,        Set eventListeners,        Set iEventListeners,        DDNA tracking,        DDNA nonTracking) {       super(  configuration.application,            configuration.projectId,            configuration.environmentName,            configuration.environmentKey,            configuration.collectUrl,            configuration.engageUrl,            configuration.settings,            configuration.hashSecret,            configuration.platform,            eventListeners,            iEventListeners);

    
6. Then the DDNAImpl.java delegate (Around Line 486 in SDK v5.0.2)
   
   DDNAImpl( Application application, String projectId, String environmentName, String environmentKey, String collectUrl, String engageUrl, Settings settings, @Nullable String hashSecret, @Nullable String clientVersion, @Nullable String userId, @Nullable String platform, Set eventListeners, Set iEventListeners) { super( application, projectId, environmentName, environmentKey, collectUrl, engageUrl, settings, hashSecret, platform, eventListeners, iEventListeners);

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26

   DDNAImpl(        Application application,        String projectId,        String environmentName,        String environmentKey,        String collectUrl,        String engageUrl,        Settings settings,        @Nullable String hashSecret,        @Nullable String clientVersion,        @Nullable String userId,        @Nullable String platform,        Set eventListeners,        Set iEventListeners) {       super(  application,            projectId,            environmentName,            environmentKey,            collectUrl,            engageUrl,            settings,            hashSecret,            platform,            eventListeners,            iEventListeners);

    
7. Finally the DDNANonTracking.java delegate (Around Line 51 in SDK v5.0.2)
   
   DDNANonTracking( Application application, String projectId, String environmentName, String environmentKey, String collectUrl, String engageUrl, Settings settings, @Nullable String hashSecret, @Nullable String platform, Set eventListeners, Set iEventListeners) { super( application, projectId, environmentName, environmentKey, collectUrl, engageUrl, settings, hashSecret, platform, eventListeners, iEventListeners);

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24

   DDNANonTracking(        Application application,        String projectId,        String environmentName,        String environmentKey,        String collectUrl,        String engageUrl,        Settings settings,        @Nullable String hashSecret,        @Nullable String platform,        Set eventListeners,        Set iEventListeners) {       super(  application,            projectId,            environmentName,            environmentKey,            collectUrl,            engageUrl,            settings,            hashSecret,            platform,            eventListeners,            iEventListeners);

    
8. Now the NetworkManager constructor can now be updated to use the two new parameters. First update the NetworkManager constructor in the sdk\net\NetworkManager.java file (Around Line 56 in SDK v5.0.2). The two new parameters are added to the constructor as inputs, then the collectUrl and engageUrl are updated accordingly
   
   public NetworkManager( String projectId, String envName, String envKey, String collectUrl, String engageUrl, Settings settings, @Nullable String hash) { this.collectUrl = collectUrl + '/' + projectId + "/environments/" + envName; this.engageUrl = engageUrl ; this.settings = settings; this.hash = hash; MessageDigest md = null; if (hash != null && !hash.isEmpty()) { try { md = MessageDigest.getInstance("MD5"); } catch (NoSuchAlgorithmException e) { Log.w(TAG, "Events will not be hashed", e); } } md5 = md; dispatcher = new NetworkDispatcher(); }

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26

   public NetworkManager(        String projectId,        String envName,        String envKey,        String collectUrl,        String engageUrl,        Settings settings,        @Nullable String hash) {       this.collectUrl = collectUrl + '/' + projectId + "/environments/" + envName;    this.engageUrl = engageUrl ;    this.settings = settings;       this.hash = hash;    MessageDigest md = null;    if (hash != null && !hash.isEmpty()) {        try {            md = MessageDigest.getInstance("MD5");        } catch (NoSuchAlgorithmException e) {            Log.w(TAG, "Events will not be hashed", e);        }    }    md5 = md;       dispatcher = new NetworkDispatcher(); }

    
9. Then the call to create a NetworkManager in the sdk\DDNA.java file can be updated to use the new parameters. (Around Line 179 in SDK v5.0.2)
   
   network = new NetworkManager( projectId, environmentName, environmentKey, collectUrl, engageUrl, settings, hashSecret); consentTracker = new ConsentTracker( application.getSharedPreferences(DDNA_SHARED_PREFERENCES_KEY, Context.MODE_PRIVATE), new GeoIpNetworkClient(network) );

   1 2 3 4 5 6 7 8 9 10 11 12

   network = new NetworkManager(        projectId,        environmentName,        environmentKey,        collectUrl,        engageUrl,        settings,        hashSecret); consentTracker = new ConsentTracker(        application.getSharedPreferences(DDNA_SHARED_PREFERENCES_KEY, Context.MODE_PRIVATE),        new GeoIpNetworkClient(network) );

    
10. You can now modify your game code to populate the UGS projectId and environmentName parameters when the SDK is started. In the example-demo this is located in the ExampleApplication.java file. Note, the EnviornmentKey and API URls have also been modified to point to the Unity project, rather than deltaDNA.The URL endpoint for the Unity Analytics REST API is
    https://collect.analytics.unity3d.com/api/analytics/collect/v1/projectsThe URL endpoint for the Unity Remote Config is
    <span class="lang:default decode:true crayon-inline">https://config.unity3d.com/api/v1/settingsThe projectId for your project can be found on the Unity Cloud > Project Settings page for your project.
    The environmentKey and environmentName for each environment on your project can be found on the Unity Cloud > Environments page
    
    DDNA.initialise(new DDNA.Configuration( this, "25088b95-5df2-4352-9d7b-e72d48d9e5fe", "production", "1875d8f6-5c64-42e0-9e18-be437a0a126d", "https://collect.analytics.unity3d.com/api/analytics/collect/v1/projects", "https://config.unity3d.com/api/v1/settings") .clientVersion(BuildConfig.VERSION_NAME));

    1 2 3 4 5 6 7 8

    DDNA.initialise(new DDNA.Configuration(        this,        "25088b95-5df2-4352-9d7b-e72d48d9e5fe",        "production",        "1875d8f6-5c64-42e0-9e18-be437a0a126d",        "https://collect.analytics.unity3d.com/api/analytics/collect/v1/projects",        "https://config.unity3d.com/api/v1/settings")        .clientVersion(BuildConfig.VERSION_NAME));

    At this point Analytics event collection should be working, sending what the game thinks are deltaDNA events successfully, to Unity Analytics.

Testing

Use a network proxy like Charles or Fiddler to check that your analytics events are sending as expected and that you are getting a 204 response indicating that they have been received.

You should also check the Unity Analytics > Event Browser tool to confirm that they are arriving and validating correctly.