useEvaluation

This hook evaluates a  CQL query in real-time and returns the result, serving as the imperative equivalent of the <Personalization> component.

Signature

This hook has the following signature:

function useEvaluation<T extends JsonValue>(query: string, options?: EvaluationOptions): T;

The return is the result of the evaluation.

Example

Here is an example of how to use this hook:

import {useEvaluation} from '@croct/plug-react';

export function ViewDocsLink() {
  const isDeveloper = useEvaluation("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 Query evaluation.

Parameters

query

string

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

options(optional)

object

The evaluation options.

initial(optional)

JSON

An initial value to render while loading the actual value.

This value is required for server-side rendering. For client-side rendering, not specifying this value will cause rendering to suspend, requiring a <Suspense> boundary to handle the loading state.

fallback(optional)

JSON

A fallback value to render in case of an error.

If not specified, the error is thrown on failure.

expiration(optional)

number

The cache expiration time in milliseconds, extended on every render.

If negative, the cache never expires. By default, the cache expires after 60 seconds.

The SDK caches the result of the evaluation to prevent network requests on concurrent renders and re-renders.

Default:60000

cacheKey(optional)

string

A unique key to identify the cache entry.

By default, the cache key is a hash of the query and attributes. To force re-evaluation even if the query and attributes are the same, provide a unique cache key.

timeout(optional)

number

The maximum fetch time in milliseconds.

Good to know

You can set a default timeout for your application during SDK initialization, eliminating the need to specify it every call.

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

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