Skip to content

Latest commit

 

History

History
195 lines (123 loc) · 11.8 KB

overview.md

File metadata and controls

195 lines (123 loc) · 11.8 KB

Didomi Unity plugin Internal Documentation

This document explains how the Didomi Unity plugin is structured and how to work on it.
This is an internal documentation for developers who want to modify the plugin itself, not include it in their app.

Overview

Unity has support for native plugins that are libraries of native code written for different platforms. The Didomi Unity plugin supports Android and iOS by wrapping the Didomi native mobile SDKs.

The plugin embeds the mobile SDKs in Unity projects by adding them to platform-specific folders (Plugins/Didomi/Android and Plugins/Didomi/IOS).

This plugin is built in two parts:

Native calls

Unlike other parts of Unity development, native plugins require platform-specific calls and interfaces for interacting with native code.
The native part of the plugin interacts with the Didomi native mobile SDKs.

For Android, Unity generates a Java project that is built and released. This plugin uses the AndroidJavaClass, AndroidJavaObject and AndroidJavaProxy C# classes provided by the UnityEngine namespace. Those classes are used to make calls to the Didomi Android SDK from C#. In particular, AndroidJavaProxy is used to pass C# function as callbacks to Java code.

For iOS, Unity generates an Objective-C project that is built and released. This plugin calls Objective-C functions exposed by the Didomi iOS SDK through the Objective-C++ file Plugins/Didomi/IOS/Didomi.mm. The Unity C# DLL can then call functions exposed in Plugins/Didomi/IOS/Didomi.mm.

C# interface

This plugin exposes a C# interface that interacts with the native libraries through the mechanism described.
This allows Unity projects to use a standard C# interface for interacting with the Didomi libraries.

Plugin Components

Special folders for Unity plugins

The Plugins/Didomi/Android, Plugins/Android/IOS, and Plugins/Didomi/Editor folders are special folders for Unity.

During the build process for mobile platforms, Unity generates an Android project and an iOS project:

The Plugins/Didomi/Editor folder is not copied to the target apps and is used by Unity during the build process.

The names of those folders must remain the same so that Unity can correctly build and embed the plugin into the release apps.

Main folders and files

Android

Plugins/Didomi/Android contains all the Android-related files of the plugin.

Plugins/Didomi/Android/libs is the folder where native Android libraries are located. Plugins/Didomi/Android/libs/android-didomi.aar is the Android AAR library released by Didomi and included in the plugin.

IOS

Plugins/Didomi/IOS contains all the iOS-related files of the plugin.

Plugins/IOS/libs is the folder where native iOS libraries are located. Plugins/Didomi/IOS/Didomi.framework is the iOS framework released by Didomi and included in the plugin.

Plugins/Didomi/IOS/Didomi.mm contains the Objective-C++ code that maps to native functions of the Didomi iOS SDK.
The Unity C# DLL can invoke the functions declared in that file. When a new function is added to the Didomi iOS SDK, the corresponding function must be added to the Plugins/Didomi/IOS/Didomi.mm file.

Plugins/Didomi/IOS/Newtonsoft.Json.dll contains additional JSON serializing and deserializing functions from Netwonsoft as Unity cannot serialize or deserialize DataDictionary or Array. Due to compatibility issue for illcpp, the netstandard 2.0 version of the library must be used.

Editor

Plugins/Didomi/Editor contains logic used by Unity during the build process.

Plugins/Didomi/Editor/PostProcessor.cs is a post-processing file that is executed by Unity after the native projects are generated.
We use it to adapt the generated native projects to work with the Didomi native mobile SDKs by updating the type of Activity used or configuring Swift libraries for the Objective-C project.

More detailed explanations on what post-processing is done on each platform is available:

Scripts

Plugins/Didomi/Scripts contains all the C# interfaces and logic of the Unity plugin.
Unity apps call a common interface and the plugin automatically calls the right implementation based on the platform that it is running on.

Plugins/Didomi/Scripts/Interfaces exposes the public interfaces used by Unity apps for interacting with the Didomi native mobile SDKs.

Platform-specific implementations are:

Plugins/Didomi/Scripts/Tests contains some automated tests for the C# classes in the plugin.

Workflows

Didomi Interface

Android

When running on the Android platform, calls from the Unity App to the Didomi Android SDK go through the following process:

-> Unity App -> Plugin -> AndroidDidomi -> (AndroidJavaClass, AndroidJavaObject and AndroidJavaProxy) -> Native android-didomi.aar library -> AndroidObjectMapper

IOS

When running on the iOS platform, calls from the Unity App to the Didomi iOS SDK go through the following process:

-> Unity App -> Plugin -> IOSDidomi -> DidomiFramework -> Didomi.mm -> Native Didomi.framework library -> IOSObjectMapper

Maintenance operations

Update the native Didomi SDKs

As Didomi releases new versions of their native SDKs, the Unity plugin needs to be updated to referencee them.

Detailed documentation on how to update native SDKs in the plugin is available:

Release a new version of the Didomi Unity plugin

Releasing a new version of the plugin consists of creating a Unity package from the Unity editor and then creating a Github release associated with that package.

Update the plugin version number

First, update the package.json file to increase the unity plugin version number. You need to also update the IOS Native SDK and Android Native SDK version numbers if they changed. package.json file is located at Assets\Plugins\Didomi\Resources folder.

{
  ...
  "version": "1.0.0",
  "iosNativeVersion": "1.20.1",
  "androidNativeVersion": "1.14.1",
  .....
}

Create the package

Create the package in the editor:

Create Unity Package

Go to the project menu in Unity and select "Export Package". In the next dialog, set "Didomi" as the name for the package.

The Didomi.unitypackage file will be created at the selected location.

Create a Github release

Create a new Github release and attach the created Didomi.unitypackage file to it.

Tests

The sample app can be used for testing:

DemoApp

The sample app allows testing every function manually. All functions exposed by the plugin are mapped to buttons. When clicking on the corresponding button for a given function, the result of the function call is displayed on the message pane.

Unity version

We currently require Unity version 2019.3.12f1 or later. More details on the version requirement can be found in the documentation.

Unity plugin development

A few useful reference links on Unity plugin Development: