Przejdź do treści

Cała dokumentacja dla deweloperów

Widżet changeloga do osadzenia

Dwie linie HTML umieszczają twój changelog, roadmapę i pole na feedback w twoim produkcie. Ta strona opisuje atrybuty, motywy, pokazywanie tylko niektórych repozytoriów, wersjonowanie i hostowaną stronę, na którą widżet się przełącza.

Osadzalny widget

Jeśli wolisz niczego nie budować, wklej te dwie linie. Widget to custom element renderowany w shadow root, więc ani nie dziedziczy Twoich stylów, ani do nich nie wycieka.

<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>

Oba atrybuty są wymagane. data-public-id to identyfikator Twojego feedu, data-api to pochodzenie, z którego widget pobiera dane. Jeśli brakuje któregokolwiek, element zapisuje błąd w konsoli i nic nie renderuje, co jest pierwszą rzeczą do sprawdzenia, jeśli widzisz puste miejsce tam, gdzie powinien być widget.

Dodaj do elementu data-theme="dark", by wyświetlał się w ciemnej wersji; Twoja strona może to przełączać w trakcie działania. Do głębszej stylizacji widget udostępnia własności CSS (--changelogapp-text, --changelogapp-bg, --changelogapp-accent i inne) oraz nazwy ::part(), które ustawiasz we własnym arkuszu stylów. Aplikacja pokazuje podgląd obu motywów na żywo w Ustawieniach, sekcja Publiczny feed.

Dodaj data-repos, aby pokazać tylko część swoich repozytoriów, na przykład changelog jednego produktu na stronie tego produktu, gdy kilka produktów dzieli jedno konto. Wartość to lista pełnych nazw owner/repo rozdzielonych przecinkami; sama nazwa bez właściciela do niczego nie pasuje i wyświetla pusty kanał bez błędu. Uwzględnianych jest najwyżej dziesięć repozytoriów. Tak zawężony widżet pokazuje tylko zakładki Updates i Feedback, bo roadmapa nie ma widoku per repozytorium, a opinie nadal trafiają tam, gdzie wskazuje cel opinii Twojego zespołu. W Ustawieniach, Publiczny kanał jest selektor, który wpisze ten atrybut za Ciebie.

Renderuje trzy zakładki w tej kolejności: Updates, Roadmap i Feedback. Pierwsze dwie czytają powyższe feedy. Trzecia wysyła do poniższego endpointu i zapisuje identyfikator każdego zgłoszenia w localStorage, więc odwiedzający może wrócić i zobaczyć, co się stało z tym, co wysłał.

Skrypt jest serwowany z wersjonowaniem. /widget.js zawsze serwuje najnowszy build i jest cachowany przez godzinę, więc wydanie dociera do Twoich odwiedzających bez dotykania czegokolwiek. /widget-vN.js przypina jeden build: gdy numer wersji zostanie już zaserwowany, jego bajty nigdy się nie zmieniają, i jest cachowany przez rok. Przypnij, jeśli wolisz celowo przyjmować zmiany.

Wczytaj dokładnie jeden skrypt widgetu na stronę

Oba adresy URL to alternatywy, nie warstwy. Oba rejestrują tę samą nazwę custom elementu, a przeglądarka pozwala zarejestrować nazwę tylko raz na dokument: ten, który wykona się pierwszy, wygrywa na czas życia strony, a drugi staje się nieaktywny. Więc strona z /widget.js i /widget-v5.js renderuje ten, który przeglądarka wykonała pierwszy, co nie jest czymś, co kontrolujesz, a dodanie /widget-v5.js obok istniejącego /widget.js, by przypiąć wersję, nic nie robi.

Gdy tak się dzieje, widget zapisuje w konsoli ostrzeżenie z nazwami obu buildów, więc nie zostajesz z zgadywaniem. Nie może zrobić nic więcej niż ostrzec: gdy druga kopia się wykonuje, pierwsza już zarezerwowała nazwę. Poprawką jest zawsze zastąpienie tagu skryptu zamiast dodawania kolejnego, i to samo dotyczy sytuacji, gdy menedżer tagów lub fragment wstawi go za Ciebie. Aby przejść z buildu ciągłego na przypięty, zmień src.

Wyskakująca karta wydania

Dodaj data-mode="popup", a element nie wyświetli żadnych zakładek. Gdy odwiedzający ma coś nowego do zobaczenia, pokazuje jedną małą kartę z Twoim najnowszym wydaniem, a w przeciwnym razie nie pokazuje nic. data-mode nie rozróżnia wielkości liter.

<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>

Na szerokich ekranach karta pojawia się w lewym dolnym rogu, bo prawy dolny zwykle zajmuje launcher czatu. Na ekranach węższych niż 480px zajmuje całą szerokość i zasłania launcher czatu, dopóki jej nie zamkniesz. Otwiera się w górnej warstwie przeglądarki, więc overflow, transform ani z-index elementu nadrzędnego nie mogą jej przyciąć ani przykryć. Aby ją przesunąć, ostyluj ::part(popup).

Każde wydanie jest pokazywane jeden raz. Karta pojawia się, gdy odwiedzający ma wpisy, których jeszcze nie widział. Pokazuje najnowszy z nich, z licznikiem, gdy jest ich kilka, i w chwili wyświetlenia uznaje je za zobaczone. Następne wczytanie strony nie pokaże nic, dopóki nie opublikujesz czegoś nowego.

Pierwsza wizyta nie pokazuje nic: widget jedynie zapamiętuje, dokąd sięga Twój changelog, żeby obecni użytkownicy nie witali się ze starymi wiadomościami w dniu, w którym go dodasz. Karta zaczyna działać od Twojego następnego wydania. Odwiedzający, który przeczytał wydanie w widgecie osadzonym na stronie, nie zobaczy go ponownie.

To, co odwiedzający już widział, jest przechowywane w localStorage, a nie w ciasteczku, więc dotyczy jednej przeglądarki i jednego pochodzenia witryny. Ta sama osoba na innej z Twoich domen zaczyna od pierwszej wizyty. Jeśli przeglądarka blokuje pamięć, każda wizyta liczy się jako pierwsza i karta nigdy się nie pokazuje.

data-changelog-url jest opcjonalny. Przy adresie http lub https karta dostaje link See all updates do niego, zwykle do Twojej hostowanej strony lub własnej strony z changelogiem. Przy czymkolwiek innym link nie jest rysowany. data-theme i data-repos działają dokładnie tak samo jak w widgecie osadzonym na stronie.

Karta nigdy nie przejmuje fokusu i nigdy nie blokuje strony: to oznaczony region, a nie okno dialogowe. Zamyka się przyciskiem zamknięcia albo klawiszem Escape, gdy fokus jest wewnątrz karty. Escape w dowolnym innym miejscu Twojej strony zostaje dla Twojego własnego kodu.

Zasada jednego skryptu widgetu na stronę nadal obowiązuje. Karta i widget osadzony na stronie mogą współistnieć: załaduj skrypt raz i dodaj oba elementy, a będą zgodne co do tego, co odwiedzający już widział.

Przypięte buildy do /widget-v18.js włącznie są starsze niż karta. Ignorują data-mode i zamiast niej renderują zakładki, więc użyj /widget.js albo nowszego przypiętego builda.

W aplikacji, w Ustawieniach, sekcja Publiczny feed, jest ten fragment gotowy do skopiowania, z Twoim identyfikatorem feedu, motywem i zakresem repozytoriów. Wyświetlenia karty i kliknięcia jej linku Learn more pojawiają się w Analytics jako osobne liczby.

Reakcje emoji

Czytelnicy mogą zareagować na wpis, nie pisząc nic. Gdy reakcje są włączone, każdy wpis kończy się rzędem pięciu emoji, 👍 🎉 ❤️ 🚀 👀, każde z własnym licznikiem. Rząd pojawia się w widgecie osadzonym na stronie, na wyskakującej karcie wydania i na hostowanej stronie feedu.

Reakcje są wyłączone, dopóki nie włączysz ich w aplikacji, w Ustawieniach, sekcja Publiczny feed. Twój kod osadzenia się nie zmienia: widget odczytuje przełącznik z Twojego feedu, więc rząd pojawia się i znika razem z nim. Wyłączenie reakcji ukrywa rząd, ale zachowuje liczniki, więc wracają, gdy włączysz je ponownie. Przypięte buildy sprzed reakcji nigdy nie pokazują tego rzędu.

Każdy czytelnik może dać wpisowi każdą reakcję raz, a ponowne kliknięcie ją cofa. Widget rozróżnia czytelników po losowym identyfikatorze, który tworzy w przeglądarce przy pierwszym kliknięciu, a nie po koncie ani adresie e-mail. Przechowujemy tylko hash tego identyfikatora połączony z Twoim zespołem, więc ta sama przeglądarka zostawia niepowiązane ze sobą hashe na dwóch różnych changelogach.

Liczniki są orientacyjne: to przyjazny sygnał, a nie głosowanie. Wyczyszczenie pamięci przeglądarki albo otwarcie okna prywatnego pozwala zareagować ponownie, więc nigdy nie opieraj na nich ważnej decyzji. Liczniki w Twoim feedzie mogą też spóźniać się o kilka minut, bo feed jest buforowany, ale osoba, która klika, od razu widzi swoją reakcję doliczoną. W aplikacji zakładka Published w skrzynce recenzji pokazuje sumę dla każdego wpisu.

Reagowanie zapisuje w localStorage odwiedzającego dwie rzeczy, nigdy w ciasteczku. changelogapp-widget:reader-id przechowuje losowy identyfikator, jeden na przeglądarkę i pochodzenie witryny. changelogapp-widget:reactions: z doklejonym identyfikatorem Twojego feedu przechowuje reakcje wybrane w tej przeglądarce, dla maksymalnie 200 wpisów, czyli tych, na które zareagowano ostatnio. Hostowana strona zapisuje te same dwie rzeczy pod własnym adresem. Jeśli przeglądarka blokuje pamięć, reagowanie nadal działa w trakcie tego wyświetlenia strony, ale nie jest potem zapamiętywane.

Aby ostylować rząd, użyj ::part(reactions), ::part(reaction) dla każdego przycisku i ::part(reaction-count) dla jego liczby, wszystkie wymienione niżej w sekcji Stylizacja. Licznik równy zero nie pokazuje liczby. Wciśnięty przycisk ma aria-pressed="true" i jest rysowany z obwódką w kolorze --changelogapp-accent oraz pogrubionym tekstem. ::part() nie potrafi wybierać po tym atrybucie, więc aby zmienić wygląd wciśniętego przycisku, ustaw --changelogapp-accent.

Publiczna tablica opinii

Tablica pozwala czytelnikom zobaczyć, o co proszą inni, i na to zagłosować. Gdy tablica jest włączona, zakładka Feedback otwiera się Twoimi najczęściej wybieranymi prośbami, każdą z jej statusem, a zwykły formularz znajduje się pod nimi.

Tablica jest wyłączona, dopóki nie włączysz jej w aplikacji, w Ustawieniach, sekcja Publiczny feed. Twój kod osadzenia się nie zmienia: widget odczytuje przełącznik z Twojego feedu. Wyłączenie tablicy ukrywa ją, ale zachowuje Twoje prośby i ich głosy. Tablica mieszka w zakładce Feedback, więc widget bez zakładki Feedback nie pokazuje też tablicy.

Tablica pokazuje tylko to, co sam napiszesz. Opinia odwiedzającego nigdy nie trafia na nią automatycznie: to Ty decydujesz, które prośby się na niej znajdą, i sam piszesz tytuł oraz opis każdej z nich, na stronie Feedback board w aplikacji. Możesz założyć prośbę na podstawie wiadomości od odwiedzającego albo dodać własny pomysł, a tablica nigdy nie pokazuje wiadomości ani adresu e-mail odwiedzającego. Tablica pokazuje Twoje 100 najpopularniejszych próśb, a zespół może mieć ich do 500.

Każda prośba ma jeden z pięciu statusów: Rozważana, Zaplanowana, W toku, Dostarczona albo Odrzucona. Powiąż prośbę z wpisem, a przejdzie na Dostarczona sama, gdy ten wpis zostanie opublikowany, albo od razu, jeśli już jest opublikowany. Prośba założona z wiadomości odwiedzającego też przechodzi na Dostarczona, gdy opublikujesz wpis realizujący tę wiadomość.

Każda przeglądarka ma jeden głos na prośbę w każdej witrynie, a ponowne kliknięcie go cofa. Głosowanie kończy się, gdy prośba jest Dostarczona lub Odrzucona, choć każdy, kto już zagłosował, nadal może swój głos cofnąć. Głosy są sygnałem, a nie spisem ludności: wyczyszczenie pamięci przeglądarki albo otwarcie okna prywatnego pozwala zagłosować ponownie, więc używaj ich, by zobaczyć, na czym ludziom zależy, a nigdy do rozstrzygania ważnej decyzji. Liczby widziane przez innych odwiedzających mogą się nieco spóźniać, a odwiedzający, który głosuje, widzi dokładną nową liczbę.

Głosowanie zapisuje w localStorage odwiedzającego dwie rzeczy, nigdy w ciasteczku. changelogapp-widget:votes: z doklejonym identyfikatorem Twojego feedu wymienia prośby, na które ta przeglądarka zagłosowała, do 200 ostatnich. changelogapp-widget:reader-id to losowy identyfikator używany przez reakcje, jeden na przeglądarkę i pochodzenie witryny, więc głosowanie nie tworzy niczego nowego, jeśli odwiedzający już zareagował. Przechowujemy tylko hash tego identyfikatora połączony z Twoim zespołem, nigdy sam identyfikator, więc ta sama przeglądarka zostawia niepowiązane ze sobą hashe na dwóch różnych changelogach. Nie zapisujemy przy głosie adresu IP odwiedzającego. Jeśli przeglądarka blokuje pamięć, głosowanie nadal działa w trakcie tego wyświetlenia strony, ale nie jest potem zapamiętywane.

Tablica nigdy nie pojawia się na wyskakującej karcie wydania ani w widgecie ograniczonym przez data-repos, bo obejmuje cały Twój zespół. Twoja hostowana strona changeloga ma zakładkę Requests z tą samą tablicą, filtrem po statusie i głosami liczonymi tak samo. Tablica jest też publicznym JSON-em, pod GET /v1/public/YOUR_PUBLIC_ID/board.json w tym samym API, które odpowiada 404, gdy tablica jest wyłączona.

Aby ostylować tablicę, użyj ::part(board) dla całego bloku i ::part(board-heading) dla jego nagłówka, a potem części każdej prośby, wszystkie wymienione niżej w sekcji Stylizacja. Przycisk głosowania, ::part(board-vote), ma aria-pressed="true", gdy ta przeglądarka już zagłosowała, i jest wtedy rysowany z obwódką w kolorze --changelogapp-accent. ::part() nie potrafi wybierać po tym atrybucie, więc aby zmienić wygląd policzonego głosu, ustaw --changelogapp-accent.

Stylizacja

Widget renderuje się w shadow root, więc większość Twojego arkusza stylów nie sięga do środka. Właściwości dziedziczone nadal przenikają tam, gdzie widget nie ustawia własnych, tak samo jak własności CSS poniżej, ustawione na elemencie albo na jego przodku. Do wszystkiego innego użyj nazw ::part() poniżej. Obie listy są stabilnym interfejsem: raz wydana nazwa nigdy nie zostaje zmieniona.

Własności 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

Plakietki tagów. Tag z kolorem używa go jako tła, a w obu motywach kolor tekstu jest dobierany tak, by był czytelny na tym tle, w proporcji 4.5:1 lub lepszej. Biały jest preferowany, ilekroć ją osiąga. Kolor, którego widget nie potrafi odczytać jako jednolitej wartości RGB, nie dostaje dobranego koloru tekstu i zachowuje domyślny z motywu. Aby samodzielnie wybrać kolor tekstu, w dowolnym motywie, ustaw --changelogapp-pill-text. Reguła ::part(entry-tag) wygrywa ze wszystkim, więc jeśli ustawiasz tam tło, ustaw też color. --changelogapp-pill-bg to tło tagu, który nie ma koloru. Przypięte buildy do /widget-v18.js włącznie zachowują biały tekst plakietek w jasnym motywie.

Części

  • Wpisy changelogu: month-heading, entry, entry-date, entry-tag, entry-title, entry-body, entry-link, timeline-dot, entry-image, entry-header-image
  • Wewnątrz treści wpisu: entry-body-heading, entry-body-paragraph, entry-body-list, entry-body-list-item, entry-body-link, entry-body-code
  • Licznik nieprzeczytanych na zakładce Updates: unread-badge
  • Wyskakująca karta wydania: popup, popup-heading, popup-close, popup-link
  • Formularz Get updates by email, na górze Updates, gdy subskrybenci e-mail są włączeni (plan Team): subscribe, subscribe-heading, subscribe-input, subscribe-button, subscribe-status
  • Reakcje emoji, gdy są włączone: reactions, reaction, reaction-count
  • Publiczna tablica opinii, gdy jest włączona: 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

Jeśli Twoja strona wysyła nagłówek Content-Security-Policy, widget potrzebuje pochodzenia API w dwóch dyrektywach. script-src pozwala załadować skrypt. connect-src pozwala mu odczytać Twój changelog, wysyłać opinie i rejestrować wyświetlenia. Przy samej pierwszej element się pojawia, a potem pozostaje pusty, co wygląda na zepsuty feed, a nie zablokowane żądanie. Karta wymaga tych samych dwóch.

script-src https://api.changeloop.dev; connect-src https://api.changeloop.dev;

Od widgetu 0.16.0, który serwuje /widget.js, obecne przeglądarki nie wymagają zmiany style-src: widget przekazuje swoje style jako skonstruowany arkusz, którego style-src nie obejmuje. Starsze buildy, w tym przypięte do /widget-v18.js, oraz przeglądarki bez konstruowalnych arkuszy używają zamiast tego elementu style, który wymaga style-src 'unsafe-inline'.

img-src jest potrzebne tylko wtedy, gdy włączyłeś obrazy w aplikacji, w Ustawieniach, sekcja Publiczny feed, Obrazy. Widget ładuje wtedy obrazy bezpośrednio z Twoich hostów obrazów, a polityka, która ich nie wymienia, blokuje każdy z nich. Ustawienia pokazują dokładną linię z img-src uzupełnionym na podstawie Twojej listy, więc skopiuj ją ponownie po każdej zmianie listy. Hosty zrzutów ekranu GitHuba wymagają też https://github-production-user-asset-6210df.s3.amazonaws.com w img-src, ponieważ link do zrzutu ekranu z GitHuba przekierowuje pod ten adres, a przeglądarka sprawdza również go.

Jeśli Twoja polityka ustawia tylko default-src, dodaj obie dyrektywy i powtórz źródła z default-src w każdej z nich. script-src lub connect-src zastępuje default-src dla skryptów lub połączeń, więc pominięcie własnych źródeł by je zablokowało.

Dodaj pochodzenie do istniejących dyrektyw, zamiast je zastępować. Ustawienia, sekcja Publiczny feed w aplikacji pokazuje tę linię z właściwym pochodzeniem dla Twojego konta. Jeśli nie wysyłasz tego nagłówka, nie musisz nic robić.

Hostowana strona feedu

Pod tym adresem hostujemy też zwykłą stronę: Twój changelog i tablicę roadmapy, renderowane z tych samych dwóch feedów powyżej. Nie wymaga logowania ani niczego skonfigurowanego po Twojej stronie. To także miejsce, do którego odsyłamy ludzi, gdy pętla się zamyka: komentarz Shipped, który zostawiamy na issue na GitHubie, prowadzi tutaj, podobnie jak shippedEntry.link z wyszukiwania zgłoszenia powyżej, oba lądują na dostarczonym wpisie z własną kotwicą #entry-ID, która nadal znajdzie wpis, nawet jeśli przeniósł się na późniejszą stronę.

Traktuj to jako rozwiązanie zapasowe, nie integrację. Feed changeloga i widget nadal są sposobem na umieszczenie tego na Twojej własnej stronie, by wyglądało jak Twój produkt, a nie nasz; ta strona jest dla sytuacji, gdy jeszcze tego nie zrobiłeś, i dla linków zamykających pętlę, które prowadzą tutaj niezależnie od tego, co jeszcze zbudowałeś.

Twój changelog, w twoim produkcie

Changeloop tworzy każdy wpis z połączonego pull requesta, zatrzymuje go do twojego przeglądu i podaje temu widżetowi oraz kanałowi JSON. Za darmo dla jednego repozytorium, bez karty.

Zacznij za darmo

Przeczytaj dokumentację dla deweloperów