> For the complete documentation index, see [llms.txt](https://docs.crobox.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.crobox.com/how-to-guides/settings/visitor-properties.md).

# Visitor Properties

Define what Crobox remembers about each visitor, and how it personalizes products and Sagent for them.

A **visitor property** is something Crobox knows about a visitor, such as their preferred fit, skin type, or whether they're a VIP customer. Experiences can then use it: you can target campaigns at it, a Recommender can match products to it, and Sagent can take it into account in its advice.

Visitor properties get their values from:

* **Product Finder answers** - Link a question to a visitor property, and the visitor's answer is stored. See [Link Question to Visitor Profile](https://docs.crobox.com/how-to-guides/product-finders/finder-editor/question-editor.md#link-question-to-visitor-profile).
* **Your website** - Send values in the `cp` field of the pageview, such as `cp: { vip: true }`. Your developer can find the code in [Set Custom Visitor Properties with the Pageview API](https://docs.crobox.com/technical-documentation/setting-custom-visitor-properties-with-pageview-api.md).

{% hint style="warning" %}
A value your website sends is only used once a visitor property with the **exact same key** and a matching **Value Type** exists here.
{% endhint %}

Open **Settings → Visitor Properties**. Properties are grouped by category, and each shows its **Key**, **Name**, **Value type**, and **Status**: **Active** when an experience uses it, **Inactive** when none does. A **Sagent Context** label shows the property gives Sagent extra guidance.

{% hint style="info" %}
Visitor Properties is available when it's included in your plan. Contact your Customer Success Manager to enable it.
{% endhint %}

### Create a visitor property

{% stepper %}
{% step %}

#### Open the form

Click **Add Property**. The **Shopper Property Settings** panel opens.
{% endstep %}

{% step %}

#### Describe the property

* **Category** - The categories to group it under. Optional.
* **Value Type** - The kind of value it holds: **String**, **List**, **Boolean**, **Number**, **Datetime**, or **Object (JSON)**. Use **List** when visitors choose from fixed values, such as *Narrow*, *Regular*, and *Wide*.
* **Property Name** - A readable name, such as *Preferred fit*.
* **Property Key** - The key experiences and your website use to refer to the property, such as `preferred_fit`. It's filled in from the name, and can't be changed after saving. For a property your website sends, use the same key as in the pageview.
* **A visitor can have multiple values** - Switch on when a visitor can hold several values at once, such as several skin concerns.
  {% endstep %}

{% step %}

#### Add Sagent context (optional)

In **Sagent Context (general)**, write guidance Sagent should follow whenever the visitor has any value for this property. For example, *This shopper has a stated fit preference; keep advice practical.*
{% endstep %}

{% step %}

#### Add the values of a List property

For a **List** property, click **Add Property Value** for each value, and give it a **Name** and a **Key**. For each value, you can switch on **Set** for:

* **Product Filtering** - Only include products that match a condition, for visitors with this value.
* **Product Ranking** - Give extra points to products that match, so they rank higher.
* **Product Benefits** - Show benefit lines on matching products.
* **Sagent Context** - Guidance for Sagent when the visitor has this value, under **Conversation context for the Sagent**. For example, *This visitor needs wide-fit; frame around comfort and support.*
  {% endstep %}

{% step %}

#### Save

Save the property. It's available to your experiences right away.
{% endstep %}
{% endstepper %}

### Use visitor properties

* **Targeting** - Show an experience only to visitors with a value, such as a campaign for visitors where `vip` is true.
* **Analytics** - Filter reports and dashboards by a visitor property.
* **Product Finder** - Link a question to a visitor property so the answer is remembered beyond the Finder.
* **Recommenders** - Match products to a visitor's value with `{{visitor.property_key}}`. See [Creating a Recommender](https://docs.crobox.com/how-to-guides/product-recommenders/creating-a-recommender.md).
* **Sagent** - Sagent receives the context you wrote for a property or value when the visitor has it.

### Frequently asked questions

<details>

<summary>Can a visitor property's value change?</summary>

Yes. A newer value replaces the old one, for example when your website sends a different value in a later pageview.

</details>

<details>

<summary>My website sends a property, but I can't target on it. Why?</summary>

Create a visitor property here with the exact key your website sends, and a matching **Value Type**. Until then, Crobox ignores the value.

</details>

<details>

<summary>Can I change a property's key?</summary>

No. The **Property Key** is fixed once saved, because experiences and your website refer to it. Create a new property if you need a different key.

</details>

<details>

<summary>What's the difference between general and per-value Sagent context?</summary>

**Sagent Context (general)** applies whenever the visitor has any value for the property. A value's own Sagent context applies only when the visitor has that value. Use both to give general guidance plus value-specific advice.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.crobox.com/how-to-guides/settings/visitor-properties.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
