How do I get started with the browserless SDK?

The browserless SDK lets you use the same JavaScript methods as the standard JS SDK. Therefore, there is no dedicated documentation for this SDK; it is a list of the core differences, and everything else stays the same (You can find further information on these core differences in our developer documentation: Javascript (browserless))

The browserless SDK is designed to operate outside of a browser environment (for example, in pure server environments). If you can access browser APIs, you should use the standard SDK and not the browserless one, even if you are technically still in a server environment.

Core differences from the standard JS SDK

The browserless SDK does not offer permanent storage of the data and information natively stored in cookies (as it is meant to be used for applications that do not render in a browser). It also does not provide any of the properties that rely on a browser API to be set.

This being said, the browserless SDK still stores data for the duration of the active session (so while the application is running) in a variable called localVariable. It stores the equivalent of what is stored in our cookies, including: privacy mode, visitor ID, and user ID.

All stored data cannot be directly accessed, but our SDK provides methods to manage this data.

Managing stored data in browserless mode

Privacy mode: use pa.privacy.getMode() and pa.privacy.setMode() Privacy | Piano Analytics Developers Documentation (atinternet-solutions.com)

Visitor identification (idclient): use pa.getVisitorId() and pa.setVisitorId() Visitor identification | Piano Analytics Developers Documentation (atinternet-solutions.com)

Users: use pa.getUser() and pa.setUser() Users | Piano Analytics Developers Documentation (atinternet-solutions.com)

Persistence across restarts (recommended approach)

The stored data does not persist when the application is stopped. If you wish to retain those pieces of information for a longer time, the application must persistently store them itself and restore them on the next run. For example: store the visitor ID externally (database, server-side session store, etc.), on the next launch force the same visitor ID using pa.setVisitorId(), and apply the same approach for privacy mode and user information as needed.

Important consent consideration

Because the browserless SDK cannot rely on cookies to remember privacy/consent state, you should ensure you have a system in place to store and reuse the visitor's privacy mode between runs. This helps avoid unnecessarily re-requesting consent due to lost session state.

Hybrid mode compatibility

The JavaScript browserless SDK can be used to integrate with Piano in Hybrid mode. The same limitations apply: there is no cookie storage, so any information typically persisted in cookies (including privacy mode) must be managed externally if you need continuity across application restarts.