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

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.

Remote Config and Game Override Migration

deltaDNA Engage Decision Point campaigns can be replicated to a large extent using UGS Remote Config and Game Overrides

  • deltaDNA Decision Point campaigns make a request at time of your choosing and respond with a JSON payload containing parameter keys and values. The content response can be targeted to individual players based on Analytics segmentation and values sent in the request at runtime.
  • UGS Remote Config makes a request at game launch by default, but can be refreshed later at a time of your choosing. It retrieves all predefined keys and values for the game
  • UGS Game Overrides change the response of a Remote Config requestt at game launch by default, but can be refreshed later at a time of your choosing. It retrieves all predefined keys including any that have been modified based on Analytics Audience or JEXL runtime parameter evaluation criteria.

There are some differences that should be noted though.

deltaDNA Decision Point Campaigns

Remote Config / Game Overrides
Analytics Audience Segmentation AND Runtime request parameters can be used to target the response to the player EITHER Analytics Audience OR Runtime Request parameters can be used to target the response to the player.

This may be a sufficient difference to prevent the migration of some DDNA decision point campaign without reworking their player selection criteria.
Only the parameter keys and values for a specific decision point are returned with each request. All parameter keys and values for the game are returned with each request.
Decision Point requests are made whenever you make them in your game client. It is not uncommon for a game to make multiple decision point requests at different points in the game.  Remote Config requests are typically only made when the game is launched, but they can be made at other points in the game if you explicitly make them.

Decision Point campaign endpoint, parameters and response format are different to Remote Config

It should also be noted that Event Triggered Campaigns and Image Message Popups rely on significant client side code and JSON response payloads, it would be a major undertaking to try and replicate their functionality with UGS.

deltaDNA Engage Decision Point Request and Response example.

Request Endpoint
https://engage16056nwdmf.deltadna.net Request Body

Response Body

 

UGS Remote Config / Game Override Request and Response example.

Request Endpoint
https://config.unity3d.com/api/v1/settings Request Body

Response Body

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 and Remote Config.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.
     
  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)
     
  4. Next the DDNA Constructor can be updated with the two new parameters, in DDNA.java file (around Line 161 in SDKv5.0.2)
     
  5. Then the delegates can be updated. First the DDNADelegate.java file (Around line 46 in SDK v5.0.2)
     
  6. Then the DDNAImpl.java delegate (Around Line 486 in SDK v5.0.2)
     
  7. Finally the DDNANonTracking.java delegate (Around Line 51 in SDK v5.0.2)
     
  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
     
  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)
     
  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
    At this point Analytics event collection should be working, sending what the game thinks are deltaDNA events successfully, to Unity Analytics.
  11. Now we can modify the bodies of the Engage Decision Point campaign request and responses to match the formatting expected by Unity Remote Config.
    First change the way the request payload is constructed by completely replacing the section of code, inside the try block, that builds the event JSONObject in the EventHandler.java file (Around Line 168 in SDK v5.0.2).
     
  12. Now we can make some changes to the NetworkManager.java file to inject the new projectId and environmentId into the request. Four small changes are required to achieve this.Add the JSONException library to the top of the NetworkManager class if your IDE hasn’t added it automatically already.
    Then add the new properties (Around Line 50 in SDK v5.0.2)
    Then populate them (Around Line 71 in SDK v5.0.2)
    Before injecting their values into the Remote Config request payload (Around Line 130 in SDK v5.0.2)
     
  13. Finally, you may need to modify the Engage Decision Point request in the test app to send a request with the decisionPoint and parameters that match something that you have configured in Remote Config.
    e.g. in the DemoApplication ExampleActivity.java file (Around Line 173 in SDK v5.0.2)
     

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.


deltaDNA Engage Decision Point Campaigns can be tested with the deltaDNA > Setup > Engage Trace Tool. It lets you see the Engage request and response for a given decision point campaign.

A network traffic proxy like Charles or Fiddler should be used to check the requests and responses from UGS Remote Config / Game Overrides.

Game Override campaign setup.

The sdk modifications above rely on the decisionPoint campaign name (decisionPoint) being sent to the Remote Config API as a user parameter that can then be evaluated at runtime as JEXL audience targeting criteria.

This does impose a limitation, that Analytics audience selection criteria cannot be used at the same time. But additional parameters can be put into the JEXL targeting criteria to mitigate this.