# JS SDK API

JS SDK API — клиентский интерфейс web-скрипта Gravity Field. Через него можно отправлять события, получать рекомендации и данные товаров, запускать embed-кампании, ждать появления элементов на странице и отправлять трекинг для API-driven сценариев.

Скрипт публикует один и тот же объект в `window.GF` и `window.SL`. В новом клиентском коде используйте `GF`; `SL` остается совместимым legacy-алиасом.

---

## Что должно быть настроено

Перед использованием JS SDK проверьте базовую web-интеграцию:

- на странице подключен `core.js`;
- до загрузки скрипта объявлен `window.GF`;
- задан `GF.section`;
- задан `GF.pageContext` с типом страницы и данными контекста.

Подробнее: [Установка скрипта](/Integration/web_integration/script.md) и [Контекст страницы](/Integration/web_integration/page_context.md).

---

## С чего начать

{.compact}
| Задача | Куда перейти |
| --- | --- |
| Передать пользовательское действие: добавление в корзину, покупку, wishlist или кастомное событие | [Передача событий](/Integration/web_integration/events.md) |
| Получить рекомендации и отрисовать собственный виджет | [Работа с рекомендательными виджетами](./work_rec_widgets.md) |
| Получить данные товаров, social proof или product set | [Получение информации о товаре](./get_product_info.md) |
| Дождаться DOM-элемента, переменной, SDK-события или попадания элемента в экран | [Ожидание элементов, переменных](./wait_for_elements.md) |
| Запустить embed-кампанию из клиентского кода | [Вставка embed виджетов](./inster_widget.md) |
| Отправить трекинг API-кампании или использовать advanced-методы | [Другие полезные функции](./other_helpful.md) |

---

## Структура раздела

- [Работа с рекомендательными виджетами](./work_rec_widgets.md) — получение товаров рекомендаций, ручная разметка виджета, `GF.Recommendations.track`, события `gf_wrimp` и `gf_pimp`, динамические правила.
- [Получение информации о товаре](./get_product_info.md) — данные товара из фида, social proof, product sets и `GF.pageData`.
- [Получение аффинити профиля пользователя](./get_affinity_profile.md) — `GF.ServerUtils.getAffinity()` и `GF.userAffinity`.
- [Ожидание элементов, переменных](./wait_for_elements.md) — `GF.waitForElement`, `GF.waitForVariable`, `GF.PubSub`, `GF.Utils.waitUntil`, `GF.Utils.sendEventInViewport`.
- [Вставка embed виджетов](./inster_widget.md) — запуск кампании через `GF.Utils.runCampaign`.
- [Другие полезные функции](./other_helpful.md) — overlay, аудитории, API engagement tracking и низкоуровневые методы.

---

## Готовность скрипта

После инициализации скрипт отправляет событие `gf-ready`. Используйте его, если код должен выполняться только после загрузки пользовательских данных, `dynamic.js`, кампаний и публичных методов SDK.

```jsx
document.addEventListener('gf-ready', function () {
  // JS SDK is ready
});
```

---

## Отправка событий и SPA

`GF.API()` добавляет действие в очередь скрипта. Если метод вызван до полной инициализации, действие будет выполнено после запуска очереди.

{.compact}
| Вызов | Назначение |
| --- | --- |
| `GF.API('event', eventObject)` | Отправить пользовательское событие. Подробнее: [Передача событий](/Integration/web_integration/events.md). |
| `GF.API('pageview', data)` | Отправить pageview. Обычно вызывается скриптом автоматически. |
| `GF.API('spa', params)` | Обновить контекст и перезапустить SPA-кампании. Подробнее: [SPA](/Integration/web_integration/spa.md). |

```jsx
GF.API('event', {
  name: 'Add to Wishlist',
  properties: {
    eventType: 'add-to-wishlist-v1',
    productId: 'item-34454',
  },
});
```

---

## Карта методов

{.compact}
| Сценарий | Метод | Подробнее |
| --- | --- | --- |
| Получить товары рекомендаций | `GF.Recommendations.get(strategy, options, callback)` | [Работа с рекомендательными виджетами](./work_rec_widgets.md) |
| Разметить и отслеживать кастомный рекомендательный виджет | `GF.Recommendations.track(element, variationData)` | [Работа с рекомендательными виджетами](./work_rec_widgets.md) |
| Получить данные товаров и social proof | `GF.ServerUtils.getProductsData(skus, options)` | [Получение информации о товаре](./get_product_info.md) |
| Получить product set | `GF.ServerUtils.getProductSets(ids)` или `GF.getProductSets(ids)` | [Получение информации о товаре](./get_product_info.md) |
| Получить affinity-профиль | `GF.ServerUtils.getAffinity()` | [Получение аффинити профиля пользователя](./get_affinity_profile.md) |
| Ожидать DOM-элемент | `GF.waitForElement(selector, callback, minElements, interval, maximumRetries)` | [Ожидание элементов, переменных](./wait_for_elements.md) |
| Ожидать переменную в `window` | `GF.waitForVariable(variable, interval, maximumRetries)` | [Ожидание элементов, переменных](./wait_for_elements.md) |
| Подписаться на события SDK | `GF.PubSub.on(topic, callback)` и `GF.PubSub.once(topic, callback)` | [Ожидание элементов, переменных](./wait_for_elements.md) |
| Запустить embed-кампанию | `GF.Utils.runCampaign(campaignId, params)` | [Вставка embed виджетов](./inster_widget.md) |
| Создать overlay | `new GF.Overlay(codeObject, options)` | [Другие полезные функции](./other_helpful.md) |
| Отправить трекинг API-кампании | `GF.ServerUtils.reportEngagement(token, type)` | [Другие полезные функции](./other_helpful.md) |
| Получить аудитории текущего пользователя | `GF.Audiences.getCurrent()` | [Другие полезные функции](./other_helpful.md) |
| Выполнить низкоуровневый HTTP-запрос | `GF.Ajax.get(url, withCredentials)` / `GF.Ajax.post(url, data, headers, withCredentials)` | [Другие полезные функции](./other_helpful.md#ajax) |
| Работать с хранилищами скрипта | `GF.StorageUtils.get(...)`, `GF.StorageUtils.set(...)`, `GF.StorageUtils.remove(...)` | [Другие полезные функции](./other_helpful.md#storageutils) |
| Получить SHA-256 hash строки | `GF.digestString(string)` | [Другие полезные функции](./other_helpful.md#digeststring) |
| Получить базовые данные события | `GF.ServerUtils.getEventBaseData()` | [Другие полезные функции](./other_helpful.md#serverutils) |
| Отправить низкоуровневое событие | `GF.ServerUtils.logEvent(data, endpoint, shouldSave)` | [Другие полезные функции](./other_helpful.md#serverutils) |
| Отправить низкоуровневый engagement | `GF.ServerUtils.logEngagement(data, type)` / `GF.ServerUtils.logRecsEvent(data)` | [Другие полезные функции](./other_helpful.md#serverutils) |
| Выполнить низкоуровневые запросы рекомендаций | `GF.ServerUtils.getRecommendations(...)` / `GF.ServerUtils.getRecommendationsBatch(...)` | [Другие полезные функции](./other_helpful.md#serverutils) |