Skip to main content
Version: Config V2

Using the ConfigCat SDK in Unity

Getting Started​

ConfigCat provides support for feature flagging in Unity applications and games via the ConfigCat .NET SDK.

However, compared to an ordinary .NET application, the installation process is different in Unity and requires a bit of extra effort. (Mainly because Unity doesn't support NuGet packages and uses .NET as a scripting platform.)

1. Get the SDK assembly files​

Since NuGet packages cannot be referenced in Unity projects directly, the SDK's assembly file (ConfigCat.Client.dll) and its dependencies must be added manually.

So, as a first step, you will need to get the assembly .dll files for netstandard2.0 from the following packages:

You can do this by downloading these packages and extracting the .dll files manually from the .nupkg files (which are actually plain ZIP files).

Or, if you have .NET installed, you can take a shortcut:

  1. Create a file named Plugins.csproj (anywhere in your file system) with the following content: 
    <Project Sdk="Microsoft.NET.Sdk">
      <PropertyGroup>
        <TargetFramework>netstandard2.0</TargetFramework>
      </PropertyGroup>
      <ItemGroup>
        <PackageReference Include="ConfigCat.Client" Version="*" />
      </ItemGroup>
    </Project>
  2. Run dotnet publish -c Release in the same folder.
  3. You will now have all the necessary .dll files in the bin/Release/netstandard2.0/publish folder.

2. Add the SDK assembly files to your Unity project​

Create a folder named Plugins in your Unity project's Assets, then copy the SDK assembly files into this folder.

3. Create a script for hosting the ConfigCat client​

To access your feature flags, you will need to create an instance of ConfigCatClient with your SDK Key. Usually you do this once, at the start of your application or game, then use the client throughout its lifetime.

However, sharing object instances between scripts is not straightforward in Unity. We recommend the following approach:

Create a folder named Scripts in your Unity project's Assets, then add a C# Script named SingletonServices to it. Replace the script content with the following code:

using System;
using System.Globalization;
using System.Threading;
using ConfigCat.Client;
using UnityEngine;

public class SingletonServices : MonoBehaviour
{
    private static SingletonServices instance;
    public static SingletonServices Instance => instance;

    [field: NonSerialized]
    public IConfigCatClient ConfigCatClient { get; private set; }

    private void Awake()
    {
        if (Interlocked.CompareExchange(ref instance, this, null) is not null)
        {
            // If another instance has been created already, get rid of this one.
            Destroy(this);
            return;
        }

        ConfigCatClient = ConfigCat.Client.ConfigCatClient.Get("YOUR_SDK_KEY", options =>
        {
            options.Logger = new ConfigCatToUnityDebugLogAdapter(LogLevel.Warning);
        });

        DontDestroyOnLoad(this.gameObject);
    }

    // Start is called before the first frame update
    void Start() { }

    // Update is called once per frame
    void Update() { }

    private void OnDestroy()
    {
        this.ConfigCatClient?.Dispose();
        this.ConfigCatClient = null;
    }

    private sealed class ConfigCatToUnityDebugLogAdapter : IConfigCatLogger
    {
        private readonly LogLevel logLevel;

        public ConfigCatToUnityDebugLogAdapter(LogLevel logLevel)
        {
            this.logLevel = logLevel;
        }

        public LogLevel LogLevel
        {
            get => this.logLevel;
            set { throw new NotSupportedException(); }
        }

        public void Log(LogLevel level, LogEventId eventId, ref FormattableLogMessage message, Exception exception = null)
        {
            var eventIdString = eventId.Id.ToString(CultureInfo.InvariantCulture);
            var exceptionString = exception is null ? string.Empty : Environment.NewLine + exception;
            var logMessage = $"ConfigCat[{eventIdString}] {message.InvariantFormattedMessage}{exceptionString}";
            switch (level)
            {
                case LogLevel.Error:
                    Debug.LogError(logMessage);
                    break;
                case LogLevel.Warning:
                    Debug.LogWarning(logMessage);
                    break;
                case LogLevel.Info:
                    Debug.Log(logMessage);
                    break;
                case LogLevel.Debug:
                    Debug.Log(logMessage);
                    break;
            }
        }
    }
}
caution

In case your application or game targets WebGL, this won't cut it. To make the ConfigCat SDK work, you will need additional code, as shown here.

Finally, to activate the SingletonServices script, add an empty GameObject to your first scene and assign the script to it.

4. Get your setting value​

Once the setup above is done, you will be able to access the ConfigCat client in your other scripts and use it to evaluate feature flags and settings:

var configCatClient = SingletonServices.Instance.ConfigCatClient;

var isMyAwesomeFeatureEnabled = await configCatClient.GetValueAsync("isMyAwesomeFeatureEnabled", false);
if (isMyAwesomeFeatureEnabled)
{
    doTheNewThing();
}
else
{
    doTheOldThing();
}
info

As you can see, feature flag evaluation is asynchronous by default, which in some cases may not play well with Unity's programming model. (Might lead to async void event handlers or other cumbersome solutions.) If this is the case for you, consider using non-blocking synchronous evaluation with snapshots.

Platform compatibility​

Proper support for Unity is available since ConfigCat .NET SDK v9.3.0. Earlier versions may work with certain build settings (although certainly not with WebGL), but it is recommended to use the latest SDK version.

According to our tests, the ConfigCat .NET SDK works fine with Unity 2021.3 or newer, over both the Mono and IL2CPP scripting backends.

As long as you use the netstandard2.0 build of the SDK and its dependencies, the "Api Compatibility Level" setting shouldn't matter, both the ".NET Framework" and ".NET Standard 2.1" options should be OK. If you experience any issue, try to set the "Api Compatibility Level" setting to ".NET Standard 2.1" on the Edit / Project Settings... / Player tab.

info

We strive to provide an extensive support for the various Unity versions and scripting backends. If you still encounter an issue with the SDK on some platform, please open a GitHub issue or contact support.

Further reading​

You can read about the configuration and the advanced features of the ConfigCat .NET SDK here.

Guides​

See the following guides on how to use ConfigCat's .NET SDK in Unity:

Look under the hood​