samhub.js
    Preparing search index...

    Class IdGraph

    IdGraph class for collecting and managing user identity signals.

    The IdGraph system collects various signals about users and their devices, manages signal collection through pluggable modules, and sends collected data to an analytics endpoint. It includes features like:

    • Automatic signal collection through modules
    • Sampling support for controlling tracking coverage
    • Device ID management with localStorage persistence
    • Automatic periodic flushing of signals
    • Signal hashing for privacy

    Basic usage:

    const idGraph = new IdGraph("my-container-id", {
      api_url: "https://analytics.example.com/pixel.gif",
      sampling: 0.8,
      debug: true
    });

    // Add custom signal
    await idGraph.addCustomSignal({
      name: "user_preference",
      value: "dark_mode",
      hashed: false
    });

    // Manually flush signals
    idGraph.flushSignals();

    // Clean up when done
    idGraph.destroy();
    Index

    Constructors

    constructor

    Methods

    addCustomSignal addSignal clearSignals destroy flushSignals getSignals

    Constructors

    • Creates a new IdGraph instance.

      Parameters

      • containerId: string

        Unique identifier for this container/application

      • options: IdGraphOptions = {}

        Configuration options for the IdGraph instance

      Returns IdGraph

      The constructor initializes the device ID, determines sampling eligibility, configures modules, and sets up automatic signal flushing if configured.

      const idGraph = new IdGraph("my-app", {
        sampling: 0.5,
        modules: ["browser_info"],
        flush_interval_ms: 10000
      });

    Methods

    • Adds a custom signal with automatic name prefixing.

      Parameters

      • signal: SignalData

        The custom signal data to add (name will be prefixed with "d_")

      Returns Promise<void>

      This method automatically prefixes the signal name with "d_" to distinguish custom signals from built-in module signals. This is the recommended way to add user-defined signals.

      await idGraph.addCustomSignal({
        name: "purchase_intent",
        value: "high",
        hashed: false
      });
      // Signal will be stored as "d_purchase_intent"

    • Adds a signal to the collection queue.

      Parameters

      • signal: SignalData

        The signal data to add

      Returns void

      This method is typically used internally by modules. For adding custom signals, consider using addCustomSignal instead.

      idGraph.addSignal({
        name: "browser_lang",
        value: "en-US",
        hashed: false
      });

    • Clears all collected signals from the queue.

      Returns void

      This method removes all signals without sending them. To send signals before clearing, use flushSignals instead.

      idGraph.clearSignals();

    • Cleans up resources and stops automatic signal flushing.

      Returns void

      Call this method when you're done using the IdGraph instance to prevent memory leaks from the automatic flush interval.

      idGraph.destroy();

    • Sends all collected signals to the analytics endpoint and clears the queue.

      Returns SignalData[]

      Array of signals that were flushed (empty if no signals or sampling prevented sending)

      This method is called automatically at the configured flush interval. You can also call it manually to force an immediate flush. If the device is not being tracked due to sampling, signals will be cleared but not sent.

      const flushedSignals = idGraph.flushSignals();
      console.log(`Flushed ${flushedSignals.length} signals`);

    • Returns the current array of collected signals.

      Returns SignalData[]

      Array of all signals currently in the queue

      This method does not clear the signals array. Use flushSignals to send and clear signals, or clearSignals to just clear them.

      const currentSignals = idGraph.getSignals();
      console.log(`${currentSignals.length} signals collected`);

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods