Skip to main content

.NET Backend SDK

The Hyppot .NET Backend SDK enables server-side feature experimentation in your .NET applications. This approach is ideal for backend logic, API behavior changes, and ensuring consistent cross-client experiences.

Installation and configuration​

In-process installation via Hyppot.AspnetCore​

If Hyppot is hosted in-process within your ASP.NET Core application using Hyppot.AspNetCore, interfaces are already configured and registered in .NET ServiceCollection. No additional configuration needed.

SDK configuration​

If you want to access Hyppot from a different .Net application (e.g. a different app module or a Docker-hosted Hyppot instance), you need to install and configure Hyppot.Sdk package:

  • install Hyppot.Sdk in your .Net application
  • go to "Configuration" tab in your Hyppot Administrative interface and generate the new API key,
  • in your IoC configuration (typically your Program.cs), add the following code to register SDK and provide the generated API key: 
    using Hyppot.Sdk; 

    // ... 

    services.AddHyppotSdk(cfg =>
      {
          cfg.BaseUrl = "https://address.to.your.hyppot.instance";
          cfg.ApiKey = "key_Xyz..."; 
          // cfg.PathPrefix = "/custom-prefix"; // if different than default
      })

    // ...

Basic Usage​

Dependency Injection​

After you have configured Hyppot, you can resolve IRolloutResolver and IRolloutTracker from IoC container:

// Services are available through DI
public class MyController : ControllerBase
{
    private readonly IRolloutResolver _resolver;
    private readonly IRolloutTracker _tracker;

    public MyController(
        IRolloutResolver resolver,
        IRolloutTracker tracker)
    {
        _resolver = resolver;
        _tracker = tracker;
    }
}

Resolving Feature Toggles​

Use IRolloutResolver to resolve feature toggles for a user. Feature toggles always return a VariantInstance (never null). If the user is outside of the toggle audience, the resolver returns the Off variant with the toggle’s off-configuration.

using Hyppot.Definition;
using Hyppot.Definition.Audience;
using Hyppot.Definition.Variables;
using Hyppot.Resolving;

// Resolve a specific feature toggle for a user
var toggle = await _resolver.ResolveFeatureToggleAsync(
    new RolloutId("new-checkout"),
    new UserId("user-123"));

// Check whether the feature is enabled for this user
if (toggle.IsActiveFeature)
{
    // Read variables from the toggle's "On" configuration
    var buttonColor = toggle.Variables
        .First(v => v.Name == new VariableName("button-color"))
        .Value.Get<string>();

    // Use values in your logic
    return new FeatureResponse
    {
        ButtonColor = buttonColor
    };
}
else
{
    // Fallback when feature is off for the user
    return new FeatureResponse
    {
        ButtonColor = "gray"
    };
}

Notes:

  • ResolveFeatureToggleAsync throws if the feature toggle does not exist.
  • Feature toggles do not produce impressions; impression tracking applies to experiments.

Resolving Experiments​

Use IRolloutResolver to get experiment variants for users:

// Resolve a specific experiment for a user
var experiment = _resolver.ResolveExperimentAsync(
    new RolloutId("button-color-test"), 
    new UserId("user-123"));

if (experiment != null)
{
    // Get variable values
    var buttonColor = experiment.Variables
        .First(v => v.Name == new VariableName("button-color"))
        .Value.Get<string>();
    
    // Use the values in your logic
    return new FeatureResponse
    {
        ButtonColor = buttonColor,
    };
}

Tracking Events​

Impression Tracking​

Track when users are exposed to experiment variants:

// Track impression when user sees the experiment
await _tracker.TrackImpressionAsync(
    Impression.Create(
        new RolloutId("button-color-test"),
        new VariantId("red-variant"),
        new UserId("user-123"),
        DateTime.UtcNow
    ));

// Track impression with deduplication key
await _tracker.TrackImpressionAsync(
    Impression.Create(
        new RolloutId("button-color-test"),
        new VariantId("red-variant"),
        new UserId("user-123"),
        DateTime.UtcNow,
        deduplicationKey: "page-view-123"
    ));

Conversion Tracking​

Track user actions as conversions:

// Track simple conversion
await _tracker.TrackConversionAsync(
    Conversion.Create(
        "button-click",
        DateTime.UtcNow,
        new UserId("user-123")
    ));

// Track conversion with metrics
var metrics = new VariableInstance[]
{
    new VariableInstance(
        new VariableName("revenue"), 
        new VariableValue<double>(125.50)
    ),
    new VariableInstance(
        new VariableName("product-category"), 
        new VariableValue<string>("electronics")
    ),
    new VariableInstance(
        new VariableName("is-premium"), 
        new VariableValue<bool>(true)
    )
};

await _tracker.TrackConversionAsync(
    Conversion.Create(
        "purchase-completed",
        DateTime.UtcNow,
        new UserId("user-123"),
        deduplicationKey: "order-456",
        metrics: metrics
    ));

User aliasing​

When the same person can have multiple identities (e.g. anonymous and logged-in), use user aliasing so Hyppot treats them as one user for contamination detection and excludes contaminated impressions from statistics. Inject IUserAliasService and call it when you know two IDs belong to the same person:

// After login: link anonymous and logged-in IDs
await _userAliasService.AliasUsersAsync(
    new[] { new UserId(anonymousId), new UserId(loggedInUserId) });

// Optional: keep aliases until a specific date (e.g. experiment end)
await _userAliasService.AliasUsersAsync(
    new[] { new UserId(anonymousId), new UserId(loggedInUserId) },
    keepAtLeastUntil: experimentEndDate);

See Contaminated data cleanup for the full guide and API details.

Best Practices​

  1. Always provide fallbacks - Never let experiments break your application
  2. Use dependency injection - Leverage ASP.NET Core's built-in DI
  3. Track impressions early - Track when users are exposed to experiments
  4. Validate experiment data - Don't trust experiment variables blindly
  5. Handle errors gracefully - Log errors but don't fail the user experience

Next Steps​