Best Practices

Best Practices

Best Practices  

Initialise once, at startup The SDK should be initialised before your server starts handling requests. This avoids race conditions where an experiment evaluation runs before the client is ready.
  1. const pageSenseClient = await PageSenseClientBuilder.createNewPageSenseClient(
  2.   accountId, sdkKey, projectName, sdkOptions
  3. );
Don't initialise inside request handlers — one instance for the lifetime of the application is all you need.
  1. Don't create multiple SDK instances The SDK is built to be initialised once and shared. Multiple instances mean duplicate polling loops, extra memory overhead, and unnecessary network calls to PageSense.
  2. Use stable, consistent user identifiers MurmurHash bucketing is deterministic — the same user ID always maps to the same variation for a given experiment. That only works if the ID you pass stays the same across requests.
  3. Good choices: user account ID, customer ID, hashed email, device ID. Avoid: session IDs, randomly generated IDs, request IDs.
  4. Enable USS when consistency across sessions matters If a user's variation assignment should survive server restarts, configuration changes, or new variation rollouts — use the User Storage Service. Redis or a database work well in production; file storage works for smaller setups.
  5. Keep polling intervals sensible The 30–120 second range covers most production use cases well. Going shorter strains your infrastructure; going longer means your SDK is slow to pick up experiment changes.
  6. Use webhooks over polling where you can Polling works, but webhooks are faster and cheaper. A webhook fires the moment an experiment is relaunched in PageSense — your SDK refreshes in real time, no wait.

Debugging and Troubleshooting  

Start here when something isn't working: flip the log level to DEBUG.
  1. const sdkOptions = new PageSenseSDKOptions()
  2.   .addLogLevel("DEBUG");
This surfaces detailed logs for experiment evaluation, variation bucketing, API calls, and polling cycles — enough to trace most issues.

Checklist:
  • Client is null after init — check your accountId, sdkKey, and projectName. One wrong value here causes init to fail silently.
  • Experiment always returns null — verify the experiment is active in PageSense and that your userAttributes match the targeting conditions.
  • Users getting inconsistent variations — check whether USS is enabled. Without it, variation changes in the experiment configuration can shift users.
  • Polling not picking up changes — confirm startPolling() was called and the polling interval isn't too long.
  • Goals not recording — goals must be configured inside the experiment in PageSense before trackGoal can record anything.




We’ve designed this documentation to guide you every step of the way. If you need further assistance or have any questions, don’t hesitate to contact us at support@zohopagesense.com - we’re always here to help!