Get started
Installation
This guide will walk you through the process of installation our SDK into your Unity project.
Unity Package Manager
Follow these steps to install the Noctua SDK:
- Open the Unity Package Manager by navigating to Window > Package Manager in your Unity project.
- Click the "+" button in the top-left corner, then select Add package from git URL...

External Dependency Manager
Note
The Noctua SDK relies on this plugin to manage platform dependencies. If you have already installed Google's External Dependency Manager, you can skip this step.
- Enter the following package URL:
https:/googlesamples/unity-jar-resolver.git?path=upm
Noctua SDK
- Enter the Noctua SDK package URL:
https:/NoctuaLabs/noctua-unity-sdk-upm.git#0.4.0
Tip
See our Release Notes to find the latest version of the SDK and install a specific version by append #x.x.x
to the package URL, where x.x.x
is the desired version number. For example:
https:/NoctuaLabs/noctua-unity-sdk-upm.git#0.2.0
If you don't specify a version, the latest version of the Noctua SDK will be installed.
Platform-Specific Settings
After installing the External Dependency Manager, configure these additional settings based on your target platform(s):
Android Settings
- Enable custom Gradle templates:
- Go to Edit > Project Settings > Player > (Android Logo) > Publishing Settings.
- Check the box for Custom Main Manifest
- Check the box for Custom Main Gradle Template
- Check the box for Custom Gradle Properties Template
Important
Unity Editor 2022.3 or later is required to check the additional box for Custom Gradle Settings Template.

- Set minimum API level to 24 or higher.

Resolving Dependencies
After configuring platform-specific settings:
- Navigate to Assets > External Dependency Manager > Android Resolver
- Click Resolve
iOS Settings
Cocoapods is no longer used. The Noctua SDK has been migrated to use Swift Package Manager (SPM) in the latest version.
You do not need to install or configure Cocoapods anymore.
Final Manual Step: Embed & Sign
After exporting the iOS project from Unity and opening it in Xcode:
- Select the
Unity-iPhone
target. - Open the General tab.
- Scroll to Frameworks, Libraries, and Embedded Content.
- Ensure
NoctuaSDK
is listed with "Embed & Sign".
Why Embed & Sign?
This ensures the SDK is properly bundled and signed in your final iOS build.
Skipping this may cause runtime crashes or missing framework errors.

⚠️ Cocoapods Deprecated
- Install Cocoapods:
- Go to Assets > External Dependency Manager > iOS Resolver > Install Cocoapods
Note
If you already have Cocoapods installed, you can skip this step.
- Check these items in iOS Resolver > Settings Window

Configuration
To set up and start using the Noctua SDK in your project, follow these steps:
Configuration
Note
Contact the Noctua Team to obtain the configuration file. This file also includes settings for 3rd-party services. See how to get SDK Client ID here.
- Obtain the
noctuagg.json
configuration file from the Noctua Team. - Copy the
noctuagg.json
file to theAssets/StreamingAssets
directory in your Unity project. - If you get config files 3rd-party services such as Firebase from us (
google-services.json
andGoogleService-Info.plist
) also copy toAssets/StreamingAssets
directory
Initialization
To initialize the Noctua SDK:
- Create a new C# script named
NoctuaSDKInitializer.cs
in your project. - Add the following content to the script:
using UnityEngine;
using com.noctuagames.sdk;
public class NoctuaSDKInitializer : MonoBehaviour
{
private async void Awake()
{
try
{
await Noctua.InitAsync();
}
catch (NoctuaException e)
{
// Handle the exception
}
}
}
Important
If our SDK initialization process returns an exception, the user should be prevented from proceeding further. You must handle the exception from SDK init and display an error dialog. The dialog could suggest that the user restart the game or retry the initialization process.
- In your Unity project:
- Create an empty GameObject in your first scene (the scene that loads when your game starts).
- Name this GameObject "NoctuaSDKInitializer" (or any name you prefer).
- Attach the
NoctuaSDKInitializer.cs
script to this GameObject.
Tip
Ensure that the GameObject with the NoctuaSDKInitializer script is present in every initial scene of your game. This guarantees that the Noctua SDK is always initialized when your game starts, regardless of which scene is loaded first.