> For the complete documentation index, see [llms.txt](https://lionstudios.gitbook.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lionstudios.gitbook.io/readme/analytics/api/helper-functions.md).

# Helper Functions

## **AB Testing**

#### **`AbCohort()`**

* **Overview**: The method should be called every session. If a user is in multiple AB tests, the method should be called multiple times. This will attach the cohort information to all events. To keep experiment information consistent across games for easier analysis, please do your best to use the following naming convention: `{game_code}_{platform}_{test.name}`
  * **game\_code** – Three-letter game code, e.g. FNI, SBP, FMT, etc.
    * If a game doesn't have a three-letter code, use full name: `game.that.doest.have.code`
  * **platform**
    * `ios` – iOS platform
    * `and` – Android platform
    * `all` – Both platforms (start and end dates should be equal)
  * **test.name** – Test name using dots (`.`) instead of spaces
* **Returns**: `void`
* **Parameters**:

| **Parameter**      | **type**                     | **Required** | **Description**             |
| ------------------ | ---------------------------- | ------------ | --------------------------- |
| `experimentName`   | `string`                     | Required     | The experiment name         |
| `experimentCohort` | `string`                     | Required     | The variant or cohort name. |
| `additionalData`   | `Dictionary<string, object>` | Optional     | Any additional information  |

## Code examples:

```csharp
LionAnalytics.AbCohort(
    experimentName: "levelRuns", 
    experimentCohort: "cohort_01");
```

{% hint style="info" %}
If a user is in multiple tests, the method should be called multiple times. This cohort data will be attached as a global parameter and will be included in the payload of all events afterwards. In order to clear an experiment, please use the `ClearAbCohort(string experimentName)` method.
{% endhint %}

#### **`ClearAbCohort()`**

* **Overview**: Clear an AbCohort Experiment (***Not commonly used***). Only use this if you set up client code to check for FeatureFlags during a session and can respond to players changing experiment participation mid-session.
* **Returns**: `void`
* **Parameters**:

| **Parameter**    | **type** | **Required** | **Description**                                                  |
| ---------------- | -------- | ------------ | ---------------------------------------------------------------- |
| `experimentName` | `string` | Required     | Name of the abCohort experiment to clear from proceeding events. |

## **Additional Data**

#### **`AddInitializationInfo()`**

* **Overview**: This method adds key-value data that will be included in the game\_started event's additional\_data.If called after game\_started event has already been automatically sent, the data will be sent as a separate debug event instead.We recommend to call this method in a `[RuntimeInitializeOnLoadMethod]` marked method to ensure it is included with the game\_started event. You can call this method multiple times to add more data. [See code example here](https://github.com/lionstudios/LionSuite/blob/release/Documentation/docs/analytics/api/gamestarted.md)
* **Returns**: `void`
* **Parameters**:

| **Parameter** | **type** | **Required** | **Description**                            |
| ------------- | -------- | ------------ | ------------------------------------------ |
| `key`         | `string` | Required     | The name of the item to add.               |
| `value`       | `object` | Required     | The value of the item you want to include. |

#### **`ClearAllGlobalData()`**

* **Overview**: Clears all the developer provided global additional data.
* **Returns**: `void`
* **Parameters**: None

#### **`ClearGlobalData()`**

* **Overview**: Clears an entry in the developer provided global additional data.
* **Returns**: `void`
* **Parameters**:

| **Parameter** | **type** | **Required** | **Description**                 |
| ------------- | -------- | ------------ | ------------------------------- |
| `key`         | `string` | Required     | The name of the item to remove. |

#### **`SetGlobalAdditionalData()`**

* **Overview**: This method allows developers to add their own global parameter values that will be fired off with every subsequent event.
* **Returns**: `void`
* **Parameters**:

| **Parameter** | **type**     | **Required** | **Description**                                                                                                            |
| ------------- | ------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `map`         | `Dictionary` | Required     | Developers can pass a Dictionary\<string, object> and the event will loop through and add all the desired key value pairs. |

* **Parameters overload 1**:

| **Parameter** | **type** | **Required** | **Description**                                             |
| ------------- | -------- | ------------ | ----------------------------------------------------------- |
| `item`        | `string` | Required     | The name of the data to add to as a global parameter value. |
| `val`         | `object` | Required     | The value associated with the key of the global parameter.  |

#### **`SetGlobalAdditionalDataCallback()`**

* **Overview**: Defines a callback that will be called whenever an event is fired. The values returned by this callback will be added to the additional data of that event. This allows developers to add their own global parameter values, following a defined logic.
* **Returns**: `void`
* **Parameters**:

| **Parameter** | **type**                                              | **Required** | **Description**                                                                                                          |
| ------------- | ----------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `callback`    | `Func<LionGameEventBase, Dictionary<string, object>>` | Required     | A callback function that takes the event being fired and returns a Dictionary of objects to add to its additional\_data. |

## Code examples:

```csharp
void Start()
{
    LionAnalytics.SetGlobalAdditionalDataCallback(AdditionalDataCallback);
}
private Dictionary<string, object> AdditionalDataCallback(LionGameEventBase eventBase)
{
    var dataToAdd = new Dictionary<string, object>();
    if (eventBase is HeartBeatEvent)
    {
        // Add additional data specifically for HearBeatEvent
        dataToAdd["memory_used"] = MyPerformanceManager.MemoryUsed;
    }
    // Add additional data for every event
    dataToAdd["current_level"] = MyLevelManager.CurrentLevel;
    return dataToAdd;
}
```

{% hint style="info" %}

* Devs can return different additionalData depending on the event being fired, or can return the same additionalData for every event.
  * (***'LionGameEventBase'***) is the abstract base class. The object passed to this callback will be one of the classes present in `Packages/Lion - Analytics/Runtime/Events`
    {% endhint %}

## **Game Data**

#### **`GetTotalTimeInApp()`**

* **Overview**: Returns the time in app variable that is being tracked on to all LA events currently.
* **Returns**: `int`
* **Parameters**: None

#### **`SetTutorial()`**

* **Overview**: Set Tutorial.
* **Returns**: `void`
* **Parameters**:

| **Parameter**   | **type** | **Required** | **Description**                                                 |
| --------------- | -------- | ------------ | --------------------------------------------------------------- |
| `tutorialState` | `bool`   | Required     | Value used to determine if an event is a tutorial or not.       |
| `trackMission`  | `string` | Required     | Used to check internally if a tutorial has started or finished. |

## **Monetization**

#### **`SetCurrencyBalance()`**

* **Overview**: This method sets the Currency Balance that will be attached to all events. It should be called anytime that currency is spent or received. to all events. It should be called anytime that virtual currency is spent or received.
* **Returns**: `void`
* **Parameters**:

| **Parameter** | **type** | **Required** | **Description**                                          |
| ------------- | -------- | ------------ | -------------------------------------------------------- |
| `type`        | `string` | Required     | The type of currency (typically soft or hard)            |
| `name`        | `string` | Required     | The name of the currency                                 |
| `balance`     | `double` | Required     | The new value of the player’s balance for that currency. |

{% hint style="warning" %}
`type` and `name` are case-sensitive. Consider using public constants to avoid typos.
{% endhint %}

#### **`SetItemBalance()`**

* **Overview**: This method sets the Item Balance that will be attached to all events. It should be called anytime that item is used or received. to all events. It should be called anytime that real currency is spent or received.
* **Returns**: `void`
* **Parameters**:

| **Parameter** | **type** | **Required** | **Description**                                      |
| ------------- | -------- | ------------ | ---------------------------------------------------- |
| `type`        | `string` | Required     | The type of item                                     |
| `name`        | `string` | Required     | The name of the item                                 |
| `balance`     | `double` | Required     | The new value of the player’s balance for that item. |

{% hint style="warning" %}
`type` and `name` are case-sensitive. Consider using public constants to avoid typos.
{% endhint %}

## **Player data**

#### **`ClearPlayerLevel()`**

* **Overview**: Clear a players level, and remove the tracking from other events.
* **Returns**: `void`
* **Parameters**: None

#### **`ClearPlayerScore()`**

* **Overview**: Clear a players score, and remove the tracking from other events.
* **Returns**: `void`
* **Parameters**: None

#### **`ClearPlayerXP()`**

* **Overview**: Clear Player XP.
* **Returns**: `void`
* **Parameters**: None

#### **`SetPlayerLevel()`**

* **Overview**: This method sets the global Player Level (account) value that will be attached to all events. It should be called anytime the Player Level changes.
* **Returns**: `void`
* **Parameters**:

| **Parameter** | **type**  | **Required** | **Description**                                                       |
| ------------- | --------- | ------------ | --------------------------------------------------------------------- |
| `playerLevel` | `integer` | Required     | This is the value of the player’s account level (not gameplay level). |

#### **`SetPlayerScore()`**

* **Overview**: This method sets the global Player Score value that will be attached to all events.
* **Returns**: `void`
* **Parameters**:

| **Parameter** | **type**  | **Required** | **Description**                          |
| ------------- | --------- | ------------ | ---------------------------------------- |
| `userScore`   | `integer` | Optional     | This is the value of the player’s score. |

#### **`SetPlayerXP()`**

* **Overview**: This method sets the global Player XP (experience) value that will be attached to all events. It should be called anytime the Player XP changes.
* **Returns**: `void`
* **Parameters**:

| **Parameter** | **type**  | **Required** | **Description**                                    |
| ------------- | --------- | ------------ | -------------------------------------------------- |
| `playerXp`    | `integer` | Required     | This is the value of the player’s XP (experience). |


---

# 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://lionstudios.gitbook.io/readme/analytics/api/helper-functions.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.