Встраиваемый виджет
Если вы предпочитаете ничего не строить, вставьте эти две строки. Виджет — это custom element, рендерящийся в shadow root, поэтому он не наследует ваши стили и не влияет на них.
<script src="https://api.changeloop.dev/widget.js" defer></script>
<changelogapp-widget
data-public-id="YOUR_PUBLIC_ID"
data-api="https://api.changeloop.dev"></changelogapp-widget>
Оба атрибута обязательны. data-public-id — это ID вашего фида, data-api — источник, с которого виджет получает данные. Если какого-то из них не хватает, элемент пишет ошибку в консоль и ничего не рендерит, что является первым, что нужно проверить, если вы видите пустое место там, где должен быть виджет.
Добавьте элементу data-theme="dark" для тёмного отображения; ваша страница может переключать его на лету. Для более тонкой настройки виджет предоставляет CSS-переменные (--changelogapp-text, --changelogapp-bg, --changelogapp-accent и другие) и имена ::part(), которые вы задаёте в собственной таблице стилей. Приложение показывает обе темы вживую в Настройках, раздел Публичный фид.
Добавьте data-repos, чтобы показывать только часть репозиториев, например changelog одного продукта на сайте этого продукта, когда несколько продуктов используют один аккаунт. Значение - список полных имён owner/repo через запятую; имя без владельца ничему не соответствует и выводит пустую ленту без ошибки. Учитывается не более десяти репозиториев. Ограниченный так виджет показывает только вкладки Updates и Feedback, потому что у роадмапа нет представления по репозиториям, а отзывы по-прежнему попадают туда, куда указывает цель отзывов вашей команды. В разделе Настройки, Публичная лента есть селектор, который запишет атрибут за вас.
Он рендерит три вкладки в этом порядке: Updates, Roadmap и Feedback. Первые две читают фиды выше. Третья отправляет на endpoint ниже и хранит ID каждой отправки в localStorage, поэтому посетитель может вернуться и увидеть, что произошло с тем, что он отправил.
Скрипт подаётся с версионированием. /widget.js всегда подаёт новейшую сборку и кэшируется на час, поэтому релиз доходит до ваших посетителей без каких-либо действий с вашей стороны. /widget-vN.js фиксирует одну сборку: как только номер версии был подан, её байты больше никогда не меняются, и она кэшируется на год. Зафиксируйте её, если предпочитаете принимать изменения намеренно.
Загружайте ровно один скрипт виджета на страницу
Два URL — это альтернативы, а не слои. Оба регистрируют одно и то же имя custom element, а браузер позволяет зарегистрировать имя только один раз на документ: какой скрипт выполнится первым, тот и побеждает на весь срок жизни страницы, а второй становится неактивным. Так что страница, содержащая и /widget.js, и /widget-v5.js, рендерит тот, который браузер выполнил первым, а это не то, что вы контролируете, и добавление /widget-v5.js рядом с существующим /widget.js для фиксации версии ничего не делает.
Когда это происходит, виджет пишет предупреждение в консоль, называя обе сборки, так что вы не остаётесь гадать. Он не может сделать больше, чем предупредить: к моменту выполнения второй копии первая уже заняла имя. Решение — всегда заменять тег скрипта, а не добавлять другой, и то же самое применимо, если менеджер тегов или частичный шаблон вставляет его за вас. Чтобы перейти от постоянно обновляемой сборки к зафиксированной, измените src.
Всплывающая карточка релиза
Добавьте data-mode="popup", и элемент перестанет рисовать вкладки. Когда у посетителя есть что-то новое, он показывает одну небольшую карточку с вашим последним релизом, а в остальных случаях не показывает ничего. Значение data-mode не зависит от регистра.
<script src="https://api.changeloop.dev/widget.js" defer></script>
<changelogapp-widget
data-public-id="YOUR_PUBLIC_ID"
data-api="https://api.changeloop.dev"
data-mode="popup"
data-changelog-url="https://feed.changeloop.dev/feed/YOUR_PUBLIC_ID"></changelogapp-widget>
На широких экранах карточка стоит в левом нижнем углу, потому что правый нижний обычно занят кнопкой чата. На экранах уже 480px она занимает всю ширину и перекрывает кнопку чата, пока её не закроют. Карточка открывается в верхнем слое браузера, поэтому overflow, transform или z-index родительского элемента не смогут её обрезать или спрятать. Чтобы сдвинуть её, задайте стили для ::part(popup).
Каждый релиз показывается один раз. Карточка появляется, когда у посетителя есть записи, которых он ещё не видел. Она показывает самую новую из них, а если их несколько, добавляет счётчик, и считает записи просмотренными в момент появления. Следующая загрузка страницы ничего не покажет, пока вы не опубликуете что-то новое.
Первый визит не показывает ничего: виджет лишь запоминает, докуда дошёл ваш changelog, чтобы существующие пользователи не получали старые новости в день подключения. Карточка начнёт появляться со следующего релиза. Посетителю, который уже прочитал релиз во встроенном виджете, он повторно не показывается.
Что посетитель уже видел, хранится в localStorage, а не в cookie, поэтому данные привязаны к одному браузеру и одному источнику сайта. Тот же человек на другом вашем домене начнёт с первого визита. Если браузер блокирует хранилище, каждый визит считается первым, и карточка не появляется никогда.
Атрибут data-changelog-url необязателен. Если указать адрес с http или https, в карточке появится ссылка "See all updates", обычно на вашу размещённую страницу или на собственную страницу changelog. При любом другом значении ссылка не рисуется. Атрибуты data-theme и data-repos работают точно так же, как во встроенном виджете.
Карточка никогда не забирает фокус и не блокирует страницу: это подписанная область, а не диалог. Она закрывается кнопкой закрытия или клавишей Escape, пока фокус находится внутри карточки. Escape в любом другом месте страницы остаётся на усмотрение вашего кода.
Правило одного скрипта виджета на страницу действует и здесь. Всплывающая карточка и встроенный виджет могут жить на одной странице: загрузите скрипт один раз и добавьте оба элемента, и они будут одинаково знать, что посетитель уже видел.
Зафиксированные сборки до /widget-v18.js включительно старше всплывающей карточки. Они игнорируют data-mode и вместо неё рисуют встроенные вкладки, поэтому используйте /widget.js или более новую зафиксированную сборку.
В приложении, в Настройках, раздел Публичный фид, этот сниппет уже готов к копированию: с вашим ID фида, темой и выбранными репозиториями. Показы карточки и клики по её ссылке "Learn more" отображаются в Аналитике отдельными числами.
Эмодзи-реакции
Читатели могут отреагировать на запись, ничего не написав. Когда реакции включены, каждая запись заканчивается рядом из пяти эмодзи, 👍 🎉 ❤️ 🚀 👀, у каждого со своим счётчиком. Ряд виден во встроенном виджете, на всплывающей карточке релиза и на размещённой у нас странице фида.
Пока вы не включите реакции в приложении, в Настройках, раздел Публичный фид, они выключены. Ваш код встраивания менять не нужно: виджет считывает переключатель из вашего фида, поэтому ряд появляется и исчезает вместе с ним. Если выключить реакции, ряд скрывается, а счётчики сохраняются и вернутся при повторном включении. Зафиксированные сборки, выпущенные до появления реакций, этот ряд не показывают никогда.
Каждый читатель может поставить каждую реакцию на запись один раз, а повторное нажатие снимает её. Виджет различает читателей по случайному ID, который создаёт в браузере при первом клике, а не по аккаунту или адресу email. Мы храним только хеш этого ID вместе с вашей командой, поэтому один и тот же браузер оставляет несвязанные хеши в двух разных changelog.
Счётчики приблизительные: это дружеский сигнал, а не голосование. Если очистить хранилище браузера или открыть приватное окно, можно отреагировать снова, поэтому не принимайте по ним важных решений. Счётчики в вашем фиде могут отставать на несколько минут, потому что фид кешируется, но тот, кто нажал, сразу видит свою реакцию в счётчике. В приложении на вкладке Опубликованные во входящих показан общий итог по каждой записи.
Реакция сохраняет в localStorage посетителя две вещи, но никогда не в cookie. В changelogapp-widget:reader-id лежит случайный ID, по одному на браузер и источник сайта. В changelogapp-widget:reactions: с добавленным ID вашего фида хранятся реакции, выбранные в этом браузере, не более чем для 200 записей, тех, на которые он реагировал последними. Размещённая страница хранит те же две записи под своим адресом. Если браузер блокирует хранилище, реакции продолжают работать в рамках текущего просмотра страницы, но потом не запоминаются.
Чтобы стилизовать ряд, используйте ::part(reactions), ::part(reaction) для каждой кнопки и ::part(reaction-count) для её числа. Все они перечислены ниже в разделе Стилизация. Нулевой счётчик числа не показывает. У нажатой кнопки есть aria-pressed="true", и она рисуется с обводкой цвета вашего --changelogapp-accent и жирным текстом. ::part() не умеет выбирать по этому атрибуту, поэтому чтобы изменить вид нажатой кнопки, задайте --changelogapp-accent.
Публичная доска пожеланий
Доска позволяет читателям увидеть, что просят другие, и проголосовать за это. Когда доска включена, вкладка Feedback открывается с самыми популярными запросами и статусом каждого, а привычная форма находится под ними.
Пока вы не включите доску в приложении, в Настройках, раздел Публичный фид, она выключена. Ваш код встраивания менять не нужно: виджет считывает переключатель из вашего фида. Если выключить доску, она скрывается, а ваши запросы и голоса за них сохраняются. Доска находится на вкладке Feedback, поэтому в виджете без этой вкладки доски тоже нет.
Доска показывает только то, что написали вы. Отзыв посетителя сам по себе на неё никогда не попадает: вы решаете, какие запросы выставить на доску, и сами пишете заголовок и описание каждого на странице Feedback board в приложении. Запрос можно создать из сообщения посетителя или добавить собственную идею, при этом доска никогда не показывает ни сообщение посетителя, ни его адрес email. На доске видны ваши 100 лучших запросов, а команда может хранить до 500.
У каждого запроса один из пяти статусов: "Under consideration", "Planned", "In progress", "Shipped" или "Declined". Свяжите запрос с записью, и он сам перейдёт в "Shipped", когда эта запись будет опубликована, а если она уже опубликована, то сразу. Запрос, созданный из сообщения посетителя, тоже переходит в "Shipped", когда публикуется запись, выполняющая это сообщение.
С одного браузера на каждом сайте можно отдать один голос за запрос, а повторный клик снимает его. Когда запрос получает статус "Shipped" или "Declined", голосование по нему закрывается, но те, кто уже проголосовал, всё ещё могут забрать свой голос. Голоса это сигнал, а не подсчёт людей: если очистить хранилище браузера или открыть приватное окно, можно проголосовать снова, поэтому пользуйтесь ими, чтобы понять, что людям важно, и не принимайте по ним значимых решений. Счётчики, которые видят другие посетители, могут немного отставать, а проголосовавший сразу видит точное новое число.
Голосование сохраняет в localStorage посетителя две вещи, но никогда не в cookie. В changelogapp-widget:votes: с добавленным ID вашего фида лежит список запросов, за которые проголосовали в этом браузере, не более 200 последних. changelogapp-widget:reader-id это случайный ID, который используют и реакции, по одному на браузер и источник сайта, поэтому если посетитель уже реагировал, голосование ничего нового не создаёт. Мы храним только хеш этого ID вместе с вашей командой, а сам ID не храним, поэтому один и тот же браузер оставляет несвязанные хеши в двух разных changelog. IP-адрес посетителя вместе с голосом мы не сохраняем. Если браузер блокирует хранилище, голосование продолжает работать в рамках текущего просмотра страницы, но потом не запоминается.
Во всплывающей карточке релиза доска не появляется никогда, как и в виджете с ограничением через data-repos, потому что доска охватывает всю вашу команду. На размещённой у нас странице changelog есть вкладка "Requests" с той же доской, фильтром по статусу и голосами, которые считаются так же. Доска доступна и как публичный JSON по адресу GET /v1/public/YOUR_PUBLIC_ID/board.json на том же API, и пока доска выключена, он отвечает 404.
Чтобы стилизовать доску, используйте ::part(board) для всего блока и ::part(board-heading) для её заголовка, а также части каждого запроса, все они перечислены ниже в разделе Стилизация. Кнопка голоса ::part(board-vote) получает aria-pressed="true", когда этот браузер уже проголосовал, и тогда рисуется с обводкой цвета вашего --changelogapp-accent. ::part() не умеет выбирать по этому атрибуту, поэтому чтобы изменить вид учтённого голоса, задайте --changelogapp-accent.
Стилизация
Виджет рендерится в shadow root, поэтому большая часть вашей таблицы стилей до него не доходит. Наследуемые свойства всё же проходят внутрь там, где виджет не задаёт свои, как и перечисленные ниже CSS-переменные, заданные на элементе или на его предке. Для всего остального используйте имена ::part() ниже. Оба списка составляют стабильный интерфейс: однажды выпущенное имя больше никогда не переименовывается.
CSS-переменные
--changelogapp-font-family--changelogapp-text--changelogapp-text-muted--changelogapp-bg--changelogapp-border--changelogapp-accent--changelogapp-radius--changelogapp-space--changelogapp-timeline-line--changelogapp-pill-bg--changelogapp-pill-text
Плашки тегов. Тег с цветом использует его как фон, и в обеих темах цвет текста подбирается так, чтобы читаться на этом фоне, с контрастом 4.5:1 или выше. Белый предпочтителен, если он достигает этого порога. Цвет, который виджет не может прочитать как сплошное значение RGB, не получает подобранного цвета текста и сохраняет значение темы по умолчанию. Чтобы выбрать цвет текста самостоятельно, в любой из тем, задайте --changelogapp-pill-text. Правило ::part(entry-tag) побеждает всё остальное, поэтому если вы задаёте там фон, задайте и color. Переменная --changelogapp-pill-bg задаёт фон тега, у которого нет цвета. Зафиксированные сборки до /widget-v18.js включительно сохраняют белый текст плашек в светлой теме.
Части
- Записи changelog:
month-heading,entry,entry-date,entry-tag,entry-title,entry-body,entry-link,timeline-dot,entry-image,entry-header-image - Внутри тела записи:
entry-body-heading,entry-body-paragraph,entry-body-list,entry-body-list-item,entry-body-link,entry-body-code - Счётчик непрочитанного на вкладке Updates:
unread-badge - Всплывающая карточка релиза:
popup,popup-heading,popup-close,popup-link - Форма "Get updates by email" вверху вкладки Updates, когда включены подписчики по email (план Team):
subscribe,subscribe-heading,subscribe-input,subscribe-button,subscribe-status - Эмодзи-реакции, когда они включены:
reactions,reaction,reaction-count - Публичная доска пожеланий, когда она включена:
board,board-heading,board-request,board-request-title,board-request-description,board-request-status,board-request-link,board-vote,board-vote-count
Content-Security-Policy
Если ваш сайт отправляет заголовок Content-Security-Policy, виджету нужен источник API в двух директивах. script-src позволяет загрузить скрипт. connect-src позволяет читать ваш changelog, отправлять отзывы и фиксировать просмотры. Если указана только первая, элемент появляется и остаётся пустым, что выглядит как сломанный фид, а не как заблокированный запрос. Всплывающей карточке нужны те же две.
script-src https://api.changeloop.dev; connect-src https://api.changeloop.dev;Начиная с виджета 0.16.0, который отдаёт /widget.js, современным браузерам не нужно менять style-src: виджет передаёт свои стили как сконструированную таблицу стилей, которой style-src не управляет. Более старые сборки, включая зафиксированные до /widget-v18.js, и браузеры без поддержки конструируемых таблиц стилей используют элемент style, которому нужен style-src 'unsafe-inline'.
img-src нужен, только если вы включили изображения в приложении, в Настройках, раздел Публичный фид, блок Изображения. Тогда виджет загружает картинки напрямую с ваших хостов изображений, и политика, в которой их нет, блокирует каждую. В Настройках показана точная строка с img-src, заполненным по вашему списку, поэтому копируйте её заново после каждого изменения списка. Для хостов скриншотов GitHub в img-src также нужен https://github-production-user-asset-6210df.s3.amazonaws.com, потому что ссылка на скриншот GitHub перенаправляет туда, и браузер проверяет и этот адрес.
Если в вашей политике задан только default-src, добавьте обе директивы и повторите в каждой источники из default-src. Директива script-src или connect-src заменяет default-src для скриптов или соединений, поэтому если не указать свои источники, они будут заблокированы.
Добавляйте источник в существующие директивы, а не заменяйте их. В приложении, в Настройках, раздел Публичный фид, эта строка показана с правильным источником для вашего аккаунта. Если вы не отправляете этот заголовок, делать ничего не нужно.
Размещённая страница фида
Мы также размещаем простую страницу по этому адресу: ваш changelog и вашу доску roadmap, отрендеренные из тех же двух фидов выше. Не требует входа и ничего настроенного с вашей стороны. Это также место, куда мы возвращаем людей, когда цикл замыкается: комментарий Shipped, который мы оставляем на issue GitHub, ссылается сюда, как и shippedEntry.link из поиска отправки выше, оба приводят к доставленной записи с её собственной якорной ссылкой #entry-ID, которая всё ещё находит запись, даже если она с тех пор переместилась на более позднюю страницу.
Относитесь к этому как к резервному варианту, а не к интеграции. Фид changelog и виджет остаются способом разместить это на вашем собственном сайте, чтобы это выглядело как ваш продукт, а не наш; эта страница для случаев, когда вы этого ещё не сделали, и для ссылок замыкания цикла, которые указывают сюда независимо от того, что ещё вы построили.
Ваш changelog внутри вашего продукта
Changeloop составляет каждую запись из слитого pull request, держит её до вашей проверки и отдаёт этому виджету и JSON-ленте. Бесплатно для одного репозитория, без карты.
Начать бесплатно