evaluate

This function evaluates a CQL query on the server side.

Alternatively, you can use the cql tag function for a more concise and readable way with interpolation support.

Signature

This function has the following signature:

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

Example

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

import {evaluate} from '@croct/plug-next/server';

export async function DocsLink() {
  const isDeveloper = await evaluate("user's persona is 'developer'");

  return (
    isDeveloper
      ? <a href="/docs">View docs</a>
      : <a href="/share">Share with your developer</a>
  );
}

For more examples, see the Query evaluation.

Parameters

The following list describes the supported parameters:

query

string

The CQL query to evaluate, with a maximum length of 500 characters.

options

object

The evaluation options.

route(optional)

object

The context of the current route.

Conditional requirement

This option is only needed for Page router or API routes, as the current request scope is only accessible through the App router and Server actions.

The property names are aligned with those in Next.js for easy forwarding, as shown in the Page router example.

req

NextApiRequest|NextRequest|GetServerSidePropsRequest

The request object.

res

NextApiResponse|NextResponse|GetServerSidePropsResponse

The response object.

clientId(optional)

string

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

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.

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

clientAgent(optional)

string

The user agent of the client (browser).

Auto-configuration

The SDK automatically forwards the user agent from the incoming request, so you do not need to specify this option unless you want to override it.

If not specified or unknown, device technology information will be limited or unavailable.

clientIp(optional)

string

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

Auto-configuration

The SDK automatically forwards the IP address from the incoming request, so you do not need to specify this option unless you want to override it.

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 will be limited or unavailable.

userToken(optional)

string

A base64-encoded JSON Web Token (JWT) that identifies 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.

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

timeout(optional)

number

The maximum fetch time in milliseconds.

Environment variable

You can also set this option by defining the environment variable NEXT_PUBLIC_CROCT_DEFAULT_FETCH_TIMEOUT.

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

baseEndpointUrl(optional)

string

The base URL to use for the API calls.

Environment variable

You can also set this option by defining the environment variable NEXT_PUBLIC_CROCT_BASE_ENDPOINT_URL.

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

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

extra(optional)

object

Additional options to pass to the fetch function.

logger(optional)

object

A custom logger to handle log messages.

By default, warnings and errors are logged to the console, and everything else is 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(optional)

object

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

timeZone(optional)

string

The time zone of the user, represented by an IANA time zone ID, 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(optional)

object

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

Auto-configuration

The SDK automatically forwards this information from the incoming request, so you do not need to specify this option unless you want to override it.

For more information on how to use this information, see Marketing variables;

name(optional)

string

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

This information usually comes from the utm_campaign URL parameter.

source(optional)

string

The source of the campaign, such as google.

This information usually comes from the utm_source URL parameter.

medium(optional)

string

The medium of the campaign, such as cpc.

This information usually comes from the utm_medium URL parameter.

term(optional)

string

The term of the campaign, such as running shoes.

This information usually comes from the utm_term URL parameter.

content(optional)

string

The content of the campaign, such as banner ad.

This information usually comes from the utm_content URL parameter.

page(optional)

object

Information about the page the user is currently viewing.

Auto-configuration

The SDK automatically forwards this information from the incoming request, so you do not need to specify this option unless you want to override it.

For more information on how to use this information, see Navigation variables.

url

string

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

This information usually comes from the window.location.href property.

title(optional)

string

The title of the page, such as Products.

This information usually comes from the document.title property.

referrer(optional)

string

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

This information usually comes from the Referer HTTP header or the document.referrer; property.

attributes(optional)

object

The map of attributes to inject in the evaluation context.

The attributes can be referenced in audience conditions using the context variable. For example, suppose you pass the following attributes:

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

You can then reference them in queries like:

context's cities include location's city

For more information, see 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