# createCroct

Learn how to initialize the SDK using a Vue plugin.

This function creates a Vue plugin that initializes the SDK and makes it available throughout the application, which you can then access with the [`useCroct`](/reference/sdk/vue/api/composables/use-croct) composable.

## Signature

This function has the following signature:

```ts
function createCroct(options: CroctPluginOptions): Plugin;
```

The return is a Vue [Plugin](https://vuejs.org/guide/reusability/plugins.html) instance.

## Example

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

**main.ts**

```ts
import {createApp} from 'vue';
import {createCroct} from '@croct/plug-vue';
import App from './App.vue';

const app = createApp(App);

app.use(createCroct({
appId: 'YOUR_APPLICATION_ID',
}));

app.mount('#app');
```

## Parameters

The following list describes the supported options:

- `appId`: `string` (optional)

  The ID of the application in your workspace.

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

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

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

  If not specified, the SDK assigns an ID using the [CID Assigner endpoint](#cidassignerendpointurl-prop). This option is typically used when the Client ID is generated on the server side and passed to the client.

- `token`: `string|null` (optional)

  A base64-encoded [JSON Web Token (JWT)](https://jwt.io) to identify the user.

  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.

  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: 5000)

  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, [composables](../composables), and [standalone functions](../functions).

  The default timeout is 5 seconds.

- `defaultPreferredLocale`: `string` (optional)

  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>`](../components/slot-content#preferredlocale-prop) component, [`useContent`](../composables/use-content#options-preferredlocale-prop) composable, 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.

- `cidAssignerEndpointUrl`: `string` (optional)

  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`](#clientid-prop) 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`: `boolean` (optional) (default: false)

  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.

- `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`

      The name of the cookie, which must not be empty and must contain only ASCII characters.

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

      The domain of the cookie, non-empty.

    - `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`

      The name of the cookie, which must not be empty and must contain only ASCII characters.

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

      The domain of the cookie, non-empty.

    - `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`

      The name of the cookie, which must not be empty and must contain only ASCII characters.

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

      The domain of the cookie, non-empty.

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