API

This section documents all APIs of experiments and events. The methods are only available through Ascend. To get all the methods, use following:

// This returns the object which contains all the methods
import { Experiments } from '@dreamhorizonorg/ascend-react-native';

// Use the Experiments object to access all methods
console.log(Experiments);

---

Experiments

Method	Return Type
getStringFlag(experiment_key: string, variable: string)	Promise<string>
getBooleanFlag(experiment_key: string, variable: string)	Promise<boolean>
getNumberFlag(experiment_key: string, variable: string)	Promise<number>
getAllVariables(experiment_key: string)	Promise<any>
fetchExperiments(defaultValues: object)	Promise<void>
refreshExperiment()	Promise<void>

---

Method Details

1. getStringFlag

Retrieves a string value from an experiment

Parameters:

• experiment_key: The experiment identifier (e.g., “button_exp_test”)
• variable: Variable name within the experiment (required)

Returns: String value with fallback to "" (empty string)

Fallback Order:

1. Experiment map (fetched from server)
2. Default map (provided at initialization)
3. Hard-coded "" (empty string)

Example:

import { Experiments } from '@dreamhorizonorg/ascend-react-native';

const color = await Experiments.getStringFlag('button_exp_test', 'color');

---

2. getBooleanFlag

Retrieves a boolean value from an experiment

Parameters:

• experiment_key: The experiment identifier (e.g., “feature_toggle”)
• variable: Variable name within the experiment (required)

Returns: Boolean value with fallback to false

Fallback Order:

1. Experiment map (fetched from server)
2. Default map (provided at initialization)
3. Hard-coded false

Example:

import { Experiments } from '@dreamhorizonorg/ascend-react-native';

const isEnabled = await Experiments.getBooleanFlag('feature_toggle', 'enabled');

---

3. getNumberFlag

Retrieves a number value from an experiment

Parameters:

• experiment_key: The experiment identifier (e.g., “retry_config”)
• variable: Variable name within the experiment (required)

Returns: Number value with fallback to -1

Fallback Order:

1. Experiment map (fetched from server)
2. Default map (provided at initialization)
3. Hard-coded -1

Example:

import { Experiments } from '@dreamhorizonorg/ascend-react-native';

const maxAttempts = await Experiments.getNumberFlag('retry_config', 'max_attempts');

---

4. getAllVariables

Retrieves all variables for a specific experiment as an object

Parameters:

• experiment_key: The experiment identifier

Returns: Object containing all variables, or default values if not found

Fallback Order:

1. Experiment map (fetched from server)
2. Default map (provided at initialization)
3. Empty object

Example:

import { Experiments } from '@dreamhorizonorg/ascend-react-native';

const allVars = await Experiments.getAllVariables('button_exp_test');
console.log('Variables:', allVars);

---

5. fetchExperiments

Fetches experiments from the backend server.

Parameters:

• defaultValues: Object of experiment keys with their default values (e.g., { "button_color": { "color": "blue" } })

Behavior:

• Appends the provided default values to the default map
• Triggers network requests to fetch the experiments
• API CALL - POST request to /v1/allocations endpoint (or configured apiEndpoint)

API Request Details:

• Method: POST
• Endpoint: Configured apiEndpoint (default: /v1/allocations)
• Headers:
  • x-experiment-keys: From configuration headers
  • user-id: Current user ID (if available)
  • content-type: application/json
  • Custom headers from configuration
• Body: JSON payload with experiment_keys, stable_id, user_id, and attributes

On Success:

• Updates experiment map with fetched experiments
• Removes experiments not in defaultExperiments
• Persists experiment map to local storage

On Error:

• Throws error with error message

Example:

import { Experiments } from '@dreamhorizonorg/ascend-react-native';

await Experiments.fetchExperiments({
  'button_color': {
    color: 'blue'
  }
});

---

6. refreshExperiment

Fetches experiments using predefined experiment keys in the default map

Parameters:

• None

Behavior:

• Uses existing default experiments (from configuration) to refresh
• Builds request from keys of the defaultExperiments map
• Triggers network request to fetch experiments
• API CALL - Same as fetchExperiments but uses default map keys

On Success:

• If shouldRefreshOnForeground is true, updates caching headers (e.g., cache window/last modified) from the response
• Parses response and updates experiment map
• Removes experiments not present in defaultExperiments
• Persists experiment map to local storage

On Error or Exception:

• Processes error (including 304 Not Modified handling) and throws error

Example:

import { Experiments } from '@dreamhorizonorg/ascend-react-native';

await Experiments.refreshExperiment();

---

Events

Coming soon…