# \ Learn how to initialize the SDK. This component initializes the SDK and makes it available in the component tree, which you can then access with the [`useCroct`](../hooks/use-croct) hook. ## Example Here is a basic example of how to use this component: **JavaScript** ```jsx import {CroctProvider} from '@croct/plug-next/CroctProvider'; export default function App() { return (

My first personalized app 🚀

 ); } ``` **TypeScript** ```tsx import type {ReactElement} from 'react'; import {CroctProvider} from '@croct/plug-next/CroctProvider' export default function App(): ReactElement { return (

My first personalized app 🚀

 ); } ``` ## Attributes The following list describes the supported attributes: - `appId`: `string` (optional) The ID of the application in your workspace. > **Environment variable** > > You can also set this option by defining the environment variable [`NEXT_PUBLIC_CROCT_APP_ID`](../environment-variables#next_public_croct_app_id-prop). You can find this ID on the [Integration page](https://app.croct.com/redirect/organizations/-organization-/workspaces/-workspace-/applications/-application-/integration) of your application. - `debug`: `boolean` (optional) (default: false) Whether to enable [debug mode](../../troubleshooting/debugging). > **Environment variable** > > You can also enable this option by setting the environment variable [`NEXT_PUBLIC_CROCT_DEBUG`](../environment-variables#next_public_croct_debug-prop) to `true`. When enabled, the SDK logs detailed messages to the console that can help you diagnose issues. - `test`: `boolean` (optional) (default: false) Whether to enable [test mode](../../testing/unit-testing#enable-test-mode). > **Environment variable** > > You can also enable this option by setting the environment variable [`NEXT_PUBLIC_CROCT_TEST`](../environment-variables#next_public_croct_test-prop) to `true`. When enabled, the SDK uses a mock event transport layer to simulate successful transmission, which is useful for testing. - `track`: `boolean` (optional) (default: true) Whether to enable the automatic event tracking on initialization. - `clientId`: `string` (optional) The unique identifier for the client (browser). > **Auto-configuration** > > The SDK automatically generates and forwards the client ID from the incoming request, so you do not need to specify this option unless you want to override it. - `token`: `string|null` (optional) A base64-encoded [JSON Web Token (JWT)](https://jwt.io) to identify the user. > **Auto-configuration** > > The SDK automatically generates and sets the token, so you do not need to specify this option unless you want to override it. This option must not be specified together with the [`userId`](#userid-prop). Setting this parameter to `null` clears any previously specified token. If the **Require signed token** option is enabled in the [Application settings](https://app.croct.com/redirect/organizations/-organization-/workspaces/-workspace-/applications/-application-/settings), a signed JWT is required. In this case, the [token must be signed](/explanation/application/signed-tokens) using an [API key](/explanation/application/api-keys) with **Issue user tokens** permission. - `userId`: `string` (optional) The ID of the user logged into the application. > **Auto-configuration** > > The SDK automatically generates and sets the token, so you do not need to specify this option unless you want to override it. This option must not be specified together with the [`token`](#token-prop) option. Only use this option if the **Require signed token** option is disabled in the [Application settings](https://app.croct.com/redirect/organizations/-organization-/workspaces/-workspace-/applications/-application-/settings). Otherwise, all requests will fail with an authentication error because the SDK internally issues an [unsigned token](/explanation/application/signed-tokens#unsigned-tokens). - `tokenScope`: `string` (optional) (default: "global") 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. - `defaultFetchTimeout`: `number` (optional) (default: 2000) The default timeout in milliseconds for network requests. > **Environment variable** > > You can also set this option by defining the environment variable [`NEXT_PUBLIC_CROCT_DEFAULT_FETCH_TIMEOUT`](../environment-variables#next_public_croct_default_fetch_timeout-prop). 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](../hooks), and [standalone functions](../functions). The default timeout is 2 seconds. - `defaultPreferredLocale`: `string` (optional) The default preferred locale for content retrieval. > **Environment variable** > > You can also set this option by defining the environment variable [`NEXT_PUBLIC_CROCT_DEFAULT_PREFERRED_LOCALE`](../environment-variables#next_public_croct_default_preferred_locale-prop). 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 [``](../components/slot#preferredlocale-prop) component, [`useContent`](../hooks/use-content#options-preferredlocale-prop) hook, and [`fetchContent`](../functions/fetch-content#options-preferredlocale-prop) function. - `eventMetadata`: `object` (optional) 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`: `object` (optional) 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`: `(url: string) => URL` (optional) 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`: `string` (optional) 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](../../testing/integration-testing#create-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](../../testing/integration-testing) for more information on how to mock the API calls. - `cookie`: `object` (optional) 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`](#tokenscope-prop) option. This option allows you to specify which information should be stored in first-party cookies instead. - `clientId`: `object` (optional) This option configures the SDK to store the Client ID in a first-party cookie. - `name`: `string` (optional) (default: ct.client\_id) The name of the cookie, which must not be empty and must contain only ASCII characters. > **Environment variable** > > You can also set this option by defining the environment variable [`NEXT_PUBLIC_CROCT_CLIENT_ID_COOKIE_NAME`](../environment-variables#next_public_croct_client_id_cookie_name-prop). - `secure`: `boolean` (optional) (default: true) Specifies whether the cookie should be sent only over secure connections. - `maxAge`: `number` (optional) (default: 31536000) The maximum age of the cookie in seconds. For example, a value of `3600` sets the cookie to expire in one hour. > **Environment variable** > > You can also set this option by defining the environment variable [`NEXT_PUBLIC_CROCT_CLIENT_ID_COOKIE_DURATION`](../environment-variables#next_public_croct_client_id_cookie_duration-prop). - `domain`: `string` (optional) (default: ) The domain of the cookie, non-empty. > **Environment variable** > > You can also set this option by defining the environment variable [`NEXT_PUBLIC_CROCT_CLIENT_ID_COOKIE_DOMAIN`](../environment-variables#next_public_croct_client_id_cookie_domain-prop). - `path`: `string` (optional) The path of the cookie, non-empty. - `sameSite`: `string` (optional) (default: none) Define how the browser should handle the cookie in cross-site links. The following values are supported: | Value | Description | | -------- | ----------------------------------------------------------------------------- | | `strict` | The cookie is sent only to the same site. | | `lax` | The cookie is sent to the same site and to cross-site requests that are safe. | | `none` | The cookie is sent to the same site and to cross-site requests. | For more details, see the [SameSite cookie](https://web.dev/articles/samesite-cookies-explained) article. > **Cookie loss** > > Setting this parameter to `strict` or `lax` causes the cookie to be reset when users visit the site from a different domain. - `userToken`: `object` (optional) This option configures the SDK to store the user token in a first-party cookie. - `name`: `string` (optional) (default: ct.user\_token) The name of the cookie, which must not be empty and must contain only ASCII characters. > **Environment variable** > > You can also set this option by defining the environment variable [`NEXT_PUBLIC_CROCT_USER_TOKEN_COOKIE_NAME`](../environment-variables#next_public_croct_user_token_cookie_name-prop). - `secure`: `boolean` (optional) (default: true) Specifies whether the cookie should be sent only over secure connections. - `maxAge`: `number` (optional) (default: 604800) The maximum age of the cookie in seconds. For example, a value of `3600` sets the cookie to expire in one hour. > **Environment variable** > > You can also set this option by defining the environment variable [`NEXT_PUBLIC_CROCT_USER_TOKEN_COOKIE_DURATION`](../environment-variables#next_public_croct_user_token_cookie_duration-prop). - `domain`: `string` (optional) (default: ) The domain of the cookie, non-empty. > **Environment variable** > > You can also set this option by defining the environment variable [`NEXT_PUBLIC_CROCT_USER_TOKEN_COOKIE_DOMAIN`](../environment-variables#next_public_croct_user_token_cookie_domain-prop). - `path`: `string` (optional) The path of the cookie, non-empty. - `sameSite`: `string` (optional) (default: none) Define how the browser should handle the cookie in cross-site links. The following values are supported: | Value | Description | | -------- | ----------------------------------------------------------------------------- | | `strict` | The cookie is sent only to the same site. | | `lax` | The cookie is sent to the same site and to cross-site requests that are safe. | | `none` | The cookie is sent to the same site and to cross-site requests. | For more details, see the [SameSite cookie](https://web.dev/articles/samesite-cookies-explained) article. > **Cookie loss** > > Setting this parameter to `strict` or `lax` causes the cookie to be reset when users visit the site from a different domain. - `previewToken`: `object` (optional) This option configures the SDK to store the preview token in a first-party cookie. - `name`: `string` (optional) (default: ct.preview\_token) The name of the cookie, which must not be empty and must contain only ASCII characters. > **Environment variable** > > You can also set this option by defining the environment variable [`NEXT_PUBLIC_CROCT_PREVIEW_TOKEN_COOKIE_NAME`](../environment-variables#next_public_croct_preview_token_cookie_name-prop). - `secure`: `boolean` (optional) (default: true) Specifies whether the cookie should be sent only over secure connections. - `maxAge`: `number` (optional) The maximum age of the cookie in seconds. For example, a value of `3600` sets the cookie to expire in one hour. - `domain`: `string` (optional) (default: ) The domain of the cookie, non-empty. > **Environment variable** > > You can also set this option by defining the environment variable [`NEXT_PUBLIC_CROCT_PREVIEW_TOKEN_COOKIE_DOMAIN`](../environment-variables#next_public_croct_preview_token_cookie_domain-prop). - `path`: `string` (optional) The path of the cookie, non-empty. - `sameSite`: `string` (optional) (default: none) Define how the browser should handle the cookie in cross-site links. The following values are supported: | Value | Description | | -------- | ----------------------------------------------------------------------------- | | `strict` | The cookie is sent only to the same site. | | `lax` | The cookie is sent to the same site and to cross-site requests that are safe. | | `none` | The cookie is sent to the same site and to cross-site requests. | For more details, see the [SameSite cookie](https://web.dev/articles/samesite-cookies-explained) article. > **Cookie loss** > > Setting this parameter to `strict` or `lax` causes the cookie to be reset when users visit the site from a different domain.