# Reference

<table><thead><tr><th width="220.5">Method</th><th>Description</th></tr></thead><tbody><tr><td><a href="#iadvize.help">help</a></td><td>Displays a list of available commands in the console</td></tr><tr><td><a href="#iadvize.activate-iadvize.logout">activate / logout</a></td><td><p>Activates the tag with an identity or removes an identity, effectively stopping the tag.</p><p>Needed when authentication is enabled.</p></td></tr><tr><td><a href="#iadvize.get">get</a></td><td>Getters for retrieving public properties</td></tr><tr><td><a href="#iadvize.set">set</a></td><td>Getters for defining public properties</td></tr><tr><td><a href="#iadvize.on-iadvize">on</a></td><td>Event listeners to watch for changes of specific properties</td></tr><tr><td><a href="#iadvize.off-iadvize">off</a></td><td>Remove an event listener</td></tr><tr><td><a href="#iadvize.recordtransaction">recordTransaction</a></td><td>Inform iAdvize that a transaction has occurred on your website</td></tr><tr><td><a href="#iadvize.navigate">navigate</a></td><td>Changes the current screen and restart the tag, allowing a new targeting run</td></tr></tbody></table>

## iAdvize.help <a href="#iadvize.help" id="iadvize.help"></a>

* Lists all the available methods,
* Lists all the available properties on `get` and `set`,
* Lists all the available events on `on` and `off`.

## iAdvize.activate / iAdvize.logout <a href="#iadvize.activate-iadvize.logout" id="iadvize.activate-iadvize.logout"></a>

These methods are used for authentication. Please see the dedicated Help Center article : <https://help.iadvize.com/hc/articles/6043078724626>

## iAdvize.get <a href="#iadvize.get" id="iadvize.get"></a>

`iAdvize.get` takes a single property argument, and returns the associated value. Properties are keys that reference values that can change over time. These values can be accessed :

* directly, using `iAdvize.get` (ex: `iAdvize.get('visitor:cookiesConsent')`)
* when they change, using iAdvize.on (ex: `iAdvize.on('visitor:cookiesConsentChange', callback)`)

| Property                           | Description                                                              | Values                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ---------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| chatbox:status                     | The status of the chatbox                                                | `OPENED`, `REDUCED`, `CLOSED` (default)                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| conversation:id                    | The id of the conversation                                               | `string`, `null` (default)                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| tag:version                        | The tag version                                                          | `"LIGHT"`, `"FULL"`                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| visitor:cookiesConsent             | Whether the visitor consented to cookies or not                          | `true`, `false`, `null` (default)                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| visitor:GDPRConsent                | Whether the visitor consented to GDPR or not                             | `true`, `false`, `null` (default)                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| visitor:sourceId                   | The ID of the visitor                                                    | `string`, `null` (default)                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| customData                         | The current custom data object                                           | `object`                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| engagementRules:triggered          | Get all the triggered rules id on the page                               | <p><code>string\[]</code><br><br>Array of ids of engagement rules</p>                                                                                                                                                                                                                                                                                                                                                                                                    |
| engagementNotifications:displayed  | Get all the displayed notifications on the page                          | <p><code>object\[]</code><br><br>type: <code>"BADGE"</code>, <code>"CLASSIC"</code>, <code>"MESSAGING"</code>, <code>"INVITATION"</code>, <code>"MINI\_BADGE"</code>, <code>"CHATBOX"</code>, <code>"MESSAGE"</code>, <code>"CUSTOM\_BUTTON"</code>, <code>"EMBEDDED\_CONVERSATION\_STARTER"</code><br>id (notification id): <code>string</code><br>ruleId: <code>string</code><br>channels: <code>\["CHAT", "CALL", "VIDEO", "MESSENGER", "SMS", "WHATSAPP"]</code></p> |
| engagementNotifications:controlled | Get all the controlled notifications of a the increment test on the page | <p><code>object\[]</code><br><br>type: <code>"BADGE"</code>, <code>"CLASSIC"</code>, <code>"MESSAGING"</code>, <code>"INVITATION"</code>, <code>"MINI\_BADGE"</code>, <code>"CHATBOX"</code>, <code>"MESSAGE"</code>, <code>"CUSTOM\_BUTTON"</code>, <code>"EMBEDDED\_CONVERSATION\_STARTER"</code></p>                                                                                                                                                                  |
| incrementTestVisitorGroup          | The visitor's group assignment in an A/B increment test                  | `"EXPOSED"`, `"CONTROL"`, `null` (default)                                                                                                                                                                                                                                                                                                                                                                                                                               |

#### Example :

```javascript
window.iAdvizeInterface = window.iAdvizeInterface || [];
window.iAdvizeInterface.push(function (iAdvize) {
  const visitorCookiesConsent = iAdvize.get('visitor:cookiesConsent');
});
```

## iAdvize.set <a href="#iadvize.set" id="iadvize.set"></a>

Set editable properties.

| Property                  | Description                                                                                                                                                                                                                                                                                                                                            | Values                           |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- |
| visitor:cookiesConsent    | Whether the visitor consented to cookies or not. Optionally accepts a third argument (`ttl` in seconds) when called as `iAdvize.set('visitor:cookiesConsent', hasConsented, ttl)` to customise how long the consent and the generated VUID cookie stay valid (defaults to 31536000 seconds / 365 days when omitted).                                   | `true`, `false`                  |
| visitor:GDPRConsent       | Whether the visitor consented to GDPR or not                                                                                                                                                                                                                                                                                                           | `true`, `false`                  |
| customData                | Shallow‑merge the provided key/value pairs into the custom data store (accessible via `iAdvize.get('customData')`) to enrich targeting, notifications, and conversation payloads. Updates are debounced (\~500 ms) and re‑evaluate engagement rules that depend on custom data; related experiences that rely on these values may refresh accordingly. | `object`                         |
| incrementTestVisitorGroup | Assigns the visitor to a group in an A/B increment test. When set to `"CONTROL"`, notifications are created but hidden from the visitor to measure the impact of showing vs not showing them. When set to `"EXPOSED"`, notifications are displayed normally. Set to `null` to disable the test.                                                        | `"EXPOSED"`, `"CONTROL"`, `null` |

#### Example :

```javascript
window.iAdvizeInterface = window.iAdvizeInterface || [];
window.iAdvizeInterface.push(function (iAdvize) {
  iAdvize.set('visitor:GDPRConsent', true);
  // CMP scenario: store consent for 6 months and align the VUID cookie duration
  iAdvize.set('visitor:cookiesConsent', true, 60 * 60 * 24 * 30 * 6);
});
```

#### Custom data usage examples

Custom data allows you to send real‑time context to iAdvize based on the visitor’s navigation on your website. For example, you can send the product IDs being viewed so that iAdvize can adapt the content of Conversation Starter notifications, and so that the AI Shopping Assistant understands the visitor’s browsing context.

You can also pass other contextual information, such as page type, product categories, or details about the visitor’s identity (when logged in), to personalize the AI Shopping Assistant’s responses (advanced configuration may be required).

There are many other uses for custom data, such as engaging visitors based on these values, or transmitting contextual information about visitors and their conversations to the human agent who will handle them from the Desk.

```javascript
window.iAdvizeInterface = window.iAdvizeInterface || [];
window.iAdvizeInterface.push(function (iAdvize) {
  // Update or add keys. This performs a shallow merge into the custom data store
  iAdvize.set('customData', { productId: 'SKU-123' });
});
```

* Updating `customData` reruns engagement rules that depend on custom data and can refresh surfaces that leverage these values (for example, certain notifications or knowledge suggestions).
* The merge is shallow (top-level keys only) .
* Custom data is included when creating a conversation and can be used by multiple features (e.g., targeting, notifications, reporting).
* Reading: prefer `iAdvize.get('customData')` over direct access to the underlying store.
* Listening: `iAdvize.on('customData', (next, prev) => { /* ... */ })` provides the next and previous values.
* Supported types for targeting and visitor context: `string`, `number`, `boolean`, and `string[]` (arrays are serialized as CSV). Nested objects/arrays are not deeply merged (they are replaced) and are ignored for targeting.

{% hint style="info" %}
For more information on the use of custom data and its implementation, please read the following articles:

* [Integrate the Custom Data tag manually](https://help.iadvize.com/hc/en-gb/articles/29565124093202)
* [Create and use the Custom data](https://help.iadvize.com/hc/en-gb/articles/203401593)
  {% endhint %}

## iAdvize.on <a href="#iadvize.on-iadvize" id="iadvize.on-iadvize"></a>

Listen to a property change.

`iAdvize.on` takes two arguments :

* The name of an event,
* A callback that takes the associated event value and the previous value as parameter.

<table><thead><tr><th>Property</th><th width="241.5806884765625">Description</th><th>Values</th></tr></thead><tbody><tr><td>chatbox:statusChange</td><td>The status of the chatbox</td><td><code>OPENED</code>, <code>REDUCED</code>, <code>CLOSED</code> (default)</td></tr><tr><td>conversation:idChange</td><td>The id of the conversation</td><td><code>string</code>, <code>null</code> (default)</td></tr><tr><td>tag:versionChange</td><td>The tag version</td><td><code>"LIGHT"</code>, <code>"FULL"</code></td></tr><tr><td>visitor:cookiesConsentChange</td><td>Whether the visitor consented to cookies or not</td><td><code>true</code>, <code>false</code>, <code>null</code> (default)</td></tr><tr><td>visitor:GDPRConsentChange</td><td>Whether the visitor consented to GDPR or not</td><td><code>true</code>, <code>false</code>, <code>null</code> (default)</td></tr><tr><td>visitor:sourceIdChange</td><td>The ID of the visitor</td><td><code>string</code>, <code>null</code> (default)</td></tr><tr><td>customData</td><td>Fired when the custom data object is updated</td><td><code>object</code> (listener receives next and previous values)</td></tr><tr><td>engagementRules:triggeredChange</td><td>Get all the triggered rules id on the page</td><td><code>string[]</code><br><br>Array of ids of engagement rules</td></tr><tr><td>engagementNotifications:displayedChange</td><td>Get all the notifications displayed on the page</td><td><code>object[]</code><br><br>type: <code>"BADGE"</code>, <code>"CLASSIC"</code>, <code>"MESSAGING"</code>, <code>"INVITATION"</code>, <code>"MINI_BADGE"</code>, <code>"CHATBOX"</code>, <code>"MESSAGE"</code>, <code>"CUSTOM_BUTTON"</code>, <code>"EMBEDDED_CONVERSATION_STARTER"</code><br>id (notification id): <code>string</code><br>ruleId: <code>string</code><br>channels: <code>["CHAT", "CALL", "VIDEO", "MESSENGER", "SMS", "WHATSAPP"]</code></td></tr><tr><td>engagementRule:triggered</td><td>Called when an engagement rule is triggered on the page</td><td><code>string</code><br><br>Id of engagement rule</td></tr><tr><td>engagementNotification:displayed</td><td>Triggered when a notification is displayed on the page</td><td><code>object</code><br><br>type: <code>"BADGE"</code>, <code>"CLASSIC"</code>, <code>"MESSAGING"</code>, <code>"INVITATION"</code>, <code>"MINI_BADGE"</code>, <code>"CHATBOX"</code>, <code>"MESSAGE"</code>, <code>"CUSTOM_BUTTON"</code>, <code>"EMBEDDED_CONVERSATION_STARTER"</code><br>id (notification id): <code>string</code><br>ruleId: <code>string</code><br>channels: <code>["CHAT", "CALL", "VIDEO", "MESSENGER", "SMS", "WHATSAPP"]</code></td></tr><tr><td>engagementNotification:clicked</td><td>Triggered when the notification is clicked</td><td><code>object</code><br><br>type: <code>"BADGE"</code>, <code>"CLASSIC"</code>, <code>"MESSAGING"</code>, <code>"INVITATION"</code>, <code>"MINI_BADGE"</code>, <code>"CUSTOM_BUTTON"</code>, <code>"EMBEDDED_CONVERSATION_STARTER"</code><br>id (notification id): <code>string</code><br>ruleId: <code>string</code><br>channel: <code>"CHAT", "CALL", "VIDEO", "MESSENGER", "SMS", "WHATSAPP"</code><br>text: <code>string</code> This field is populated only for <code>EMBEDDED_CONVERSATION_STARTER</code> notifications (except for the "last button"); otherwise, the value is null.</td></tr><tr><td>engagementNotification:controlled</td><td>Triggered when the notification is not authorized in the increment test</td><td><code>object</code><br><br>type: <code>"BADGE"</code>, <code>"CLASSIC"</code>, <code>"MESSAGING"</code>, <code>"INVITATION"</code>, <code>"MINI_BADGE"</code>, <code>"CHATBOX"</code>, <code>"MESSAGE"</code>, <code>"CUSTOM_BUTTON"</code> | <code>undefined</code>, <code>"EMBEDDED_CONVERSATION_STARTER"</code><br>id (notification id): <code>string</code> | <code>undefined</code><br>ruleId: <code>string</code><br>channel: <code>"CHAT", "CALL", "VIDEO", "MESSENGER", "SMS", "WHATSAPP"</code></td></tr><tr><td>incrementTestVisitorGroupChange</td><td>Triggered when the visitor's A/B test group assignment changes</td><td><code>"EXPOSED"</code>, <code>"CONTROL"</code>, <code>null</code> (default)</td></tr></tbody></table>

#### Example :

```javascript
window.iAdvizeInterface = window.iAdvizeInterface || [];
window.iAdvizeInterface.push(function (iAdvize) {
  iAdvize.on('visitor:cookiesConsentChange', function (visitorCookiesConsent, previousValue) {
    // The new value 
    console.log(visitorCookiesConsent);
    // The previous Value
    console.log(previousValue);
  });
});
```

## iAdvize.off <a href="#iadvize.off-iadvize" id="iadvize.off-iadvize"></a>

Remove the event listener.

`iAdvize.off` takes two arguments :

* The name of an event,
* A callback that takes the associated event value and the previous value as parameter.

#### Example :

```javascript
window.iAdvizeInterface = window.iAdvizeInterface || [];
window.iAdvizeInterface.push(function (iAdvize) {
  const callback = (visitorCookiesConsent, previousValue) => console.log(visitorCookiesConsent, previousValue);
  // Listen the changes
  iAdvize.on('visitor:cookiesConsentChange', callback);
  // Remove the listener
  iAdvize.off('visitor:cookiesConsentChange', callback);
});
```

## iAdvize.recordTransaction <a href="#iadvize.recordtransaction" id="iadvize.recordtransaction"></a>

Allows to record transactions. See the dedicated article on the Help Center: <https://help.iadvize.com/hc/en-gb/articles/206375538>

#### Example :

```javascript
window.iAdvizeInterface = window.iAdvizeInterface || [];
window.iAdvizeInterface.push(function (iAdvize) {
  iAdvize.recordTransaction({
    id: 'unique-id',
    amount: 49.95,
  });
});
```

## iAdvize.navigate

<table><thead><tr><th width="170">Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>path</td><td><code>String</code></td><td>Path/URL you wish to tell iAdvize where the visitor is "virtually" browsing</td></tr></tbody></table>

If part of your web site is built using SPA technology that does not update your browser's history (=your site's url does not change, even though the page displayed to the visitor does), you can simulate a page change using the `iAdvize.navigate("YOUR_PATH")` method.

This will restart iAdvize's targeting engine to take into account the new URL/path value you enter as parameter.