# Evaluate

Learn how to evaluate a CQL query using a standalone function.

This function evaluates a [CQL query](/reference/cql) in real-time and returns the result.

## Signature

This function has the following signature:

```ts
function evaluate<T extends JsonValue>(query: string, options: EvaluationOptions): Promise<T>;
```

The result is a `Promise` that resolves to the result of the evaluation.

## Example

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

```ts
import {evaluate} from '@croct/plug/api';

const result = await evaluate('user is returning', {
appId: '00000000-0000-0000-0000-000000000000',
});
```

## Parameters

The following list describes the supported parameters:

- `query`: `string`

  The [CQL query](/reference/cql) to evaluate, with a maximum length of 500 characters.

- `options`: `object`

  The evaluation options.

  - `appId`: `string` (optional)

    The Application ID to use for client-side requests.

    This option is required for client-side applications. For server-side applications, use the [`apiKey`](#options-apikey-prop) option instead. Specifying both will result in an error.

  - `apiKey`: `string` (optional)

    The [API key](/explanation/application/api-keys) to use for server-side requests.

    This option is required for server-side applications. For client-side applications, use the [`appId`](#options-appid-prop) option instead. Specifying both will result in an error.

    > **Keep your API key safe**
    >
    > Never use your API key in client-side code, only in server-side environments.

  - `clientId`: `string` (optional)

    The ID of the client (browser), in the form of a UUID.

    This must be a persistent identifier that uniquely identifies the user across sessions.

    If omitted, the user will be treated as anonymous, resulting in no session context and reduced effectiveness of dynamic content features.

  - `clientAgent`: `string` (optional)

    The user agent of the client (browser).

    If not specified or unknown, [device technology information](/reference/cql/context#technology) will be limited or unavailable.

  - `clientIp`: `string` (optional)

    The IP address of the client (end-user).

    Passing `127.0.0.1` makes the API uses IP address of the incoming request, which is useful for local development.

    If not specified or unknown, [geographic location information](/reference/cql/context#location) will be limited or unavailable.

  - `userToken`: `string` (optional)

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

    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, or the request will fail with an authorization error.

  - `timeout`: `number` (optional)

    The maximum fetch time in milliseconds.

    Once reached, the SDK will abort the request and reject the promise with a timeout error.

  - `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/evaluate`   | Endpoint for client-side evaluation. |
    | `/external/web/evaluate` | Endpoint for server-side evaluation. |

    See [Integration tests](../../testing/integration-testing) for more information on how to mock the API calls.

  - `extra`: `object` (optional)

    Additional options to pass to the [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) function.

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

  - `context`: `object` (optional)

    Information about the user context, such as the time zone, campaign, and page.

    - `timeZone`: `string` (optional)

      The time zone of the user, represented by an [IANA time zone ID](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#list), like `America/New_York`.

      This information is used for time-based features like localization and scheduling, and usually comes from the browser's preferences or the user's profile.

    - `campaign`: `object` (optional)

      Information about the marketing campaign that brought the user to the page.

      For more information on how to use this information, see [Marketing variables](/reference/cql/context#marketing);

      - `name`: `string` (optional)

        The name of the campaign, such as `summer-sale`.

        This information usually comes from the `utm_campaign` URL parameter.

      - `source`: `string` (optional)

        The source of the campaign, such as `google`.

        This information usually comes from the `utm_source` URL parameter.

      - `medium`: `string` (optional)

        The medium of the campaign, such as `cpc`.

        This information usually comes from the `utm_medium` URL parameter.

      - `term`: `string` (optional)

        The term of the campaign, such as `running shoes`.

        This information usually comes from the `utm_term` URL parameter.

      - `content`: `string` (optional)

        The content of the campaign, such as `banner ad`.

        This information usually comes from the `utm_content` URL parameter.

    - `page`: `object` (optional)

      Information about the page the user is currently viewing.

      For more information on how to use this information, see [Navigation variables](/reference/cql/context#navigation).

      - `url`: `string`

        The URL of the page, such as `https://www.example.com/products`.

        This information usually comes from the [`window.location.href`](https://developer.mozilla.org/en-US/docs/Web/API/Location/href) property.

      - `title`: `string` (optional)

        The title of the page, such as `Products`.

        This information usually comes from the [`document.title`](https://developer.mozilla.org/en-US/docs/Web/API/Document/title) property.

      - `referrer`: `string` (optional)

        The URL of the page that linked to the current page, such as `https://www.google.com`.

        This information usually comes from the [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) HTTP header or the [`document.referrer`](https://developer.mozilla.org/en-US/docs/Web/API/Document/referrer); property.

    - `attributes`: `object` (optional)

      The map of attributes to inject in the evaluation context.

      The attributes can be referenced in audience conditions using the [`context`](/reference/cql/context#evaluation) variable. For example, suppose you pass the following attributes:

      ```json
      {cities: ["New York", "San Francisco"]}
      ```

      You can then reference them in queries like:

      ```cql
      context's cities include location's cityName
      ```

      For more information, see [Context variables](../../content-rendering#context-variables).

      The following restrictions apply to the attributes:

      - Up to 30 entries and 5 levels deep
      - Keys can be either numbers or non-empty strings with a maximum length of 50 characters
      - Values can be null, numbers, booleans, strings (up to 50 characters), or nested maps
      - Nested maps follow the same constraints for keys and values