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. The SDK is currently supported on Android and Windows.

info

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

warning

Restriction for Google Play Apps. SDK cannot be integrated into applications distributed via Google Play. Minimum required Android API level is 21 (Android 5.0 / Lollipop). Also for Google Play integration you MUST talk to your account manager or someone from [email protected].

Import the Package​

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

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

Application permissions​

The SDK manages Android permissions automatically. It ships with a small Android plugin manifest that Unity merges into your app during Android builds, so you do not need to add any permissions manually.

note

Do not copy permission lines into your own AndroidManifest.xml unless you’re intentionally doing an advanced/manual override. Adding them manually in normal setups is unnecessary and can cause duplicate/merge issues.

Application dependencies​

The package includes an EDM4U dependency file that pulls required Android libraries automatically.

If you don't already have External Dependency Manager for Unity (EDM4U) installed:

  1. Go to Window → Package Manager → Add (＋) → Add package from Git URL…
  2. Enter the following URL: 
    https://github.com/googlesamples/unity-jar-resolver.git?path=upm
  3. Press Install.

(If the menu item is missing in your Unity version, add the same URL under "dependencies" in Packages/manifest.json.)

EDM4U usually auto-resolves dependencies when importing the SDK package.

If auto-resolution is disabled in your project, run Assets → External Dependency Manager → Android Resolver → Force Resolve once.

Running the sample scene​

The SDK package ships with a sample scene you can open and run immediately:

  1. After importing hgsdk.unitypackage, open Assets/Hgsdk/Sample/Scenes/ and load the sample scene.
  2. In the Hierarchy, select Hgsdk and paste your API Key into the Controller component’s field.
  3. Press Play in the Editor to see the default consent flow and service start/stop behavior.
  4. If your project targets Android, ensure EDM4U is installed to resolve dependencies automatically or add dependencies manually.
  5. For production integration, reuse the Hgsdk prefab in your own scenes or call the Hgsdk.Service API directly.

Using the Package​

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

Internally, the Hgsdk prefab provides default Consent Forms for Desktop and Mobile that you can use as-is or replace with your own UI.

The main Hgsdk GameObject 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.
    Non-blocking; start happens asynchronously. If consent is missing, the service will not start (see ShowConsent() / OptInService()).

  • StopService() — stops the SDK service. Non-blocking.

  • OptInService() — opts in to the SDK service by giving user consent; subsequent calls to StartService() will be allowed to start the service.

  • 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() — convenience initializer: 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 (Android: Logcat; Windows: file + stdout).

  • 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

.Initialize() must be called before any other SDK service method.

info

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

Initializing the SDK Service​

To initialize the SDK service, call the .Initialize() method:

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

This initializes the SDK service with your provided API key. Should be called before calling any other service method.

note

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

Starting the SDK Service​

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

bool consent = Hgsdk.Service.Start();

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.

Stopping the SDK Service​

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

Hgsdk.Service.Stop();

Identifying the SDK Service​

To retrieve the SDK service identity string, call the .Identify() method:

string identifier = Hgsdk.Service.Identify();

This is an immediate operation and returns an opaque string that uniquely identifies the running SDK service.

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 a log file will be created in the current working directory of your application. Log is also written to standard output.

Disable logging​

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

Hgsdk.Service.Mute();

Disable logging for SDK service.

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.