# Другие функции
В этом разделе собраны методы, которые чаще используются внутри кампаний, кастомных шаблонов и API-driven сценариев.
---
## Overlay
`GF.Overlay` создает оверлей: попап или полноэкранное всплывающее окно.
**Синтаксис**
```jsx
const overlay = new GF.Overlay(codeObject, options);
overlay.open();
```
{.compact}
| Параметр | Тип | Описание |
| --- | --- | --- |
| `codeObject` [!badge variant="danger" text="обязательно"] | `Object` | Объект с кодом оверлея: `htmlCode`, `cssCode`, `jsCode`. |
| `options` | `Object` | Настройки оверлея. |
| Объект **options**: | | |
| `destroyOnClose` | `boolean` | Удалять оверлей из DOM при закрытии. По умолчанию `true`. |
| `disableScroll` | `boolean` | Зарезервировано в настройках. |
| `closeIcon` | `string` | HTML для кастомной иконки закрытия. |
| `closeEventName` | `string` | Название события, которое отправится при закрытии. |
| `closeClickCallback` | `function` | Колбэк при клике на иконку закрытия. |
| `position` | `string` | Позиция оверлея. По умолчанию `middle`. |
| `autoHide` | `number` | Через сколько секунд автоматически закрыть оверлей. По умолчанию `0`. |
| `backdropColor` | `string` | Цвет фона. По умолчанию `rgba(0,0,0,.7)`. |
| `backdropClose` | `boolean` | Закрывать оверлей по клику на фон. По умолчанию `true`. |
| `showCloseIcon` | `boolean` | Показывать иконку закрытия. По умолчанию `true`. |
| `hideAfterCloseClicked` | `boolean` | Скрывать кампанию после клика по закрытию, если передан `campaignId`. |
=== Пример использования
```jsx
const overlay = new GF.Overlay({
htmlCode: '123
',
cssCode: '.test { background: #fff; padding: 20px; }',
});
overlay.open();
```
===
---
## Отправка кликов кампании
Для кампаний типа Dynamic Content, Recommendations, Overlay и Notification клики отправляются автоматически. В Custom code можно отправить клик вручную, чтобы он попал в отчет кампании.
**Синтаксис**
```jsx
GF.ServerUtils.logClick(${slClickObj});
```
=== Пример в редакторе вариации
```jsx
GF.ServerUtils.logClick({
var: ['${slVariationId}'],
ver: '${slVersionId}',
exp: '${slExperienceId}',
cam: '${slTagId}',
});
```
===
!!!
`${slClickObj}`, `${slVariationId}`, `${slVersionId}`, `${slExperienceId}` и `${slTagId}` - технические переменные редактора вариации Gravity Field. В клиентском коде вне редактора используйте значения, полученные из вашего API-сценария.
!!!
---
## Получить список аудиторий
Метод возвращает массив идентификаторов аудиторий текущего пользователя.
**Синтаксис**
```jsx
GF.Audiences.getCurrent()
```
=== Пример использования
```jsx
const audiences = GF.Audiences.getCurrent();
console.log(audiences);
```
===
---
## Трекинг API-кампании
Методы ниже нужны, когда кампания получена через server-side/API сценарий, а события взаимодействия удобно отправить через web-скрипт.
!!!
Для кампаний, которые рендерит сам web-скрипт, показы и клики обычно отправляются автоматически.
!!!
### Показ кастомного элемента
`GF.Utils.track` отправляет `WRIMP`, когда переданный элемент попадает в экран.
```jsx
GF.Utils.track(elementToTrack, ${gfTrackObj});
```
`${gfTrackObj}` - техническая переменная редактора вариации. Объект должен содержать как минимум `var`, а также обычно `ver`, `exp` и `cam`.
### Взаимодействия по токену API-ответа
`GF.ServerUtils.reportEngagement` отправляет события по токену из server-side/API ответа. Используйте готовый `decisionId` или `slotId` из ответа API; не собирайте токен вручную.
**Синтаксис**
```jsx
GF.ServerUtils.reportEngagement(token, type)
```
{.compact}
| Параметр | Тип | Описание |
| --- | --- | --- |
| `token` [!badge variant="danger" text="обязательно"] | `string` | `decisionId` или `slotId` из API-ответа. |
| `type` [!badge variant="danger" text="обязательно"] | `string` | Тип события: `WRIMP`, `CLICK` или `SLOT_CLICK`. |
=== Пример клика по товару
```jsx
productElement.addEventListener('click', function (event) {
const slotId = event.currentTarget.dataset.slotId;
if (slotId && window.GF?.ServerUtils) {
GF.ServerUtils.reportEngagement(slotId, 'SLOT_CLICK');
}
});
```
===
---
## Отслеживание попадания элементов в экран
Метод возвращает `Promise` с первыми элементами, которые попали в экран. Если передать название события, скрипт дополнительно отправит `CustomEvent` на `document`.
!!!
Фактическое имя метода в скрипте: `detectElementsRealImpresssion` с тремя `s`. Используйте именно это написание.
!!!
**Синтаксис**
```jsx
GF.Utils.detectElementsRealImpresssion(elements, customEventName)
```
{.compact}
| Параметр | Тип | Описание |
| --- | --- | --- |
| `elements` [!badge variant="danger" text="обязательно"] | `HTMLElement / NodeList / Array` | Элемент или список элементов для отслеживания. |
| `customEventName` | `string` | Название `CustomEvent`, который будет отправлен на `document`. |
!!!
Если передавать массив элементов, они должны иметь примерно одинаковые размеры. Иначе расчет попадания 50% элемента в экран может быть некорректным.
!!!
=== Пример использования
```jsx
const targetElements = document.querySelectorAll('.product-item');
const decisionId = apiResponse.decisionId;
document.addEventListener('productInViewport', function (event) {
console.log(event.detail.elements);
});
GF.Utils.detectElementsRealImpresssion(targetElements, 'productInViewport').then(function () {
GF.ServerUtils.reportEngagement(decisionId, 'WRIMP');
});
```
===
---
## Служебные и низкоуровневые методы
Методы ниже экспортируются в публичный объект `GF`, но обычно используются для внутренних задач скрипта, отладки, кастомных кампаний и нестандартных интеграционных сценариев.
!!!
Если задачу можно решить через более высокий уровень API, используйте его. Например, для обычной отправки события предпочтительнее `GF.API('event', ...)`, а не прямой вызов `GF.ServerUtils.logEvent(...)`.
!!!
### Ajax
`GF.Ajax` - тонкая обертка над `XMLHttpRequest`. Для запросов к событиям Gravity Field скрипт автоматически добавляет заголовок `section_id`.
{.compact}
| Метод | Описание |
| --- | --- |
| `GF.Ajax.get(url, withCredentials)` | Выполняет GET-запрос. Возвращает `Promise` с raw response. |
| `GF.Ajax.post(url, data, headers, withCredentials)` | Выполняет POST-запрос. Если `headers['content-type']` равен `application/json`, объект `data` отправляется как JSON. |
```jsx
GF.Ajax.get('/some-endpoint').then(function (response) {
console.log(response);
});
```
### StorageUtils
`GF.StorageUtils` работает с `localStorage`, `sessionStorage` и cookie-хранилищем скрипта.
{.compact}
| Метод | Описание |
| --- | --- |
| `GF.StorageUtils.get(name, storages, options)` | Получает значение из первого доступного хранилища. |
| `GF.StorageUtils.set(name, value, storages, options)` | Записывает значение в одно или несколько хранилищ. |
| `GF.StorageUtils.remove(name, storages)` | Удаляет значение из указанных хранилищ. |
Доступные значения `storages`: `localStorage`, `sessionStorage`, `cookieStorage`.
```jsx
GF.StorageUtils.set('custom-key', 'custom-value', ['localStorage']);
const value = GF.StorageUtils.get('custom-key', ['localStorage']);
```
### digestString
`GF.digestString` считает SHA-256 hash строки и возвращает `Promise` со строкой в hex-формате. Метод используется скриптом, например, для хеширования email перед отправкой события.
```jsx
GF.digestString('user@example.com').then(function (hash) {
console.log(hash);
});
```
### ServerUtils
`GF.ServerUtils` содержит низкоуровневые методы отправки событий и запросов к backend-эндпоинтам скрипта.
{.compact}
| Метод | Описание |
| --- | --- |
| `getEventBaseData()` | Возвращает базовые поля события: `uid`, `ses`, `sec`, `url`, `ctx`, `aud`, `tsrc`, `reqts`. |
| `logEvent(data, endpoint, shouldSave)` | Отправляет событие на endpoint `event` или `page`. Для обычных событий используйте `GF.API('event', ...)`. |
| `logClick(data)` | Отправляет клик кампании. |
| `logBatch(data)` | Отправляет batch impression-событий. |
| `logEngagement(data, type)` | Отправляет engagement-событие: например `click`, `impression`, `WRIMP`. |
| `logRecsEvent(data)` | Отправляет событие рекомендательного виджета. |
| `reportEngagement(token, type)` | Отправляет API engagement по `decisionId` или `slotId`. |
| `getProductSets(setsArray)` | Получает product sets. Также доступен алиас `GF.getProductSets`. |
| `getProductsData(skus, options)` | Получает данные товаров и social proof. |
| `getRecommendations(strategyId, options)` | Низкоуровневый запрос одной рекомендательной стратегии. Обычно используйте `GF.Recommendations.get`. |
| `getRecommendationsBatch(data, options)` | Низкоуровневый batch-запрос рекомендаций. Обычно используйте `GF.Recommendations.get`. |
| `getAffinity()` | Получает affinity-профиль пользователя. |
=== Пример низкоуровневого клика
```jsx
GF.ServerUtils.logClick({
var: ['${slVariationId}'],
ver: '${slVersionId}',
exp: '${slExperienceId}',
cam: '${slTagId}',
});
```
===
=== Пример базовых данных события
```jsx
const baseData = GF.ServerUtils.getEventBaseData();
console.log(baseData.uid, baseData.ses, baseData.ctx);
```
===