PageSense Node.js SDK

The PageSense Node.js SDK enables developers to integrate FullStack A/B testing and experimentation into their Node.js applications.

The SDK evaluates experiments directly within the application runtime, allowing backend services to allocate experiment variations and track user engagement with minimal latency while keeping experiment configurations synchronized with the PageSense platform.

This approach ensures:

• Low-latency experiment evaluation
• Deterministic variation assignment
• Reduced dependency on network calls during request processing
• Accurate analytics and experiment reporting

Table of Contents

• Features
• Installation
• Requirements
• Quick Start
• SDK Initialization
• Activate Experiment
• Get Variation Name
• Track Goal
• SDK Configuration Options
• Architecture Overview
• Experiment Execution Flow
• Best Practices
• Debugging
• License

Features

The PageSense Node.js SDK provides the following capabilities:

• Run FullStack A/B tests in Node.js applications
• Deterministic variation allocation
• Evaluate audience targeting rules
• Track goal conversions and engagement events
• Store user attributes for report segmentation
• Synchronize project configuration automatically
• Support custom logger integration
• Support persistent user storage service
• Support webhook and polling-based project configuration updates

Installation

Install the PageSense Node.js SDK using npm:

npm install @zohopagesense/pagesense-node-sdk

Requirements

| Requirement | Version | | ----------- | ------- | | Node.js | >= 16 |

Quick Start

Import the SDK

const {
  PageSenseClientBuilder,
  PageSenseSDKOptions
} = require('@zohopagesense/pagesense-node-sdk');

SDK Initialization

The PageSenseClient is the primary interface provided by the PageSense Node.js SDK to run and manage FullStack A/B Test experiments within a Node.js application.

const sdkOptions = new PageSenseSDKOptions();

const pageSenseClient = await PageSenseClientBuilder.createNewPageSenseClient(
  accountId,
  sdkKey,
  projectName,
  sdkOptions
);

Parameters

| Parameter | Type | Description | | ----------- | ------------------- | ------------------------------------------------------------- | | accountId | String | Unique identifier of the PageSense account | | sdkKey | String | SDK key associated with the PageSense environment | | projectName | String | Name of the PageSense project containing the experiments | | sdkOptions | PageSenseSDKOptions | Optional configuration object used to customize SDK behaviour |

Activate Experiment

The activateExperiment API activates a FullStack experiment and determines the variation assigned to a user.

Method

const variationName = pageSenseClient.activateExperiment(experimentName, userId, userAttributes);

Parameters

| Parameter | Type | Description | | -------------- | ------ | ------------------------------------------------------------ | | experimentName | String | Name of the FullStack experiment configured in PageSense | | userId | String | Unique identifier representing the user | | userAttributes | Object | Key-value map of user attributes used for audience targeting |

Return Value

| Value | Description | | -------------- | --------------------------------------------- | | Variation Name | Returned if user qualifies for the experiment | | null | Returned if user does not qualify |

Example

const userAttributes = {
  Browser: 'Chrome',
  Device: 'Desktop',
  OS: 'Windows 10'
};

const variationName = pageSenseClient.activateExperiment(
  'Checkout_Experiment',
  'user_123',
  userAttributes
);

Get Variation Name

The getVariationName API retrieves the variation assigned to a user without triggering experiment tracking.

Method

const variationName = pageSenseClient.getVariationName(experimentName, userId, userAttributes);

Parameters

| Parameter | Type | Description | | -------------- | ------ | ------------------------------------------- | | experimentName | String | Name of the experiment | | userId | String | Unique user identifier | | userAttributes | Object | User attributes used for audience targeting |

Return Value

| Value | Description | | -------------- | --------------------------------- | | Variation Name | Returned if user qualifies | | null | Returned if user does not qualify |

Example

const userAttributes = {
  Browser: 'Chrome',
  Device: 'Desktop',
  OS: 'Windows 10'
};

const variationName = pageSenseClient.getVariationName(
  'Checkout_Experiment',
  'user_123',
  userAttributes
);

Track Goal

The trackGoal API records conversion events for FullStack experiments.

Method

pageSenseClient.trackGoal(experimentName, userId, goalName, userAttributes);

Parameters

| Parameter | Type | Description | | -------------- | ------ | ---------------------------------------- | | experimentName | String | Name of the experiment | | userId | String | Unique user identifier | | goalName | String | Name of the goal configured in PageSense | | userAttributes | Object | User attributes for segmentation |

Example

const userAttributes = {
  Browser: 'Chrome',
  Device: 'Desktop',
  OS: 'Windows 10'
};

pageSenseClient.trackGoal('Checkout_Experiment', 'user_123', 'PurchaseCompleted', userAttributes);

SDK Configuration Options

The SDK can be customized using PageSenseSDKOptions.

const sdkOptions = new PageSenseSDKOptions()
  .addLogLevel('DEBUG')
  .addCustomLogger(customLogger)
  .addCustomStorage(userStorageService)
  .addPollingInterval(10);

Available Options

| Option | Description | | -------------------- | ---------------------------------------- | | addPollingInterval() | Sets project settings polling interval | | addLogLevel() | Configures SDK logging verbosity | | addCustomLogger() | Registers a custom logger implementation | | addCustomStorage() | Enables persistent user storage |

Architecture Overview

| Layer | Description | | --------------------------- | ------------------------------------------------------------------------------- | | PageSenseClientBuilder | Responsible for constructing and initializing the SDK client instance | | PageSenseSDKOptions | Collects SDK configuration options such as polling, logging, and storage | | PageSenseClient | Main SDK interface used by applications to evaluate experiments and track goals | | Experiment Decision Engine | Evaluates experiment eligibility and determines variation allocation | | MurmurHash Bucketing Engine | Generates deterministic hash values used for variation allocation | | User Storage Service | Persists experiment-variation assignments for users across sessions | | Logger System | Handles SDK logging using built-in or custom logger implementations | | Messaging System | Generates standardized SDK log messages and error messages | | HTTP Communication Layer | Handles all outbound HTTP requests between the SDK and PageSense servers |

Experiment Execution Flow

1. SDK Initialization
2. Fetch Project Settings
3. User Request Received
4. Audience Targeting Evaluation
5. MurmurHash Bucketing
6. Variation Assignment
7. Application Executes Variation Logic
8. Goal Completion
9. Conversion Data Sent to PageSense

Best Practices

• Initialize the SDK during application startup
• Reuse a single SDK instance throughout the application lifecycle
• Use stable user identifiers
• Enable User Storage Service for persistent variation assignment
• Configure reasonable polling intervals
• Prefer webhook synchronization when available

Debugging

Enable detailed logging for debugging:

.addLogLevel("DEBUG")

Debug logs provide information about:

• Experiment evaluation
• Variation allocation
• Polling cycles
• HTTP requests
• SDK internal operations

License

Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/

Copyright © Zoho Corporation Private Limited

Licensed under the Apache License, Version 2.0.