SDK Customization
PageSense SDK provides a flexible configuration model that allows developers to adapt its behavior to suit the needs of their application. While the SDK can be used with minimal setup using the default configuration, applications with stricter performance, logging, or storage requirements may benefit from customizing the components within the SDK.
Default Initialization
When the PageSense SDK is initialized without any custom options, it automatically creates a PageSenseClient instance using a predefined set of configuration values designed for general use:
Polling interval: PageSense SDK periodically contacts the PageSense server to pull the latest project settings. By default, this interval is set to 10 seconds, ensuring that your application stays updated with the latest project configuration changes without requiring manual refresh.
Log level: SDK captures log messages that are at the INFO level and above. This includes key operational events, warnings, errors and high severity messages.
Logger: A built-in console logger is included by default, allowing the logs to appear directly in your application's output console.
These default parameters are intended to support quick onboarding and provide reliable behavior in typical development, testing and production setups.
Customizable Options
Option | Purpose |
Polling Interval | Controls how frequently the SDK syncs with PageSense server. Adjusting this value allows the customers to optimize network usage or increase responsiveness to project setting updates. |
Custom Logging | Customers can supply a custom logger to capture the SDK logs in a preferred format or route them into centralized logging systems |
Custom User Storage | Allows the application to define how experiment variation assignments for the users are persisted. This is valuable when consistent user experience across sessions or devices is required. |
Log Level | Enables fine-grained control over which log messages are emitted. Applications can choose from standard levels such as TRACE, DEBUG, INFO, WARN, ERROR, and SEVERE to match their debugging or monitoring standards. |
Following code explains how to create a customized PageSenseClient instance using the PageSenseClientBuilder.
- use Zoho\PageSense\PageSenseClientBuilder;
- // Create the builder using the project settings.
- $builder = PageSenseClientBuilder::getBuilder($projectSettings);
- // Apply optional custom configurations and build the PageSenseClient.
- $pageSenseClient = $builder
- ->addPollingInterval(60000) // Set polling interval to 60 seconds
- ->addLogLevel('DEBUG') // Capture logs from DEBUG level and above
- ->addCustomLogger($customLogger) // Use a custom PSR-3 compatible logger
- ->addCustomStorage($customStorage) // Set custom user storage service
- ->buildClient(); // Build and return the configured client instance
Polling interval
PageSense SDK contains the method addPollingInterval that allows you to control how frequently the PageSense SDK checks the PageSense server for updates to the project settings. This polling mechanism ensures that the SDK stays synchronized with the latest changes made in the PageSense for the given project —such as experiment updates, traffic reallocation, variation and goal changes etc.
By default, the PageSense SDK polls the PageSense server every 10 seconds. For applications that require a different refresh rate, the interval can be customized by supplying a value in milliseconds to the addPollingInterval method.
Usage Example
- // Create the builder using the project settings.
- $builder = PageSenseClientBuilder::getBuilder($projectSettings);\
- // Set the polling interval to one second and build the PageSenseClient.
- $pageSenseClient = $builder->addPollingInterval(60000)->buildClient();
In this example, the polling interval is set to 60,000 milliseconds (60 seconds), meaning the SDK will request the latest project settings from PageSense sever once every minute.Method Parameters
Parameter | Type | Description |
pollingInterval | Integer | Defines how often the SDK polls the PageSense server, expressed in milliseconds. |
Considerations When Choosing a Polling Interval
Selecting an appropriate polling interval depends on your application’s performance requirements, usage patterns, and sensitivity to project configuration delays.
Keep the following points in mind:
1. Very Short Intervals (less than 10 seconds)
Increase the number of requests made to the PageSense server.
Can lead to higher network overhead.
May cause unnecessary load if your project configuration changes infrequently.
2. Moderate Intervals (10–60 seconds)
Suitable for most real-time or near–real-time use cases.
Provide a balance between responsiveness and network efficiency.
3. Long Intervals (greater than 5 minutes)
Reduce network traffic but may delay updates from PageSense
Users might receive outdated experiment or targeting configurations until the next poll cycle which may affect the experiment results.
Best Practices
Choose a shorter interval when rapid propagation of project configuration changes is important.
Use longer intervals for high-traffic applications where minimizing network usage is a priority.
Log level
PageSenseSDK contains the method addLogLevel that allows you to define how much logging information the PageSense SDK should produce while your application is running. This is useful when you need greater visibility of the SDK internal processes or wish to limit log output in production environments.
By specifying a log level, you set the lowest severity of messages the SDK will output. All messages at that level and any levels with higher severity above it —will be recorded. This gives you fine-grained control over the verbosity of the SDK’s built-in logging system.
The log level must be passed as a String, and the SDK accepts the following values :TRACE, DEBUG, INFO, WARNING, ERROR, SEVERE
These levels correspond to common logging standards used across application frameworks.
Usage Example
- use Zoho\PageSense\PageSenseClientBuilder;
- // Create the builder using the project settings.
- $builder = PageSenseClientBuilder::getBuilder($projectSettings);
- // Apply the custom log level and build the PageSenseClient.
- $pageSenseClient = $builder->addLogLevel('DEBUG')
->buildClient();
In the above example, the log level is set to "WARNING". PageSense SDK will therefore output log messages classified as: WARNING, ERROR, and SEVERE.Method Parameter
Param | Type | Description |
logLevel | String | Specifies the minimum log severity to be recorded |
Custom logger
PageSense SDK includes a built-in logger to log the diagnostic and operational messages to the console . However, many applications rely on their own centralized or framework-specific logging systems. To support these environments, PageSense SDK allows you to supply a custom logger implementation that replaces the default logging behavior.
By registering a custom logger, all the log output generated by the SDK—across all severity levels—is routed through your implementation. This allows you to apply your own logging policies, formatting rules, routing logic, and storage strategies.
A custom logger is particularly helpful when:
Your application already uses a structured or centralized logging framework.
You need to redirect logs to external monitoring tools.
You want to standardize log output across all the modules of your system.
How to Use a Custom Logger
To integrate a custom logger, you must provide an instance of a class that implements the PageSenseLogger interface. This interface defines the methods the SDK uses to display and store the log messages. Your implementation can internally use any logging library (e.g., Monolog, Log4j, Winston) or write logs to a location of your choice. Once your logger class is ready, you register it with the SDK using the addCustomLogger method available on the PageSenseClientBuilder.
Note: When both addLogLevel() and addCustomLogger() are used in the PageSense SDK initialization, the log-level configured in the custom logger’s own takes precedence over the log level supplied to the SDK. PageSense SDK will forward all log messages to the custom logger without applying its internal log-level filters.Usage Example
- use Zoho\PageSense\PageSenseClientBuilder;
- // Create a custom logger
- $customLogger = new FileSystemLogger();
- // Create the builder using the project settings.
- $builder = PageSenseClientBuilder::getBuilder($projectSettings);
- // Apply the custom log level and build the PageSenseClient.
- $pageSenseClient = $builder->addCustomStorage($customLogger)->buildClient();
In the above example, customLogger is an application-defined object that implements the PageSenseLogger interface and contains your preferred logging logic.
Method Parameter
Parameter | Type | Description |
customLogger | Instance of a class implementing PageSenseLogger
| A user-defined logger that determines how and where SDK log messages are recorded. |
User Storage Service (USS)
User Storage Service (USS) allows the PageSense SDK to persist variation assignments for the users across multiple A/B test experiments within a project. By providing a custom storage mechanism, you can ensure that users consistently receive the same variation over time, even when project and experiment configurations change.
This capability is especially valuable for preserving consistency in the variation assignment and delivering a stable user experience when the project settings change. Common scenarios include:
Introducing new variations
Modifying traffic allocation for an experiment
Relocating traffic distribution between variations
Migrating project settings across environments
How It Works
To enable USS, you provide your own implementation of the UserStorageService interface exposed by PageSense SDK. This interface defines how the PageSense SDK should:
Store a user’s assigned variation
Retrieve the stored variation during subsequent API requests
Your implementation may use any storage mechanism appropriate for your application such as :
Local files
Relational or NoSQL databases
In-memory caches such as Redis
Distributed session stores
Custom application-level persistence systems
Once implemented, the custom storage service is supplied to the PageSenseSDK through the addUserStorageService method on the PageSenseClientBuilder.
- use Zoho\PageSense\PageSenseClientBuilder;
- // Path to storage the custom storage file
- $storageDirectory = __DIR__ . '/UserStorage';
- // Create a custom user storage
- $customStorage = new FileUserStorageService($storageDirectory);
- // Create the builder using the project settings.
- $builder = PageSenseClientBuilder::getBuilder($projectSettings);
- // Apply the custom log level and build the PageSenseClient.
- $pageSenseClient = $builder->addCustomStorage($customStorage)->buildClient() ;
Method Parameter
Param | Type | Description |
userStorageService | Instance of a class implementing UserStorageService | A custom implementation to manage persistent variation assignments for users for FullStack A/B Test Experiment |
Best Practices
1. Use Webhooks for Real-Time Updates
For production environments, avoid setting very short polling intervals. High-frequency polling can generate unnecessary load on your infrastructure and the PageSense servers.Webhooks provide a more efficient mechanism for near real-time configuration updates and should be preferred where feasible.
2. Use User Storage Service for Authenticated Users
Enable USS only when users have stable identifiers such as user IDs. This ensures consistent variation assignment across sessions.For anonymous or ephemeral traffic, USS generally offers limited benefit and may introduce avoidable overhead.
3. Protect Your SDK Key
The sdkKey must remain strictly on the server. Do not expose it in:
Browser-side JavaScript
Public repositories
Mobile applications
Client-facing API responses
This prevents unauthorized access to project configurations.
4. Adopt Standard Logging and Caching Interfaces
Integrate the SDK with established PHP standards:
PSR-3 for logging
PSR-16 for caching (optional, if used with USS or other persistence layers)
Adhering to these standards ensures predictable behavior and easier integration with common PHP frameworks.
5. Logger Precedence Rules
When both addLogLevel() and addCustomLogger() are supplied, the custom logger’s internal filtering logic takes precedence.The SDK forwards all log messages to your logger without applying additional filtering.
6. Ensure Stable Identifiers for Variation Assignment
Use consistent, non-volatile identifiers (e.g., persistent user IDs) for variation evaluation. Avoid identifiers that frequently change, such as IP addresses or session IDs.
7. Secure and Validate Webhook Endpoints
If webhooks are used:
Validate inbound requests
Restrict access to your webhook endpoint
Ensure the endpoint is reachable and resilient
This ensures reliable delivery of configuration updates.
8. Use Lightweight Implementations for USS and Custom Logger
Implementations of UserStorageService and PageSenseLogger should be efficient and non-blocking to avoid introducing latency into request handling.
Warnings
1. Avoid Excessive Polling
Polling intervals that are too short (<10 seconds) can lead to:
Increased server load
Excessive network traffic
Unnecessary stress on PageSense endpoints
Use with caution in production.
2. Long Polling Intervals Delay Configuration Updates
Polling intervals longer than several minutes may result in:
Delayed propagation of experiment updates
Users receiving outdated variation logic until the next polling cycle
Adjust intervals thoughtfully based on your application’s needs.
3. Persistent Storage Must Handle Failures Gracefully
When using USS, ensure your storage mechanism can:
Handle read/write failures
Recover from partial writes
Manage file system or database errors
This prevents inconsistent variation assignments.
Debugging & Troubleshooting
1. Enable DEBUG Logs in Staging
Set the log level to DEBUG in non-production environments to inspect:
Variation assignment
Bucket distributions
Webhook and polling activity
SDK initialization details
Avoid enabling DEBUG logs in production except when diagnosing issues.
2. Log Variation Assignments During Testing
Recording variation assignments during rollout helps verify:
Hashing consistency
Correct traffic allocation
Environment-to-environment alignment (Dev → QA → Prod)
3. Test USS Behavior Thoroughly
Simulate scenarios such as:
Experiment updates
New variations
Traffic reallocation
Experiment relaunches
Ensure stored variations continue to resolve correctly or are refreshed as intended.
4. Verify Webhook Delivery
Check:
Server reachability
Firewall rules
Web server logs
PageSense retry attempts (every 30 seconds, up to 15 minutes)
Webhook failures may prevent timely configuration updates.
5. Confirm Polling Operation
Ensure that:
Polling thread is active
Polling interval is configured correctly
Network errors are handled gracefully
Polling should serve as a fallback when webhooks are not available.
6. Validate Builder Configuration Order
Ensure that all configuration options (polling interval, log level, custom logger, USS) are applied to the builder before calling buildClient().
7. Review PHP Environment Constraints
Confirm that the hosting environment supports:
File system permissions (if using file-based USS)
Sufficient memory limits
Required PHP extensions (e.g., cURL, JSON, OpenSSL)
Access your files securely from anywhere
Zoho CRM Training Programs
Learn how to use the best tools for sales force automation and better customer engagement from Zoho's implementation specialists.
Zoho DataPrep Personalized Demo
If you'd like a personalized walk-through of our data preparation tool, please request a demo and we'll be happy to show you how to get the best out of Zoho DataPrep.
- Zoho Workerly Home
- Forums
- Connect With Us:
- Zoho Recruit Home
- Forums
- Connect With Us:
Create. Review. Publish.
You are currently viewing the help pages of Qntrl’s earlier version. Click here to view our latest version—Qntrl 3.0's help articles.
Zoho Sheet Resources
Zoho Forms Resources
Zoho Sign Resources
Sign, Paperless!
Zoho TeamInbox Resources
Design. Discuss. Deliver.
Related Articles
Initialization of PHP SDK
The PageSenseClient class is the main interface provided by the PageSense PHP SDK to run Full Stack A/B Testing experiments for the users. Before serving variations or tracking goals, the client must be initialized with your project’s configuration, ...Installation of PHP SDK
The PageSense PHP SDK empowers developers to integrate, run, and analyze Full Stack A/B tests directly from their PHP applications. It offers a simple, secure, and reliable way to connect your PHP applications to the PageSense’s experimentation ...SDK Customization
Overview: SDK customization involves tailoring a Software Development Kit (SDK) to meet the unique needs of your application or development environment. An SDK typically includes tools, libraries, documentation, and code samples to assist developers ...SDK Customization
Overview SDK customization involves tailoring a Software Development Kit (SDK) to meet the unique needs of your application or development environment. An SDK typically includes tools, libraries, documentation, and code samples to assist developers ...Installation of C#.NET SDK
Overview: The PageSense C# SDK empowers developers to integrate, conduct A/B testing, and personalize user experiences within C#.NET applications. PageSense C# SDK offers a simple and reliable way to integrate FullStack A/B Testing into your ...