@amplitude/experiment-js-client/dist/types/src/experimentClient.d.ts

Amplitude Experiment Javascript Client SDK

/**
 * @packageDocumentation
 * @module experiment-js-client
 */
import { ExperimentConfig } from './config';
import { Client, FetchOptions } from './types/client';
import { ExperimentPlugin } from './types/plugin';
import { ExperimentUserProvider } from './types/provider';
import { ExperimentUser } from './types/user';
import { Variant, Variants } from './types/variant';
/**
 * The default {@link Client} used to fetch variations from Experiment's
 * servers.
 *
 * @category Core Usage
 */
export declare class ExperimentClient implements Client {
    private readonly apiKey;
    private readonly config;
    private readonly variants;
    private readonly flags;
    private readonly flagApi;
    private readonly evaluationApi;
    private readonly engine;
    private user;
    private userProvider;
    private userSessionExposureTracker;
    private retriesBackoff;
    private poller;
    private isRunning;
    private readonly integrationManager;
    private readonly isWebExperiment;
    private analyticsProvider;
    /**
     * Creates a new ExperimentClient instance.
     *
     * In most cases you will want to use the `initialize` factory method in
     * {@link Experiment}.
     *
     * @param apiKey The Client key for the Experiment project
     * @param config See {@link ExperimentConfig} for config options
     */
    constructor(apiKey: string, config: ExperimentConfig);
    /**
     * Start the SDK by getting flag configurations from the server and fetching
     * variants for the user. The promise returned by this function resolves when
     * local flag configurations have been updated, and the {@link fetch()}
     * result has been received (if the request was made).
     *
     * To force this function not to fetch variants, set the {@link fetchOnStart}
     * configuration option to `false` when initializing the SDK.
     *
     * Finally, this function will start polling for flag configurations at a
     * fixed interval. To disable polling, set the {@link pollOnStart}
     * configuration option to `false` on initialization.
     *
     * @param user The user to set in the SDK.
     * @see fetchOnStart
     * @see pollOnStart
     * @see fetch
     * @see variant
     */
    start(user?: ExperimentUser): Promise<void>;
    /**
     * Stop the local flag configuration poller.
     */
    stop(): void;
    /**
     * Assign the given user to the SDK and asynchronously fetch all variants
     * from the server. Subsequent calls may omit the user from the argument to
     * use the user from the previous call.
     *
     * If an {@link ExperimentUserProvider} has been set, the argument user will
     * be merged with the provider user, preferring user fields from the argument
     * user and falling back on the provider for fields which are null or
     * undefined.
     *
     * If configured, fetch retries the request in the background on failure.
     * Variants received from a successful retry are stored in local storage for
     * access.
     *
     * If you are using the `initialVariants` config option to preload this SDK
     * from the server, you generally do not need to call `fetch`.
     *
     * @param user The user to fetch variants for.
     * @param options Options for this specific fetch call.
     * @returns Promise that resolves when the request for variants completes.
     * @see ExperimentUser
     * @see ExperimentUserProvider
     * @see FetchOptions
     */
    fetch(user?: ExperimentUser, options?: FetchOptions): Promise<ExperimentClient>;
    /**
     * Returns the variant for the provided key.
     *
     * Access the variant from {@link Source}, falling back  on the given
     * fallback, then the configured fallbackVariant.
     *
     * If an {@link ExposureTrackingProvider} is configured and the
     * {@link automaticExposureTracking} configuration option is `true`, this
     * function will call the provider with an {@link Exposure} event. The
     * exposure event does not count towards your event volume within Amplitude.
     *
     * @param key The key to get the variant for.
     * @param fallback The highest priority fallback.
     * @see ExperimentConfig
     * @see ExposureTrackingProvider
     */
    variant(key: string, fallback?: string | Variant): Variant;
    /**
     * Track an exposure event for the variant associated with the flag/experiment
     * {@link key}.
     *
     * This method requires that an {@link ExposureTrackingProvider} be
     * configured when this client is initialized, either manually, or through the
     * Amplitude Analytics SDK integration from set up using
     * {@link Experiment.initializeWithAmplitudeAnalytics}.
     *
     * @param key The flag/experiment key to track an exposure for.
     * @see ExposureTrackingProvider
     */
    exposure(key: string): void;
    /**
     * Returns all variants for the user.
     *
     * The primary source of variants is based on the
     * {@link Source} configured in the {@link ExperimentConfig}.
     *
     * @see Source
     * @see ExperimentConfig
     */
    all(): Variants;
    /**
     * Clear all variants in the cache and storage.
     */
    clear(): void;
    /**
     * Get a copy of the internal {@link ExperimentUser} object if it is set.
     *
     * @returns a copy of the internal user object if set.
     */
    getUser(): ExperimentUser;
    /**
     * Copy in and set the user within the experiment client.
     *
     * @param user the user to set within the experiment client.
     */
    setUser(user: ExperimentUser): void;
    /**
     * Get the user provider set by {@link setUserProvider} or null if the user
     * provider has not been set.
     *
     * @returns The user provider set by {@link setUserProvider} or null.
     * @deprecated use ExperimentConfig.userProvider instead
     */
    getUserProvider(): ExperimentUserProvider;
    /**
     * Sets a user provider that will inject identity information into the user
     * for {@link fetch()} requests. The user provider will only set user fields
     * in outgoing requests which are null or undefined.
     *
     * See {@link ExperimentUserProvider} for more details
     * @param userProvider
     * @deprecated use ExperimentConfig.userProvider instead
     */
    setUserProvider(userProvider: ExperimentUserProvider): Client;
    private mergeInitialFlagsWithStorage;
    private evaluate;
    private variantAndSource;
    /**
     * This function assumes the flag exists and is local evaluation mode. For
     * local evaluation, fallback order goes:
     *
     *  1. Local evaluation
     *  2. Inline function fallback
     *  3. Initial variants
     *  4. Config fallback
     *
     * If there is a default variant and no fallback, return the default variant.
     */
    private localEvaluationVariantAndSource;
    /**
     * For Source.LocalStorage, fallback order goes:
     *
     *  1. Local Storage
     *  2. Inline function fallback
     *  3. InitialFlags
     *  4. Config fallback
     *
     * If there is a default variant and no fallback, return the default variant.
     */
    private localStorageVariantAndSource;
    /**
     * For Source.InitialVariants, fallback order goes:
     *
     *  1. Initial variants
     *  2. Local storage
     *  3. Inline function fallback
     *  4. Config fallback
     *
     * If there is a default variant and no fallback, return the default variant.
     */
    private initialVariantsVariantAndSource;
    private fetchInternal;
    private cleanUserPropsForFetch;
    private doFetch;
    private doFlags;
    private storeVariants;
    private startRetries;
    private stopRetries;
    private addContext;
    private addContextOrWait;
    private sourceVariants;
    private secondaryVariants;
    private exposureInternal;
    private legacyExposureInternal;
    private debug;
    private shouldRetryFetch;
    /**
     * Add a plugin to the experiment client.
     * @param plugin the plugin to add.
     */
    addPlugin(plugin: ExperimentPlugin): void;
}