plug
Initialize the SDK.
This method initializes the SDK with the specified configuration.
You should initialize the SDK only once in the application lifecycle, usually at application startup. Subsequent calls to this method without calling the unplug method will result in an error.
To reconfigure the plug, you can call the unplug method to reset the SDK to its initial state, and then call the plug method with the new configuration.
Signature
This method has the following signature:
croct.plug(configuration?: Configuration): void;
Example
Here is a basic example of how to use this method:
import croct from '@croct/plug';croct.plug({appId: '00000000-0000-0000-0000-000000000000'});
Parameters
The following list describes the supported parameters:
- configuration(optional)object
This parameter is required unless you specified the Application ID in the script tag that loads the SDK.
- appId(optional)string
The ID of the application in your workspace.
You can find this ID on the Integration page of your application.
The SDK can automatically detect the Application ID specified in the script tag:
<script src="https://cdn.croct.io/js/v1/lib/plug.js?appId=YOUR_APPLICATION_ID"></script>If the Application ID is not specified or detected, the initialization will fail.
- debug(optional)boolean
Whether to enable debug mode.
When enabled, the SDK logs detailed messages to the console that can help you diagnose issues.
Default:false- test(optional)boolean
Whether to enable test mode.
When enabled, the SDK uses a mock event transport layer to simulate successful transmission, which is useful for testing.
Default:false- track(optional)boolean
Whether to enable the automatic event tracking on initialization.
Default:true- clientId(optional)string
The unique identifier for the client (browser).
If not specified, the SDK assigns an ID using the CID Assigner endpoint. This option is typically used when the Client ID is generated on the server side and passed to the client.
- token(optional)string|null
A base64-encoded JSON Web Token (JWT) to identify the user.
This option must not be specified together with the userId. Setting this parameter to null clears any previously specified token.
If the Require authenticated token option is enabled in the Application settings, a signed JWT is required. In this case, the token must be signed using an API key with authentication permissions.
- userId(optional)string
The ID of the user logged into the application.
This option must not be specified together with the token option.
Only use this option if the Require authenticated token option is disabled in the Application settings. Otherwise, all requests will fail with an authentication error because the SDK internally issues an unsigned token.
- tokenScope(optional)string
Defines how the SDK should synchronize the token across multiple tabs.
The following values are supported:
Scope Description global All tabs share the same user. isolated Each tab has its own independent user. contextual New tabs inherit the user from the previous tab. Here is a more detailed explanation of each scope:
- Global scope: An application is said to have a global user scope if it supports only one user at a time, in contrast to applications that allow you to switch between multiple accounts in the same session. In practice, as all tabs share the same scope, it means that if you identify or anonymize a user on one tab, it will reflect on all other tabs.
- Isolated scope: The isolated scope prevents token synchronization between tabs. You should use an isolated scope if your application does not keep users logged in across multiple tabs.
- Contextual scope: The contextual scope is similar to the isolated scope, except that new tabs retain the user identification from the last tab viewed. You should consider using this scope if your application allows users to access multiple accounts simultaneously in different tabs. This behavior is similar to how Gmail works: when you are signed in to an account and open a link, the user remains the same as the original page.
Default:"global"- defaultFetchTimeout(optional)number
The default timeout in milliseconds for network requests.
This option is useful when you want to set a default timeout for all requests.
You can override this value on a per-request basis when calling the fetch and ../evaluate methods.
The default timeout is 5 seconds.
Default:5000- defaulPreferredLocale(optional)string
The default preferred locale for content retrieval.
The code consists of a two-part string that specifies the language and, optionally, the country. For example, en represents English, en-us stands for English (United States), and pt-br for Portuguese (Brazil). It is case-insensitive and supports both hyphens and underscores as separators to accommodate the different conventions used by browsers, libraries, and other systems.
This option is useful when you want to set a global locale for all content requests, which is the common practice for most applications.
You can override this value on a per-request basis by setting the preferredLocale option when calling the fetch method.
- eventMetadata(optional)object
Additional information that may be useful to include as part of the event metadata.
A common use case is to record the version of the application that generated the event for later analysis when exporting the events.
The following restrictions apply to the metadata:
- Up to 5 entries
- Keys must be strings up to 20 characters long, starting with a letter or underscore and optionally followed by letters, digits, or underscores
- Values must be strings up to 300 characters long
- logger(optional)object
A custom logger to handle log messages.
By default, all logs are suppressed.
- urlSanitizer(optional)(url: string)=>URL
A function to process URLs before sending them to the server.
The SDK uses this function to sanitize URLs in event properties, allowing you to remove sensitive information such as tokens or personal data before including it in the event payload.
- baseEndpointUrl(optional)string
The base URL to use for the API calls.
By default, the SDK uses the production endpoint. This option is helpful for testing purposes and allows you to point the SDK to another environment, such as a mock server.
These are the endpoints that use the base URL:
Path Description /client/web/cid Endpoint for assigning a CID. /client/web/evaluate Endpoint for query evaluation. /client/web/track Endpoint for tracking events. /content Endpoint for content retrieval. See Integration tests for more information on how to mock the API calls.
- cidAssignerEndpointUrl(optional)string
The URL to use for assigning the Client ID (CID).
The SDK calls this endpoint to obtain a valid string whenever it needs to assign a new CID.
Overriding this endpoint is useful for server-side client ID assignment, such as storing the ID in a server-side cookie that is shared across subdomains. In these cases, be sure to set the name of the clientId cookie to the same value as the one used by the server.
By default, the SDK uses a built-in endpoint that assigns a random Client ID.
- disableCidMirroring(optional)boolean
Whether to disable client ID mirroring.
By default, the SDK sends the current Client ID to the CID Assigner endpoint via the cid query parameter at each initialization. This allows for a smooth migration to a custom assigner.
For example, to transition to a first-party cookie-based CID assigner, the endpoint can receive the CID, store it in a cookie, and return the same value.
Default:falseThe configuration for the cookie storage.
By default, the SDK persists information in either the browser's local storage or session storage depending on the tokenScope option.
This option allows you to specify which information should be stored in first-party cookies instead.
- appId(optional)