# Using the ConfigCat SDK in Unity

Copy page

## Getting Started[​](#getting-started "Direct link to Getting Started")

ConfigCat provides support for feature flagging in Unity applications and games via the [ConfigCat .NET SDK](https://configcat.com/docs/sdk-reference/dotnet.md).

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[​](#1-get-the-sdk-assembly-files "Direct link to 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:

* [ConfigCat.Client v9.3.2+](https://www.nuget.org/packages/ConfigCat.Client)
* [Microsoft.Bcl.AsyncInterfaces v6.0.0](https://www.nuget.org/packages/Microsoft.Bcl.AsyncInterfaces/6.0.0)
* [System.Buffers v4.5.1](https://www.nuget.org/packages/System.Buffers/4.5.1)
* [System.Memory v4.5.4](https://www.nuget.org/packages/System.Memory/4.5.4)
* [System.Numerics.Vectors v4.5.0](https://www.nuget.org/packages/System.Numerics.Vectors/4.5.0)
* [System.Runtime.CompilerServices.Unsafe v6.0.0](https://www.nuget.org/packages/System.Runtime.CompilerServices.Unsafe/6.0.0)
* [System.Text.Encodings.Web v6.0.0](https://www.nuget.org/packages/System.Text.Encodings.Web/6.0.0)
* [System.Text.Json v6.0.10](https://www.nuget.org/packages/System.Text.Json/6.0.10)
* [System.Threading.Tasks.Extensions v4.5.4](https://www.nuget.org/packages/System.Threading.Tasks.Extensions/4.5.4)

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](https://dotnet.microsoft.com) installed, you can take a shortcut:

1

Create a file named `Plugins.csproj` (anywhere in your file system) with the following content:

```xml
<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[​](#2-add-the-sdk-assembly-files-to-your-unity-project "Direct link to 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[​](#3-create-a-script-for-hosting-the-configcat-client "Direct link to 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:

```cs
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](https://github.com/configcat/.net-sdk/blob/master/samples/UnityWebGL/Assets/Scripts/SingletonServices.cs).

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[​](#4-get-your-setting-value "Direct link to 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:

```cs
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](https://configcat.com/docs/sdk-reference/dotnet.md#snapshots-and-non-blocking-synchronous-feature-flag-evaluation).

## Platform compatibility[​](#platform-compatibility "Direct link to 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](https://docs.unity3d.com/2021.3/Documentation/Manual/ScriptingRestrictions.html).

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](https://github.com/configcat/.net-sdk/issues/new/choose) or [contact support](https://configcat.com/support).

## Further reading[​](#further-reading "Direct link to Further reading")

You can read about the configuration and the advanced features of the ConfigCat .NET SDK [here](https://configcat.com/docs/sdk-reference/dotnet.md).

## Guides[​](#guides "Direct link to Guides")

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

* [How to use feature flags in Unity](https://configcat.com/blog/2023/01/27/how-to-use-feature-flags-in-unity/) (partly outdated)

## Look under the hood[​](#look-under-the-hood "Direct link to Look under the hood")

* [ConfigCat .NET SDK on GitHub](https://github.com/configcat/.net-sdk)
* [ConfigCat .NET SDK on nuget.org](https://www.nuget.org/packages/ConfigCat.Client)