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:

  1. Open the Unity Package Manager by navigating to Window > Package Manager in your Unity project.
  2. Click the "+" button in the top-left corner, then select Add package from git URL...
Unity Package Manager
Unity Package Manager

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.

  1. Enter the following package URL:
https://github.com/googlesamples/unity-jar-resolver.git?path=upm

Noctua SDK

  1. Enter the Noctua SDK package URL:
https://github.com/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://github.com/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

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

Android Gradle Settings
Android Gradle Settings
  1. Set minimum API level to 24 or higher.
Android Minimum API Level
Android Minimum API Level

Resolving Dependencies

After configuring platform-specific settings:

  1. Navigate to Assets > External Dependency Manager > Android Resolver
  2. 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:

  1. Select the Unity-iPhone target.
  2. Open the General tab.
  3. Scroll to Frameworks, Libraries, and Embedded Content.
  4. 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.

iOS Embed & Sign
iOS Embed & Sign

⚠️ Cocoapods Deprecated

  1. Install Cocoapods:
    • Go to Assets > External Dependency Manager > iOS Resolver > Install Cocoapods

Note

If you already have Cocoapods installed, you can skip this step.

  1. Check these items in iOS Resolver > Settings Window
iOS Resolver Settings
iOS Resolver Settings

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.

  1. Obtain the noctuagg.json configuration file from the Noctua Team.
  2. Copy the noctuagg.json file to the Assets/StreamingAssets directory in your Unity project.
  3. If you get config files 3rd-party services such as Firebase from us (google-services.json and GoogleService-Info.plist) also copy to Assets/StreamingAssets directory

Initialization

To initialize the Noctua SDK:

  1. Create a new C# script named NoctuaSDKInitializer.cs in your project.
  2. 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.

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

Previous
Usage Requirements