Totum.Flags 2.0.3

Totum.Flags

.NET client for Totum feature flags. Call InitAsync once at startup, then read flags synchronously from memory — with background refresh and safe fallbacks when the network is unavailable.

Targets .NET Standard 2.1 (.NET Framework 4.7.2+, .NET Core 3.0+, .NET 5+, Unity).

AI agents & developers: use AGENT.md — copy into your app repo (.cursor/rules, AGENTS.md) for correct flag integration. This README is the full reference.

Install

The SDK is split into four NuGet packages. Pick the row that matches your app:

# ASP.NET Core
dotnet add package Totum.Flags.Extensions.DependencyInjection

# .NET (non-ASP.NET)
dotnet add package Totum.Flags
dotnet add package Totum.Flags.SystemTextJson

# Unity
dotnet add package Totum.Flags
dotnet add package Totum.Flags.NewtonsoftJson

Prerequisites — proxy URL and API key

Every app needs two values from your platform team (see SETUP-WORKER §8):

The names FLAGS_PROXY_URL and FLAGS_API_KEY are conventions for server apps (env vars, appsettings.json). The SDK does not read those names itself — you pass the strings into FlagsClientOptions.

Do not put Cloudflare account tokens or Flagship credentials in app code. The proxy API key is an app-level gate (similar to a mobile app API key): it ships with the client, but it is not a Cloudflare account secret.

.NET / ASP.NET

Load from environment variables, appsettings.json, or your secrets store:

{
  "FLAGS_PROXY_URL": "https://flags.totumcloud.com",
  "FLAGS_API_KEY": "your-proxy-key"
}

Unity

Unity has no process.env or appsettings.json. Use a ScriptableObject or build-time config — not PlayerPrefs. Full guide: Unity configuration below.

Quick start

.NET (System.Text.Json)

using Totum.Flags;
using Totum.Flags.SystemTextJson;

var flags = FlagsClientFactory.Create(new FlagsClientOptions
{
    ProxyUrl = Environment.GetEnvironmentVariable("FLAGS_PROXY_URL")!,
    ApiKey = Environment.GetEnvironmentVariable("FLAGS_API_KEY")!,
});

await flags.InitAsync(new[]
{
    new FlagDeclaration("my-app-dark-mode", FlagType.Boolean, false),
    new FlagDeclaration("my-app-checkout-flow", FlagType.String, "v1"),
});

// Synchronous — no await on getters
var darkMode = flags.GetBoolean("my-app-dark-mode", false);
var checkout = flags.GetString("my-app-checkout-flow", "v1");

Unity (Newtonsoft.Json)

See the full Unity section for where ProxyUrl and ApiKey come from. Minimal usage:

using Totum.Flags;
using Totum.Flags.NewtonsoftJson;

var flags = FlagsClientFactory.Create(new FlagsClientOptions
{
    ProxyUrl = config.ProxyUrl,
    ApiKey = config.ApiKey,
});

await flags.InitAsync(declarations);
var enabled = flags.GetBoolean("video-uploader-metrics-enabled", false);

Unity

Where do ProxyUrl and ApiKey come from?

1. Platform team provisions the Worker and adds your app to API_KEYS (SETUP-WORKER §8).
2. They give you the proxy URL (e.g. https://flags.totumcloud.com) and an API key for your build (e.g. totum-mobile-prod-key).
3. Your Unity project stores those two strings in app config and passes them to FlagsClientOptions at startup.

You do not read FLAGS_PROXY_URL / FLAGS_API_KEY from the environment in Unity. You do not use PlayerPrefs for URL or API key — PlayerPrefs is per-user, editable at runtime, and the wrong place for app configuration.

Recommended pattern: ScriptableObject per environment

Use one config asset per environment. Swap the asset (or its values) for Dev, Staging, and Production builds.

1. Config asset — Assets/Scripts/Flags/FlagsRuntimeConfig.cs:

using UnityEngine;

[CreateAssetMenu(fileName = "FlagsRuntimeConfig", menuName = "Totum/Flags Runtime Config")]
public sealed class FlagsRuntimeConfig : ScriptableObject
{
    [Tooltip("From platform team — e.g. https://flags.totumcloud.com")]
    public string ProxyUrl = "";

    [Tooltip("From platform team — one key from Worker API_KEYS")]
    public string ApiKey = "";
}

2. Create assets in the Editor

3. Bootstrap — wire config into the client once at startup:

using System.Collections.Generic;
using System.IO;
using Totum.Flags;
using Totum.Flags.NewtonsoftJson;
using UnityEngine;

public sealed class FlagsBootstrap : MonoBehaviour
{
    [SerializeField] private FlagsRuntimeConfig config = null!;

    private FlagsClient? _client;

    private async void Start()
    {
        _client = FlagsClientFactory.Create(new FlagsClientOptions
        {
            ProxyUrl = config.ProxyUrl,
            ApiKey = config.ApiKey,
            PersistFilePath = Path.Combine(Application.persistentDataPath, "flags_cache.json"),
        });

        await _client.InitAsync(new[]
        {
            new FlagDeclaration("video-uploader-metrics-enabled", FlagType.Boolean, false),
        });
    }

    private void OnDestroy() => _client?.Dispose();

    public bool IsMetricsEnabled() =>
        _client?.GetBoolean("video-uploader-metrics-enabled", false) ?? false;
}

4. Assign the right asset — drag FlagsRuntimeConfig.dev.asset onto the config field in the Inspector for local work. CI replaces or selects the prod asset before a release build.

Switching environments

What to use — and what to avoid

CI / release builds (sketch)

Your pipeline holds the prod API key as a secret. Before BuildPlayer, generate or patch the prod config:

# Example: write prod config (paths vary per project)
echo '{"ProxyUrl":"https://flags.totumcloud.com","ApiKey":"'"$FLAGS_API_KEY"'"}' \
  > Assets/StreamingAssets/flags-config.json

Or use Unity -executeMethod to assign fields on FlagsRuntimeConfig.prod.asset from environment variables your CI provides.

Troubleshooting (Unity)

Flag keys

Use hyphen-separated prefixes per product:

• totum-admin-dark-mode
• video-uploader-metrics-enabled

Each flagKey must exist in the flag dashboard with the matching type.

Dashboard: Enabled is not the same as true

Integration pattern

1. One FlagsClient per app (singleton).
2. await InitAsync(declarations[, context]) once — list every flag you read.
3. GetBoolean / GetString / GetNumber / GetObject are synchronous.
4. await RefreshAsync(context) after login or targeting changes.
5. Dispose() when tearing down (stops background refresh).

Targeting context

await flags.InitAsync(declarations, EvaluationContext.From(new Dictionary<string, object>
{
    ["userId"] = "anonymous",
}));

await flags.RefreshAsync(EvaluationContext.From(new Dictionary<string, object>
{
    ["userId"] = user.Id,
    ["plan"] = user.Plan,
}));

Optional file persistence

.NET — any writable path:

PersistFilePath = Path.Combine(Path.GetTempPath(), "flags_cache.json"),

Unity — use Application.persistentDataPath (see Unity bootstrap example).

ASP.NET Core

Install Totum.Flags.Extensions.DependencyInjection and register in Program.cs:

using Totum.Flags;
using Totum.Flags.Extensions.DependencyInjection;

builder.Services.AddTotumFlags(
    builder.Configuration,
    new[]
    {
        new FlagDeclaration("my-app-dark-mode", FlagType.Boolean, false),
        new FlagDeclaration("my-app-checkout-flow", FlagType.String, "v1"),
    });

var app = builder.Build();
// InitAsync runs automatically via IHostedService — inject IFlagsClient in controllers/services

Custom TTL, cache path, or HttpClient:

builder.Services.AddTotumFlags(options =>
{
    options.ProxyUrl = builder.Configuration["FLAGS_PROXY_URL"]!;
    options.ApiKey = builder.Configuration["FLAGS_API_KEY"]!;
    options.Ttl = TimeSpan.FromMinutes(5);
}, declarations);

Advanced: custom JSON codec

If you need direct control, set JsonCodec on FlagsClientOptions and construct FlagsClient yourself:

var options = new FlagsClientOptions
{
    ProxyUrl = proxyUrl,
    ApiKey = apiKey,
    JsonCodec = SystemTextJsonCodec.Instance,
};
var flags = new FlagsClient(options);

Client options

Caching and failures

Fallback order:

1. Fresh batch response
2. In-memory cache
3. Persisted file (if PersistFilePath set)
4. defaultValue passed to getters

InitAsync and RefreshAsync do not throw on network errors. Diagnostics use System.Diagnostics.Trace with prefix [Totum.Flags].

Anti-patterns

AI agents

• .NET: load proxy URL and API key from env / appsettings (FLAGS_PROXY_URL, FLAGS_API_KEY).
• Unity: load from ScriptableObject or build config — not env vars, not PlayerPrefs.
• List every flag in InitAsync before calling getters.
• Do not bypass this client for routine flag reads.

License

Closed Source. Proprietary & Confidential. See package LICENSE.