@naturalcycles/js-lib/dist/deviceIdService.d.ts

Standard library for universal (browser + Node.js) javascript

/// <reference lib="dom" preserve="true" />
/**
 * Service to generate, maintain, persist a stable "device id".
 *
 * It's called "device id" and not userId/visitorId, to indicate that it only identifies a device,
 * and has nothing to do with user identification.
 * User might be logged in or not.
 * User id can be the same on multiple devices.
 * DeviceId is unique per device, same User or not.
 *
 * Service provides methods to deterministically select fraction of devices.
 * For example, select 10% of devices that visit the website to be tracked by Analytics
 * (to reduce Analytics quota usage).
 * DeviceId persistence will ensure that recurring visits from the same device will yield the same
 * DeviceId, and same "selection assignment" (like an assignment in an AB test).
 *
 * @experimental
 */
export declare class DeviceIdService {
    constructor(cfg?: DeviceIdServiceCfg);
    cfg: Required<DeviceIdServiceCfg>;
    /**
     * `deviceId` is null only in anomalous cases, e.g when localStorage is not available (due to e.g "out of disk space" on device).
     * In all other cases it should be defined and stable (persisted indefinitely between multiple visits).
     *
     * It is null if the service is run on the server side.
     */
    deviceId: string | null;
    /**
     * Selects this device based on "deterministic random selection", according to the defined `rate`.
     * Rate is a floating number between 0 and 1.
     * E.g rate of 0.1 means 10% chance of being selected.
     *
     * Selection is based on deviceId, which is generated random and persisted between visits.
     * Persistence ensures that the selection (similar to an AB-test assignment) "sticks" to the device.
     *
     * If deviceId failed to be generated, e.g due to Device running out-of-space to save a string to localStorage,
     * it will NOT be selected.
     *
     * @returns true if the device is selected.
     */
    select(rate: number): boolean;
    /**
     * Deletes the persisted deviceId.
     * Keeps it in the service.
     * To remove it from the service, assign deviceIdService.deviceId = null.
     */
    clearPersistence(): void;
    /**
     * Generates a stable Device id if it wasn't previously generated on this device.
     * Otherwise, reads a Device id from persistent storage.
     */
    private init;
    private debug;
}
export interface DeviceIdServiceCfg {
    /**
     * Default: deviceId
     */
    localStorageKey?: string;
    /**
     * Set to true to enable debug logging.
     */
    debug?: boolean;
}