Перейти к основному содержимому

Справочник JS API виджетов

Методы объекта aplaut в виджетах 2.0: инициализация, предзагрузка виджетов, аутентификация, заказ, форма отзыва, тексты, смена темы, стили и события виджетов

Загрузчик виджетов 2.0 создаёт на странице объект aplaut с очередью команд. Метод из массива методов в конце загрузчика можно вызывать сразу: команда выполнится после загрузки скрипта. Метод не из массива доступен только после загрузки.

Массив в эталонном загрузчике виджетов:

["createWidget", "setUser", "on", "off", "emit", "setParams", "setConsumer", "setAuthParams", "manageOrder", "clearFormData", "setAuthStrategy"]

Из очереди скрипт принимает ещё setLocale, setTheme, applyStyles, showReviewForm и setProductReviewInviteVisible: чтобы вызывать их до загрузки, допишите их в массив. Загрузчик из раздела Виджеты отличается от эталонного только отсутствием off. Метод 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_tokenstringда—Токен OAuth-приложения со скоупами content_api и submissions_api, см. как получить токен доступа к API
localestringда—Язык: ru, en, kz, допустим суффикс региона через дефис (ru-RU). Без него инициализация прерывается ошибкой TypeError
companyIdstringда—Company ID из раздела Админ → API и доступы → Токены аутентификации. Без него не работают приглашение оставить отзыв и привязка отправленного контента к компании
preloadWidgetsstring[]нет—Виджеты, код которых загружается сразу при инициализации, см. ниже
widgetsConfigobjectнет—Настройки виджетов, см. справочник настроек
themeobjectнет—Тема оформления, см. справочник темы
textsobjectнет—Замена текстов по языкам: { ru: { … } }. Накладывается поверх встроенного словаря
analyticsobjectнет—Счётчики yandexMetrika и google_tag, см. ниже

preloadWidgets​

Все виджеты доступны всегда: при инициализации скрипт регистрирует теги всех виджетов, а код и данные виджета загружает, когда его тег появляется на странице. preloadWidgets только загружает код перечисленных виджетов заранее, не дожидаясь тега. Данные виджет всё равно запрашивает после появления тега: ID товара берётся из него.

ЗначениеВиджет
reviewsОтзывы
reviewsFormФорма отзыва
galleryГалерея ap-reviews-gallery. Псевдоним — reviewsGallery
questionsAnswersВопросы и ответы
summaryAI-сводка
productsReviewInviteПриглашение оставить отзыв
storiesСторис
storiesFormФорма сторис
inlineInformerИнформер. Псевдонимы — inlineRating и rating

Незнакомое значение пропускается без ошибки. Параметр availableWidgets из прежних версий скрипт молча игнорирует: удалять его из кода не обязательно, но и ограничивать набор виджетов он больше не может.

analytics​

Виджет сам подключает счётчики и отправляет в них все свои события и события из aplaut.emit: в Метрику как ym(id, "reachGoal", <событие>, <details>), в Google как gtag("event", <событие>, <details>).

ПараметрТипОбязательныйПо умолчаниюОписание
yandexMetrika.idstringда, для Метрики—Номер счётчика
yandexMetrika.propsobjectнет—Параметры инициализации Метрики: clickmap, trackLinks, webvisor и другие
google_tag.tag_idstringда, для Google—ID тега Google
google_tag.dl_namestringнет_dataLayerИмя dataLayer
google_tag.gtag_namestringнет_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
setOrder() => Promise<string | null>Возвращает номер заказа. Вызывается один раз в момент вызова manageOrder. Исключение в нём не отменяет регистрацию addToCart, но номер заказа не сохраняется

Что делает виджет с результатом addToCart:

Кнопкаtruefalse или исключение
Значок корзины в карточке товара полноэкранной галереиМеняется на галочку. Отметка хранится в браузере покупателя и сохраняется после перезагрузки. Повторный клик обработчик не вызываетНе меняется
Добавить в корзину в шапке виджета отзывов при verifyPurchaseState: trueСкрывается до перезагрузки страницыНе меняется

aplaut.setParams​

aplaut.setParams(params) передаёт данные открытым текстом, без подписи. Каждый вызов без user_variants сбрасывает ранее переданный вариант товара.

ПараметрТипОписание
name, email, phone, external_idstringЗаполняют поля автора в форме. Хранятся в браузере час
product_idstringПереключает форму на другой товар без перезагрузки
temporary_product_idstringВременный товар для формы без своего товара
order_numberstringНомер заказа, как у setOrder
custom_attributesobjectПроизвольные атрибуты отзыва
user_variantsstringВариант товара, выбранный покупателем
consumer_tokenstringJWT, из которого заполняются поля формы. Подпись не проверяется, покупатель при этом не аутентифицируется: для этого нужен 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) окно приглашения. Вызов с true показывает окно сразу, независимо от displayIntervalHours. Если товаров для отзыва нет, окно не появляется. Открытое окно отмечается в браузере покупателя и при следующей загрузке страницы показывается снова через delaySec. Вызов с false до загрузки скрипта пропускается.

Тексты, тема и стили​

aplaut.setLocale​

aplaut.setLocale({ locale }) переключает язык для текстов, которые виджеты выводят после вызова: уже показанный текст не меняется. Доступны язык из locale в aplaut.init и языки, полностью переданные в texts. Суффикс региона метод не отбрасывает: ru-RU покажет ключи текстов вместо перевода.

aplaut.setTheme​

aplaut.setTheme(theme) меняет тему виджетов без перезагрузки страницы. Виджеты не создаются заново: открытая форма, введённый текст и позиция слайдера сохраняются. theme — объект той же формы, что theme в aplaut.init, с изменёнными токенами, см. справочник темы.

ВызовДействие
setTheme(theme)Меняет общую тему всех виджетов. Тема накладывается на тему из init и заменяет предыдущий общий вызов
setTheme({ id, … })Меняет тему только виджетов с тем же id в data-theme. Заменяет предыдущий вызов с этим id. Если такого виджета на странице нет, тема применится, когда он появится
setTheme(), setTheme(null), setTheme({})Возвращает общую тему из init
setTheme({ id })Возвращает виджетам с этим id тему из их data-theme

Вызов с id темы из init (по умолчанию default) меняет общую тему. Тема виджета собирается слоями, каждый следующий перекрывает предыдущий:

  1. Тема по умолчанию.
  2. theme из aplaut.init.
  3. Общий вызов setTheme.
  4. data-theme виджета.
  5. Вызов setTheme с id виджета.

Стили из aplaut.applyStyles действуют поверх темы. Значение токена в cssVars можно передать строкой: color_text_primary: "#eeeeee" равно { default: "#eeeeee" }. Вызов с аргументом-не-объектом и токены с недопустимым значением пропускаются без ошибки.

aplaut.q.push(["setTheme", theme]) до загрузки скрипта применяет тему до отрисовки виджетов, и они сразу показываются в ней. После загрузки скрипт очередь не читает: вызывайте aplaut.setTheme напрямую.

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, payload) отправляет событие подписчикам aplaut.on и в подключённые счётчики. Имя может быть любым, например add_to_cart с кнопки вашего сайта. Необязательный payload подписчики получают вторым аргументом как details. Для Метрики под каждое имя нужна цель типа «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Клик по Загрузить еще в виджете отзывов. Виджет вопросов это событие не отправляетtotal_count, page — номер загружаемой страницы
reviews_list_sorter_selectВыбор в селекторе сортировки—
reviews_list_sortПрименена сортировка, вместе с reviews_list_sorter_selectsort: 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Клик по Показать все ответы—
report_submitЖалоба на отзыв, вопрос или ответ отправлена. При ошибке отправки событие не отправляетсяreportableType, reportableId, reason

Создание виджета в контейнере​

aplaut.createWidget({ container_id, widget, context_id, params }) создаёт виджет внутри элемента с указанным id. Основной способ установки — теги виджетов. Типы виджетов перечислены в справочнике настроек, включая stories и storiesForm. С неизвестным типом метод выводит в консоль Can't create a widget. Unknown type.

ПараметрТипОписание
container_idstringid элемента-контейнера
widgetstringТип виджета
context_idstringID товара
paramsobjectНастройки экземпляра, как data-атрибуты. Ключ styles — объект CSS-свойств, которые виджет записывает в style контейнера

Смотрите также: как настроить вход покупателя для отзывов, как включить проверку покупки и кнопку «В корзину», как изменить тексты и стили виджетов.