> For the complete documentation index, see [llms.txt](https://docs.hackle.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hackle.io/en/development-guide/dot-net.md).

# .NET

Get started with SDK integration quickly through a few steps.

* Step 1. Install SDK
* Step 2. Initialize SDK
* Step 3. A/B Test, Feature Flag
* Step 4. Track User Events

### Step 1. Install SDK

Add the SDK dependency.

```shell
Install-Package Hackle
```

### Step 2. Initialize SDK

HackleClient is the class that provides methods for using the SDK's features.\
To use the SDK, you need to initialize HackleClient.

#### Instantiation

Pass the SDK Key to instantiate `HackleClient`.\
`HackleClient` periodically synchronizes with the Hackle server as a background task to obtain the necessary information.

```csharp
var hackleClient = HackleClients.Create("YOUR_SERVER_SDK_KEY")
```

> ❗️ HackleClient must be a singleton.
>
> `HackleClient` manages state internally to distribute variations without blocking the calling thread. This requires additional resources. Instead of instantiating a new client for every request, it must be managed as a single instance throughout the application lifecycle.

### Step 3. A/B Test, Feature Flag

#### A/B Test

When running an A/B Test, you need to distribute users into variations and implement logic for each variation. You can use the Hackle SDK to handle user distribution.

> 📘 Variation
>
> A variation refers to the current baseline version (Control) and improved versions (Treatment) being tested, with one or more Treatment groups possible. You can configure this on the Dashboard. Refer to the \[A/B Test Settings]\(../A:B 테스트/manage-ab-dashboard/ab-settings.md) document for how to manage variations.

**variation**

Pass the **Experiment Key** to the `Variation()` method to distribute the user and receive the result. Then implement logic per variation.\
The Experiment Key is a unique number assigned to each A/B test and can be found in the Hackle Dashboard.\
The example code below passes experiment key 42, with two variations: A and B.

```csharp
using Hackle.Sdk;
using Hackle.Sdk.Common;

// Determines which variation to show to a user with identifier "ae2182e0"
// in the A/B test with experiment key 42.
// Returns variation A if a decision cannot be made.
var user = new HackleUserBuilder().Id("ae2182e0").Build();
var variation = hackleClient.Variation(42, user);

// Logic for the assigned variation
if (variation == Variation.A) {
  // Group A logic
} else if (variation == Variation.B) {
  // Group B logic
}
```

#### Feature Flag

A Feature Flag has an on state and an off state. Different features are configured for each state.\
When a user accesses a feature with a Feature Flag applied, they should receive either an on or off state. You can use the Hackle SDK to determine this state.

**isFeatureOn**

Pass the **Feature Key** to the `IsFeatureOn()` method to receive the state result for the user. Then implement logic based on the state.\
The Feature Key is a unique number assigned to each Feature Flag and can be found in the Hackle Dashboard.\
The example code below passes feature key 42.

```csharp
// Determines the user's state for the Feature Flag with feature key 42.
// Returns false (off state) if a decision cannot be made.
var user = new HackleUserBuilder().Id("ae2182e0").Build();
bool isFeatureOn = hackleClient.IsFeatureOn(42, user);

if (isFeatureOn) {
    // ON feature
} else {
    // OFF feature
}
```

#### Verifying Distribution Results

In the Hackle Dashboard, navigate to the A/B test or Feature Flag from the left menu, find the integrated item in the list, go to the detail page, and click the **Real-time Exposure Status** tab in the middle of the screen to view the distribution results from the SDK integration.

![2464](/files/prL9cUxSdUlEhLcPXMw1)

### Step 4. Track User Events

The Hackle SDK provides the ability to send user events to Hackle.\
By using this feature at every point where a change in user behavior occurs, you can obtain meaningful data about user behavior and analyze it.

**track**

Pass the **Event Key** to the `Track()` method to track user events. If needed, you can include a numeric value in `value` when tracking a user event.

* `value` only accepts the number type.

### Example 1

Suppose you defined the event key `purchase` to collect events when a user clicks the purchase button. You may also want to collect the purchase amount. In this case, you can include the purchase amount in `value`.

```csharp
// Send the "purchase" event triggered by a user with identifier "ae2182e0"
var user = new HackleUserBuilder().Id("ae2182e0").Build();
/* Example 1: Send event key only */
hackleClient.Track("purchase", user);

/* Example 2: Send event key with a numeric value */
var hackleEvent = HackleEvent.Builder("purchase").Value(10000).Build();
hackleClient.Track(hackleEvent, user);
```

Example 1 shows sending only the event key, while Example 2 shows including the purchase amount in `value` to collect it along with the event.

## Property

The Hackle SDK supports adding properties to Event objects.

* Properties must be sent as key-value pairs.
* A maximum of 64 properties can be added to an event object.

### Property Key

* Create keys like regular variable names, but make them easy to identify.
* Character limit is 64 characters.
* Case-insensitive. For example, `amount` and `AMOUNT` are recognized as the same key.

### Property Value

* value supports boolean, string, and number types.
* For string type, the character limit is 64 characters.
* For number type, up to 15 integer digits and up to 6 decimal places are supported.

### Example

The example below shows three properties (`pay_method`, `discount_amount`, `is_discount`) being added.

```csharp
var user = new HackleUserBuilder().Id("ae2182e0").Build();

var hackleEvent = HackleEvent.Builder("purchase")
  .Property("pay_method", "CARD")
  .Property("discount_amount", "800")
  .Property("is_discount", true)
  .Value(10000).Build();

hackleClient.Track(event, user);
```

#### Verifying User Event Tracking

Check whether user events sent from the SDK are being collected correctly.\
You can find the event sent via the SDK in the **Event Management** menu in the left sidebar of the Hackle Dashboard and check the real-time event collection status.

![2466](/files/ybGhEEyXmDhHNiG6pBPL)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.hackle.io/en/development-guide/dot-net.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.