useEvaluation

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

Signature

This composable has the following signature:

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

Where UseEvaluationResult<T> is:

type UseEvaluationResult<T> = {    data: ShallowRef<T | undefined>;    isLoading: Ref<boolean>;    error: Ref<Error | null>;};

Example

Here is an example of how to use this composable:

<script setup>import {useEvaluation} from '@croct/plug-vue';
const {data: isDeveloper} = useEvaluation("user's persona is 'developer'");</script>
<template>    <a v-if="isDeveloper" href="/docs">View docs</a>    <a v-else href="/share">Share with your developer</a></template>

Parameters

query

string

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

options(optional)

object

The evaluation options. Accepts a MaybeRefOrGetter for reactivity.

initial(optional)

JSON

An initial value to use while loading the actual result.

This value is required for server-side rendering. For client-side rendering, not specifying this value will cause the data ref to be undefined and isLoading to be true until the evaluation completes.

fallback(optional)

JSON

A fallback value to use in case of an error.

If not specified, the error ref will contain the error and data will remain undefined.

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

staleWhileLoading(optional)

boolean

Whether to use the previous result while re-evaluating the new value.

By default, the composable sets data to undefined and isLoading to true while evaluating.

If this option is enabled, the behavior changes as follows:

• On the first render, it either returns the initial value or sets isLoading to true while evaluating the query.
• If the cache key or any other property that affects the result changes, it returns the previous result while re-evaluating the query.
• When the new result is available, it updates data with the new value.

Default:false

timeout(optional)

number

The maximum fetch time in milliseconds.

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 cityName

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

Return

The return is a reactive object with the following properties:

data

ShallowRef<T|undefined>

A shallow ref containing the evaluation result, or undefined while loading.

isLoading

Ref<boolean>

A ref indicating whether the evaluation is currently in progress.

error

Ref<Error|null>

A ref containing the error if the evaluation failed, or null otherwise.