Справочник JS API виджетов
Методы объекта aplaut в виджетах 2.0: инициализация, модули, аутентификация, заказ, форма отзыва, тексты, стили и события виджетов
Загрузчик виджетов 2.0 создаёт на странице объект aplaut с очередью команд. Метод из массива методов в конце загрузчика можно вызывать сразу: команда выполнится после загрузки скрипта. Метод не из массива доступен только после загрузки.
Все методы, которые скрипт принимает из очереди:
["createWidget", "on", "emit", "off", "setParams", "setConsumer", "setAuthParams", "setAuthStrategy", "manageOrder", "clearFormData", "setLocale", "applyStyles", "showReviewForm", "setProductReviewInviteVisible"]
Загрузчик из раздела Виджеты содержит короткий массив: createWidget, setUser, on, emit, setParams, setConsumer, setAuthParams, manageOrder, clearFormData, setAuthStrategy. Метод setUser виджеты 2.0 не поддерживают: вызов выводит в консоль Aplaut: There is no 'setUser()' function.
Команда из очереди пропускается без ошибки, если у неё нет обязательного аргумента: setConsumer() без объекта, setAuthParams без callback, setLocale без locale, applyStyles с одним аргументом.
Инициализация
aplaut.init
aplaut.init(access_token, settings) инициализирует виджеты. Скрипт запускает инициализацию после события DOMContentLoaded.
До загрузки скрипта загрузчик хранит аргументы последнего вызова init: каждый следующий вызов молча заменяет предыдущий. После загрузки действует первый вызов, а повторный пропускается с сообщением Aplaut: Double 'aplaut.init()' detected в консоли.
| Параметр | Тип | Обязательный | По умолчанию | Описание |
|---|---|---|---|---|
access_token | string | да | — | Токен OAuth-приложения со скоупами content_api и submissions_api |
locale | string | да | — | Язык: ru, en, kz, допустим суффикс региона через дефис (ru-RU). Без него инициализация прерывается ошибкой TypeError |
companyId | string | да | — | Company ID из раздела Настройки → Разработчикам. Без него не работают приглашение оставить отзыв и привязка отправленного контента к компании |
availableWidgets | string[] | да | — | Модули, которые загружаются, см. ниже |
widgetsConfig | object | нет | — | Настройки виджетов, см. справочник настроек |
theme | object | нет | — | Тема оформления, см. справочник темы |
texts | object | нет | — | Замена текстов по языкам: { ru: { … } }. Накладывается поверх встроенного словаря |
analytics | object | нет | — | Счётчики yandexMetrika и google_tag, см. ниже |
availableWidgets
Виджет, модуля которого нет в массиве, не регистрируется, и его тег остаётся пустым. Модули перечисленных виджетов загружаются сразу при инициализации.
| Модуль | Что загружает |
|---|---|
reviews | Список отзывов |
reviewsForm | Форма отзыва. Нужна и виджету отзывов: без неё кнопка Написать отзыв ничего не открывает |
gallery | Отдельный виджет галереи ap-reviews-gallery. Полноэкранный просмотр фото внутри виджета отзывов работает без этого модуля |
questionsAnswers | Вопросы и ответы |
summary | AI-сводка |
productsReviewInvite | Приглашение оставить отзыв |
stories | Сторис |
Модуль информера загружается всегда и в массиве не нужен.
analytics
Виджет сам подключает счётчики и отправляет в них все свои события и события из aplaut.emit: в Метрику как ym(id, "reachGoal", <событие>, <details>), в Google как gtag("event", <событие>, <details>).
| Параметр | Тип | Обязательный | По умолчанию | Описание |
|---|---|---|---|---|
yandexMetrika.id | string | да, для Метрики | — | Номер счётчика |
yandexMetrika.props | object | нет | — | Параметры инициализации Метрики: clickmap, trackLinks, webvisor и другие |
google_tag.tag_id | string | да, для Google | — | ID тега Google |
google_tag.dl_name | string | нет | _dataLayer | Имя dataLayer |
google_tag.gtag_name | string | нет | _gtag | Имя функции gtag |
Аутентификация
aplaut.setConsumer
aplaut.setConsumer({ token }) передаёт JWT покупателя. Виджет отправляет токен с каждым отзывом, вопросом и ответом, а при стратегии jwt без токена не открывает формы. aplaut.setConsumer({ token: null }) разлогинивает покупателя. При загрузке страницы виджет читает токен из параметра адреса ?consumer_token=<JWT>.
aplaut.setAuthParams
aplaut.setAuthParams({ callback }) регистрирует функцию, которую виджеты вызывают перед открытием формы отзыва, вопроса или ответа, а на мобильных устройствах — перед открытием любой выдвижной панели. Функция вызывается каждый раз, даже если токен передан. Если функция завершилась без ошибки, виджет заново проверяет токен и номер заказа и открывает форму. Если функция отклонила промис или выбросила исключение, форма не открывается.
aplaut.setAuthStrategy
aplaut.setAuthStrategy(strategy) меняет стратегию на странице: "jwt" или "otp". По умолчанию действует widgetsConfig.general.authStrategy.
Заказ и корзина
aplaut.manageOrder
aplaut.manageOrder({ setOrder, addToCart }) регистрирует обработчики заказа. Оба необязательны, но вызов без обоих пропускается.
| Параметр | Тип | Описание |
|---|---|---|
addToCart | (contextId: string) => Promise<boolean> | Вызывается кнопками «Добавить в корзину» с ID товара |
setOrder | () => Promise<string | null> | Возвращает номер заказа. Вызывается один раз в момент вызова manageOrder. Исключение прерывает весь вызов, и addToCart из него не регистрируется |
Что делает виджет с результатом addToCart:
| Кнопка | true | false или исключение |
|---|---|---|
| Значок корзины в карточке товара полноэкранной галереи | Меняется на галочку. Отметка хранится в браузере покупателя и сохраняется после перезагрузки. Повторный клик обработчик не вызывает | Не меняется |
Добавить в корзину в шапке виджета отзывов при verifyPurchaseState: true | Скрывается до перезагрузки страницы | Не меняется |
aplaut.setParams
aplaut.setParams(params) передаёт данные открытым текстом, без подписи. Каждый вызов без user_variants сбрасывает ранее переданный вариант товара.
| Параметр | Тип | Описание |
|---|---|---|
name, email, phone, external_id | string | Заполняют поля автора в форме. Хранятся в браузере час |
product_id | string | Переключает форму на другой товар без перезагрузки |
temporary_product_id | string | Временный товар для формы без своего товара |
order_number | string | Номер заказа, как у setOrder |
custom_attributes | object | Произвольные атрибуты отзыва |
user_variants | string | Вариант товара, выбранный покупателем |
consumer_token | string | JWT, из которого заполняются поля формы. Подпись не проверяется, покупатель при этом не аутентифицируется: для этого нужен setConsumer |
Форма отзыва
aplaut.showReviewForm
aplaut.showReviewForm() открывает форму отзыва с теми же проверками, что и кнопка Написать отзыв: setAuthParams, стратегия, verifyPurchaseState. Товар — последний заданный: последний виджет отзывов на странице или setParams({ product_id }). Отдельную форму ap-reviews-form метод открывает только при isHashRoutingDisabled: true, иначе она открывается адресом #/mps/reviews/new/<ID_ТОВАРА>.
aplaut.clearFormData
aplaut.clearFormData() удаляет всё, что виджеты хранят в localStorage: черновик отзыва, данные автора, отметки полезности, кеш товара и сессию подтверждения по одноразовому коду. Без вызова черновик хранится в браузере час после последней правки.
Приглашение оставить отзыв
aplaut.setProductReviewInviteVisible
aplaut.setProductReviewInviteVisible(visible) показывает (true) или скрывает (false) окно приглашения. Если покупатель уже известен виджету, состояние сохраняется в браузере и восстанавливается при следующей загрузке. Вызов с false до загрузки скрипта пропускается.
Тексты и стили
aplaut.setLocale
aplaut.setLocale({ locale }) переключает язык для текстов, которые виджеты выводят после вызова: уже показанный текст не меняется. Доступны язык из locale в aplaut.init и языки, полностью переданные в texts. Суффикс региона метод не отбрасывает: ru-RU покажет ключи текстов вместо перевода.
aplaut.applyStyles
Добавляет CSS в <head> страницы и во все виджеты в Shadow DOM, включая созданные позже. Стили не ограничены виджетами и действуют на всю страницу до её перезагрузки.
| Вызов | Описание |
|---|---|
applyStyles(selector, styles) | Объект CSS-свойств для селектора. Имена свойств пишутся через дефис ("background-color"), значения получают !important. Повторный вызов с тем же селектором заменяет стили |
applyStyles(cssText, key) | Строка CSS. Повторный вызов с тем же key заменяет блок. После загрузки скрипта key можно не передавать: ключом станет сама строка |
События
aplaut.on
aplaut.on(events, callback) подписывает на события виджетов. events — массив имён, ["*"] подписывает на все. Строка вместо массива не работает. callback получает имя события и объект details асинхронно, после обработки события виджетом.
aplaut.on(["reviews_form_write_click", "reviews_form_submit"], (eventName, details) => {
console.log(eventName, details);
});
aplaut.off
aplaut.off(events, callback) снимает подписку. Без callback снимаются все подписчики перечисленных событий. aplaut.off(["*"]) отключает и отправку событий в счётчики из analytics. В текущей версии off срабатывает, только если вызван до загрузки скрипта, через очередь.
aplaut.emit
aplaut.emit(eventName) отправляет событие подписчикам aplaut.on и в подключённые счётчики. Имя может быть любым, например add_to_cart с кнопки вашего сайта. Для Метрики под каждое имя нужна цель типа «JavaScript-событие» с тем же идентификатором.
События виджетов
| Событие | Когда | details |
|---|---|---|
reviews_widget_mount | Виджет отзывов загрузил данные | reviews_widget_mount_total_count |
reviews_list_shown | Список отзывов попал в видимую область или покинул её | reviews_list_shown_total_count, viewed_time_ms |
reviews_list_first_review, reviews_list_third_review, reviews_list_fifth_review, reviews_list_tenth_review | Покупатель долистал до 1-го, 3-го, 5-го, 10-го отзыва | viewed_time_ms |
reviews_list_end | Покупатель долистал до конца списка | viewed_time_ms |
reviews_list_pagination_click | Клик по Показать ещё в отзывах или вопросах | — |
reviews_list_sorter_select | Выбор в селекторе сортировки | — |
reviews_list_sort | Применена сортировка, вместе с reviews_list_sorter_select | sort: new, old, high_rating, low_rating, useful |
reviews_list_filter_select | Отмечена или снята оценка в фильтре | filter |
reviews_list_filter_submit | Фильтр изменён, при каждой отметке | — |
reviews_list_filter_clear | Фильтры сброшены | — |
reviews_inline_filter_apply | Клик по строке оценки в блоке рейтинга | filter: от one_star до five_stars |
reviews_list_search | Поиск по отзывам | query |
reviews_list_show_all_click | Переключатель «все отзывы / этот товар» переведён на все отзывы | — |
reviews_list_like_click, reviews_list_dislike_click | Оценка полезности отзыва. Отмена оценки события не отправляет | reviewId |
reviews_list_add_media | В форму отзыва добавлены фото или видео | — |
reviews_list_rating_detail_toggle, reviews_list_dimension_toggle | Раскрыты или свёрнуты детали рейтинга или характеристики | key, action: expand или collapse |
supplement_add_to_cart_click | Клик по кнопке «Добавить в корзину» в галерее или в шапке отзывов. Отправляется до вызова addToCart | — |
reviews_form_write_click | Клик по Написать отзыв или Войти | — |
reviews_form_first_step_open, reviews_form_second_step_open, reviews_form_success_step_open | Открыт шаг формы | — |
reviews_form_rating_click | Выбрана оценка | rating |
reviews_form_rating_detail_select, reviews_form_author_detail_select | Выбран дополнительный критерий или атрибут автора | name, value |
reviews_form_recommend_click | Ответ на «рекомендую» | recommended |
reviews_form_submit | Отзыв отправлен | review без имени, email, телефона, города и аватара автора |
reviews_form_complete | Закрыт шаг «Спасибо» | — |
qa_list_shown | Список вопросов попал в видимую область | qa_list_shown_total_count, viewed_time_ms |
qa_widget_blank_shown | Показана заглушка «вопросов нет» | viewed_time_ms |
qa_list_like_click, qa_list_dislike_click | Оценка вопроса | questionId |
qa_list_search | Поиск по вопросам | query |
qa_list_sort | Сортировка вопросов | sort |
qa_form_write_click | Клик по Задать вопрос | — |
qa_form_submit | Вопрос отправлен | question без имени и email автора |
replies_like_click, replies_dislike_click | Оценка ответа | questionId, answerId |
replies_form_write_click | Клик по Ответить под отзывом или вопросом | — |
replies_list_show_all_click | Клик по Показать все ответы | — |
Создание виджета в контейнере
aplaut.createWidget({ container_id, widget, context_id, params }) создаёт виджет внутри элемента с указанным id. Основной способ установки — теги виджетов. Типы виджетов перечислены в справочнике настроек, сторис этим методом не создаются. Модуль виджета должен быть в availableWidgets.
| Параметр | Тип | Описание |
|---|---|---|
container_id | string | id элемента-контейнера |
widget | string | Тип виджета |
context_id | string | ID товара |
params | object | Настройки экземпляра, как data-атрибуты. Ключ styles — объект CSS-свойств, которые виджет записывает в style контейнера |
Смотрите также: как настроить вход покупателя для отзывов, как включить проверку покупки и кнопку «В корзину», как изменить тексты и стили виджетов.