<CroctProvider>

Initialize the SDK.

This component initializes the SDK and makes it available in the component tree, which you can then access with the useCroct hook.

Example

Here is a basic example of how to use this component:

App.jsx
1234567891011
import {CroctProvider} from '@croct/plug-next/CroctProvider';


export default function App() {
  return (
    <CroctProvider appId="YOUR_APPLICATION_ID">
      <div>
        <h1>My first personalized app 🚀</h1>
      </div>
    </CroctProvider>
  );
}

Attributes

The following list describes the supported attributes:

appId(optional)
string

The ID of the application in your workspace.

You can find this ID on the Integration page of your application.

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).

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:

ScopeDescription
globalAll tabs share the same user.
isolatedEach tab has its own independent user.
contextualNew 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 by setting the timeout property in the the options of components, hooks, and standalone functions.

The default timeout is 2 seconds.

Default:2000
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 property in the the <Slot> component, useContent hook, and fetchContent function.

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.

debug
(message: string)=>void

A function to log debug messages.

info
(message: string)=>void

A function to log informational messages.

warn
(message: string)=>void

A function to log warning messages.

error
(message: string)=>void

A function to log error messages.

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:

PathDescription
/client/web/cidEndpoint for assigning a CID.
/client/web/evaluateEndpoint for query evaluation.
/client/web/trackEndpoint for tracking events.
/contentEndpoint for content retrieval.

See Integration tests for more information on how to mock the API calls.

The 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.