Skip to main content

Integrating with Unity

This guide will walk you through the process of integrating and using the Honeygain SDK in your Unity application.

info

Don't forget to generate your Honeygain SDK API Key and download the SDK from the Developers dashboard first.

Import the Package​

The Honeygain SDK is provided as a Unity package file hgsdk.unitypackage. To import the package into your project, follow these steps:

  • In your Unity project, go to Assets > Import Package > Custom Package.
  • Select the hgsdk.unitypackage file and click Open.
  • In the Import Unity Package window, ensure all assets are checked and click Import.

Android-specific build settings​

For the Honeygain SDK to work properly on Android, the following changes are required in your project's build settings:

  • Add additional permissions in the AndroidManifest.xml file:
    • Go to Edit > Project Settings > Player > Android > Publishing Settings.
    • Check Custom Main Manifest.
    • Open the AndroidManifest.xml file, usually located at Assets/Plugins/Android/AndroidManifest.xml.
    • Add the following user permissions to the manifest element:
    AndroidManifest.xml
    <?xml version="1.0" encoding="utf-8"?>
    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
      xmlns:tools="http://schemas.android.com/tools">

      <uses-permission android:name="android.permission.INTERNET" />
      <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
      <uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />
      <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

      <application ...
      </application>
    </manifest>
  • Add additional dependencies in the mainTemplate.gradle file:
    • Go to Edit > Project Settings > Player > Android > Publishing Settings.
    • Check Custom Main Gradle Template.
    • Open the mainTemplate.gradle file, usually located at Assets/Plugins/Android/mainTemplate.gradle.
    • Add the following lines to the dependencies section:
    mainTemplate.gradle
    dependencies {
      implementation 'org.msgpack:msgpack-core:0.9.8'
      implementation 'com.google.protobuf:protobuf-javalite:3.25.3'
      implementation("com.squareup.okhttp3:okhttp:4.12.0")
      implementation 'org.jetbrains.kotlin:kotlin-stdlib-jdk7:2.0.21'
      implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.0")
      implementation fileTree(dir: 'libs', include: ['*.jar'])
    **DEPS**}

Using the Package​

After importing the Honeygain SDK Unity package, you will find the Hgsdk prefab in the Assets/Hgsdk directory. To use it, drag the Hgsdk prefab into your scene.

Internally, the Hgsdk prefab has game objects representing Consent Forms for both Desktop and Mobile platforms. When integrating, you can use these Consent Forms as they are or create your own custom UI for the Consent Form.

The main Hgsdk game object is attached to the Controller script. For this script to work properly, you need to specify the Honeygain SDK API key in the Inspector window. This script exposes the following methods that can be called from other scripts or used in the Inspector window:

  • StartService() - starts the SDK service with the API key specified in the Inspector window if user consent is given.
  • StopService() - stops the SDK service.
  • OptInService() - opts in to the SDK service by giving user consent.
  • OptOutService() - opts out of the SDK service by removing user consent; the service is also stopped if it was running.
  • ShowConsent() - shows the default Consent Form. On accepting, OptInService() and StartService() will be called.
  • InitService() - calls ShowConsent() if user consent is not given, or StartService() if user consent is given but the service is not running.
  • LogService() - enable SDK service logging.
  • MuteService() - disable SDK service logging.

The Controller script also exposes the following events that can be subscribed to in the Inspector window:

  • ConsentAccepted - invoked after the user clicks the Accept button in the default Consent Form.
  • ConsentDeclined - invoked after the user clicks the Decline button in the default Consent Form.

Advanced Scripting​

The Honeygain SDK Unity package also contains a Service script that can be used for more advanced integration of the SDK in your Unity project.

note

Note that .Start() and .Stop() method calls are non-blocking operations. Internally, SDK service starting and stopping are asynchronous operations, and there might be a slight delay before the action actually happens.

Starting the SDK Service​

To start the SDK service, call the .Start() method:

bool consent = Hgsdk.Service.Start("your-api-key");

It will check if explicit user consent was given before. Information about the current state of user consent is returned by the method. If user consent was given previously, the SDK service will start immediately. If user consent was not given previously, the SDK service will not start, and the method will return false.

note

The method parameter is your API Key provided by the Honeygain SDK.

Stopping the SDK Service​

To stop the SDK service, call the .Stop() method:

Hgsdk.Service.Stop();

Verifying the SDK Service State​

To verify if the SDK service is running, call the .IsRunning() method:

bool running = Hgsdk.Service.IsRunning();

This is an immediate operation and reports the SDK service state at the current time without blocking.

To provide user consent, call the .OptIn() method:

Hgsdk.Service.OptIn();

This stores information that user consent was given and informs the SDK service that it can start. Subsequent calls to .Start() will be allowed to start the SDK service.

To revoke user consent, call the .OptOut() method:

Hgsdk.Service.OptOut();

This stores information that user consent was revoked and informs the SDK service that it should stop if it is running. Subsequent calls to .Start() will not be allowed to start the SDK service.

To verify if user consent was given, call the .IsOptedIn() method:

bool consent = Hgsdk.Service.IsOptedIn();

This method returns the stored information about the user consent state.

Enable logging​

To enable logging, call the .Log() method:

Hgsdk.Service.Log();

Enable logging for SDK service.

On Android Logcat will be used.

On Windows log file will be created in the current working directory of your application. Log is also writen to standard output.

Disable logging​

To disable logging, call the .Mute() method:

Hgsdk.Service.Mute();

Disable logging for SDK service.

Sample Project​

To help you get started quicker, we have prepared a sample Unity project that already includes the Honeygain SDK integration and basic setup. ➡️ Download Sample Project

Tips & Tricks​

tip

On Android, you can get longer user sessions if you ask the user to disable battery optimization for your application, as it will help the SDK run longer in the background.