Overview

A Native iOS SDK does not exist for Unity Analytics, however the 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 iOS 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.

With both methods, if you have followed the DELTADNA TO UNITY DASHBOARD MAPPING FLOW before 3rd March 2024 and pay attention to the player’s userID, you can ensure a contiguous data record is maintained for each player that migrates from deltaDNA to Unity Analytics.

This guide covers both migration methods, but it only covers Analytics. Engage Campaign migration will be covered in a separate guide.

REST API Migration

The native iOS 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 iOS SDK previously used. You can retrieve the userID from the SDK by reading the userID property from it [DDNASDK sharedInstance].userID

Session management : The deltaDNA iOS 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 iOS 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 iOS 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.

deltaDNA SDK Modification

The existing deltaDNA iOS SDK is simply a wrapper for the deltaDNA REST API and luckily the specification for the deltaDNA and Unity Analytics REST APIs are very similar. The format of the JSON events is identical, it is just the REST API endpoint that differs. So, the deltaDNA SDK can be patched to make it send events to the Unity Analytics REST API endpoint instead of the deltaDNA one. This option may save you the effort of implementing your own REST API wrapper.

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

ios-sdk-5.0.2 – Modified for UGS Analytics and Remote Config.zip

SDK Integration

The deltaDNA iOS SDK can be downloaded from the deltaDNA repository on GitHub, you will find source code and Framework files there. There have been numerous versions of the SDK over the years and a few different ways of integrating it (source files, XC Framework, CocoaPods..). This guide has been written using v5.0.2 of the deltaDNA iOS SDK in mind, 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 you may need to re-install the SDK using the Source Files method.

Download and unzip the iOS SDK Source code.zip from the repository releases page
Drag the DeltaDNA.xcodeproj file in to your Xcode project
Select the build target on your main project and add the DeltaDNA.framework to it.
You should now be able to see the deltaDNA source files inside the DeltaDNA folder in your Xcode project structure. Validate that you can build and run your project.

Open the DeltaDNA/DDNASDK.h file and add this new method declaration to it.
(around Ln 134 in SDKv5.0.2)

/**
The SDK must be started once before you can send events.
@param projectId The Unity games's unique projectId.
@param environmentName The environment name.
@param collectURL The Unity Analytics Collect Endpoint URL.
*/
- (void)startWithProjectId: (NSString *) projectId
environmentName: (NSString *) environmentName
collectURL: (NSString *) collectURL;

/**

The SDK must be started once before you can send events.

@param projectId The Unity games's unique projectId.

@param environmentName The environment name.

@param collectURL The Unity Analytics Collect Endpoint URL.

- (void)startWithProjectId: (NSString *) projectId

environmentName: (NSString *) environmentName

collectURL: (NSString *) collectURL;

Open the DeltaDNA/DDNASDK.m file and add the following method to it
(around Ln 73 in SDK v5.0.2)
We will call this new method to start the SDK. The Unity Analytics REST API uses slightly different URL parameters than the deltaDNA one did. Note, we have also blanked out the Engage URL, we won’t be using it anymore (more on that later)

-(void)startWithProjectId:(NSSet *)projectId
          environmentName:(NSString *)environmentName
               collectURL:(NSString *)collectURL
{
    NSString *endpoint = [NSString stringWithFormat:@"%@/%@/environments", collectURL, projectId];
    
    [self startWithEnvironmentKey:environmentName
                       collectURL:endpoint
                        engageURL:@""
               	           userID:nil];
}

-(void)startWithProjectId:(NSSet *)projectId

environmentName:(NSString *)environmentName

collectURL:(NSString *)collectURL

{

NSString *endpoint = [NSString stringWithFormat:@"%@/%@/environments", collectURL, projectId];

[self startWithEnvironmentKey:environmentName

collectURL:endpoint

engageURL:@""

userID:nil];

}

Open the DeltaDNA/Extensions/NSUrl+DeltaDNA.m and modify the URLWithCollectEndpoint method to the following
(around line 45 in SDK v5.0.2)This removes the payload hashing and bulk endpoint that aren’t supported on Unity Analytics REST API. Don’t worry though, the endpoint we will use does accept posts containing multi-event arrays.It also modifies the URL builder to add the environment name to the end.
You can remove the NSLog line when you are satisfied that the SDK modification is performing as expected.

+ (NSURL *)URLWithCollectEndpoint:(NSString *)endpoint environmentKey:(NSString *)environmentKey payload:(NSString *)payload hashSecret:(NSString *)hashSecret
{
        
    NSString *url = [NSString stringWithFormat:@"%@/%@", endpoint, environmentKey];
    NSLog( @"%@",url);
    
    return [NSURL URLWithString:url];
}

+ (NSURL *)URLWithCollectEndpoint:(NSString *)endpoint environmentKey:(NSString *)environmentKey payload:(NSString *)payload hashSecret:(NSString *)hashSecret

{

NSString *url = [NSString stringWithFormat:@"%@/%@", endpoint, environmentKey];

NSLog( @"%@",url);

return [NSURL URLWithString:url];

}

Now find the code in your game that you use to Start the deltaDNA SDK and replace it with the new startWithProjectId method.You will need to provide your projectID and Environment Name, the ones below belong to an internal Unity Demo Game. Check the REST API Migration Guide for more information on the URL formatting and where to find your projectIdThat’s it, your deltaDNA SDK should now be sending events directly to Unity Analytics. Use a network proxy like Charles or Fiddler to check that your 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.

 [[DDNASDK sharedInstance] startWithProjectId:@"25088b95-5df2-4352-9d7b-e72d48d9e5fe"
                              environmentName:@"production"
                                   collectURL:@"https://collect.analytics.unity3d.com/api/analytics/collect/v1/projects"];

[[DDNASDK sharedInstance] startWithProjectId:@"25088b95-5df2-4352-9d7b-e72d48d9e5fe"

environmentName:@"production"

collectURL:@"https://collect.analytics.unity3d.com/api/analytics/collect/v1/projects"];

There are a few housekeeping modifications to finish off with. Open the DeltaDNA/Impl/Helpers/DDNASettings.m file and modify the DDNA_SDK_VERSION constant to make it obvious in your Analytics data that events are originating from the modified iOS SDK

C#

NSString *const DDNA_SDK_VERSION = @"iOS SDK v5.0.2(UGS)";

1

NSString *const DDNA_SDK_VERSION = @"iOS SDK v5.0.2(UGS)";
To prevent the SDK reaching out to Engage to retrieve event and campaign info on launch, you can comment out or remove the contents of the requestSessionConfiguration method in the DeltaDNA/Impl/DDNATrackingSdk.m file. Replace the contents of it with the following to ensure that the automated gameStarted and clientDevice events continue to be sent on launch

C#

self.eventWhitelist = nil; [self triggerDefaultEvents:self.sendNewPlayerEvent];

1
2

self.eventWhitelist = nil;
[self triggerDefaultEvents:self.sendNewPlayerEvent];
Finally to prevent any Engage requests reaching out to the deltaDNA Engage service, open the DeltaDNA/Impl/DDNATrackingSdk.m file, locate the requestEngagement method and remove or comment out its contents and replace them with a return statement.If you are using Engage Decision Point or Event Triggered campaigns you may want to just comment this out for now so you can refactor it to use Unity Remote Config later.

C#

- (void)requestEngagement:(DDNAEngagement *)engagement engagementHandler:(void (^)(DDNAEngagement *))engagementHandler { NSLog(@"Skipping Engage Request"); return; }

1
2
3
4
5

- (void)requestEngagement:(DDNAEngagement *)engagement engagementHandler:(void (^)(DDNAEngagement *))engagementHandler
{
NSLog(@"Skipping Engage Request");
return;
}