Vložitelný widget
Pokud raději nic nestavíš, vlož tyto dva řádky. Widget je custom element vykreslující se do shadow rootu, takže nedědí tvé styly ani do nich neprosakuje.
<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 atributy jsou povinné. data-public-id je ID tvého feedu, data-api je origin, ze kterého widget načítá data. Pokud některý chybí, element zapíše chybu do konzole a nic nevykreslí, což je první věc, kterou zkontroluj, pokud vidíš prázdné místo tam, kde by měl widget být.
Přidej k elementu data-theme="dark" pro tmavé vykreslení; tvá stránka to může přepínat za běhu. Pro hlubší stylování widget nabízí CSS vlastní proměnné (--changelogapp-text, --changelogapp-bg, --changelogapp-accent a další) a názvy ::part(), které nastavíš ve vlastním stylu. Aplikace zobrazuje živý náhled obou motivů v Nastavení, sekce Veřejný feed.
Přidejte data-repos, pokud chcete zobrazit jen některé repozitáře, například changelog jednoho produktu na webu tohoto produktu, když jeden účet sdílí více produktů. Hodnota je seznam plných názvů owner/repo oddělených čárkou; samotný název bez vlastníka nic neodpovídá a vykreslí prázdný kanál bez chyby. Zohlední se nejvýše deset repozitářů. Takto omezený widget zobrazuje jen záložky Updates a Feedback, protože roadmapa nemá pohled podle repozitáře, a zpětná vazba se stále zakládá tam, kam míří cíl zpětné vazby vašeho týmu. V Nastavení, Veřejný kanál je výběr, který atribut napíše za vás.
Vykresluje tři karty v tomto pořadí: Updates, Roadmap a Feedback. První dvě čtou feedy výše. Třetí odesílá na endpoint níže a uchovává ID každého odeslání v localStorage, takže se návštěvník může vrátit a zjistit, co se stalo s tím, co odeslal.
Skript je poskytován verzovaně. /widget.js vždy poskytuje nejnovější build a je uložen v mezipaměti na hodinu, takže vydání se dostane k tvým návštěvníkům bez toho, aniž bys čeho ses dotkl. /widget-vN.js připíná jeden build: jakmile bylo číslo verze poskytnuto, jeho byty se už nikdy nezmění, a je uložen v mezipaměti na rok. Připni ho, pokud raději přijímáš změny záměrně.
Načti přesně jeden skript widgetu na stránku
Dvě URL jsou alternativy, ne vrstvy. Obě registrují stejný název custom elementu a prohlížeč umožňuje zaregistrovat název pouze jednou na dokument: který skript se spustí jako první, ten vyhraje po dobu životnosti stránky, a druhý se stane neaktivním. Takže stránka nesoucí jak /widget.js, tak /widget-v5.js vykresluje ten, který prohlížeč spustil jako první, což není něco, co ovládáš, a přidání /widget-v5.js vedle existujícího /widget.js pro připnutí verze nedělá nic.
Když se to stane, widget zapíše varování do konzole s uvedením obou buildů, takže nezůstaneš hádat. Nemůže udělat víc než varovat: než se spustí druhá kopie, první si už nárokovala název. Oprava je vždy nahradit tag skriptu místo přidání dalšího, a totéž platí, pokud ho za tebe vloží správce tagů nebo fragment. Chceš-li přejít z průběžného buildu na připnutý, změň src.
Vyskakovací okno s novým vydáním
Přidej data-mode="popup" a element nevykreslí žádné karty. Když má návštěvník co nového vidět, zobrazí jednu malou kartu s tvým nejnovějším vydáním, jinak nezobrazí vůbec nic. U data-mode nezáleží na velikosti písmen.
<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 širokých obrazovkách je karta v levém dolním rohu, protože pravý dolní roh obvykle patří chatovacímu tlačítku. Na obrazovkách užších než 480px se roztáhne na celou šířku a chatovací tlačítko překryje, dokud ji nezavřeš. Otevírá se ve vrchní vrstvě prohlížeče, takže ji overflow, transform ani z-index nadřazeného elementu neořízne ani nezakryje. Chceš-li ji přesunout, nastyluj ::part(popup).
Každé vydání se zobrazí jednou. Karta se objeví, když má návštěvník záznamy, které ještě neviděl. Ukáže nejnovější z nich, při více záznamech i jejich počet, a v okamžiku zobrazení je počítá jako viděné. Další načtení stránky neukáže nic, dokud nepublikuješ znovu.
První návštěva nezobrazí vůbec nic: widget si jen poznamená, kam až tvůj changelog sahá, takže stávající uživatele v den zapnutí nepřivítají staré novinky. Karta začne s tvým dalším vydáním. Návštěvník, který už vydání přečetl v inline widgetu, ho znovu neuvidí.
To, co návštěvník už viděl, se ukládá do localStorage, ne do cookie, takže to patří jednomu prohlížeči a jednomu originu webu. Stejný člověk na jiné z tvých domén začne znovu od první návštěvy. Pokud prohlížeč ukládání blokuje, každá návštěva se počítá jako první a karta se nikdy nezobrazí.
data-changelog-url je volitelný. Pokud je to adresa http nebo https, karta dostane odkaz "See all updates", který na ni vede, obvykle na tvou hostovanou stránku nebo vlastní stránku changelogu. U čehokoliv jiného se žádný odkaz nevykreslí. data-theme a data-repos fungují úplně stejně jako u inline widgetu.
Karta nikdy nezíská fokus a nikdy neblokuje stránku: je to popsaná oblast, ne dialog. Zavře se tlačítkem pro zavření, nebo klávesou Escape, když je fokus uvnitř karty. Escape kdekoliv jinde na tvé stránce zůstává tvému vlastnímu kódu.
Pravidlo jednoho skriptu widgetu na stránku platí dál. Vyskakovací okno a inline widget mohou sdílet stránku: načti skript jednou a přidej oba elementy, a shodnou se na tom, co už návštěvník viděl.
Připnuté buildy do /widget-v18.js jsou starší než vyskakovací okno. Ignorují data-mode a místo něj vykreslí inline karty, takže použij /widget.js nebo novější připnutý build.
V aplikaci najdeš v Nastavení, sekce Veřejný feed, tento úryvek připravený ke zkopírování, s vyplněným ID feedu, motivem a rozsahem repozitářů. Zobrazení karty a kliknutí na její odkaz "Learn more" najdeš v Analytice jako samostatná čísla.
Emoji reakce
Čtenáři mohou na záznam zareagovat, aniž by cokoliv psali. Když jsou reakce zapnuté, každý záznam končí řadou pěti emoji, 👍 🎉 ❤️ 🚀 👀, každé s vlastním počtem. Řada se zobrazuje v inline widgetu, na kartě vyskakovacího okna s novým vydáním i na hostované stránce feedu.
Reakce jsou vypnuté, dokud je nezapneš v aplikaci v Nastavení, sekce Veřejný feed. Kód pro vložení se nemění: widget čte přepínač z tvého feedu, takže řada se objeví a zmizí spolu s ním. Když reakce vypneš, řada se skryje, ale počty zůstanou, takže se vrátí, jakmile je zase zapneš. Připnuté buildy z doby před reakcemi řadu nikdy nezobrazí.
Každý čtenář může dát záznamu každou reakci jednou a dalším stisknutím ji vezme zpět. Widget rozpozná čtenáře podle náhodného ID, které při prvním kliknutí vytvoří v prohlížeči, ne podle účtu ani e-mailové adresy. Ukládáme jen hash tohoto ID spojeného s tvým týmem, takže stejný prohlížeč zanechá na dvou různých changelozích nesouvisející hashe.
Počty jsou orientační: přátelský signál, ne hlasování. Po vymazání úložiště prohlížeče nebo v anonymním okně může někdo zareagovat znovu, takže na nich nikdy nezakládej důležitá rozhodnutí. Počty ve tvém feedu mohou také o několik minut zaostávat, protože feed je v cache, ale ten, kdo klikne, vidí svou reakci započítanou okamžitě. V aplikaci ukazuje součet každého záznamu karta Published v inboxu.
Reakce uloží do localStorage návštěvníka dvě věci, nikdy do cookie. changelogapp-widget:reader-id obsahuje náhodné ID, jedno na prohlížeč a origin webu. changelogapp-widget:reactions: následované ID tvého feedu obsahuje reakce, které tento prohlížeč zvolil, nejvýše u 200 záznamů, těch, na které reagoval naposledy. Hostovaná stránka drží stejné dvě položky pod vlastní adresou. Pokud prohlížeč ukládání blokuje, reagování na dané zobrazení stránky stále funguje, ale po něm se nezapamatuje.
Řadu nastyluješ pomocí ::part(reactions), ::part(reaction) pro každé tlačítko a ::part(reaction-count) pro jeho číslo, vše uvedené níže v části Stylování. Nulový počet nezobrazí žádné číslo. Stisknuté tlačítko má aria-pressed="true" a je vykresleno s kroužkem v barvě --changelogapp-accent a tučným textem. ::part() nedokáže vybírat podle tohoto atributu, takže vzhled stisknutého tlačítka změníš nastavením --changelogapp-accent.
Veřejná tabule zpětné vazby
Tabule umožňuje čtenářům vidět, co si chtějí ostatní, a hlasovat pro to. Když je tabule zapnutá, karta Feedback se otevře s nejvíce hlasovanými požadavky, každým s jeho stavem, a pod nimi je obvyklý formulář.
Tabule je vypnutá, dokud ji nezapneš v aplikaci v Nastavení, sekce Veřejný feed. Kód pro vložení se nemění: widget čte přepínač z tvého feedu. Když tabuli vypneš, skryje se, ale požadavky a jejich hlasy zůstanou. Je součástí karty Feedback, takže widget, který kartu Feedback nezobrazuje, nezobrazuje ani tabuli.
Tabule ukazuje jen to, co napíšeš ty. Zpětná vazba návštěvníka se na ni nikdy nedostane sama: o tom, které požadavky na tabuli budou, rozhoduješ ty a název i popis každého píšeš sám na stránce Feedback board v aplikaci. Požadavek můžeš založit ze zprávy, kterou návštěvník poslal, nebo přidat vlastní nápad. Tabule nikdy neukazuje zprávu ani e-mailovou adresu návštěvníka. Tabule zobrazuje tvých 100 nejlepších požadavků a tým jich může mít až 500.
Každý požadavek má jeden z pěti stavů: Under consideration, Planned, In progress, Shipped nebo Declined. Propoj požadavek se záznamem a on se sám přesune do stavu Shipped, jakmile je tento záznam publikován, nebo hned, pokud už publikován je. Požadavek založený ze zprávy návštěvníka se do stavu Shipped přesune také ve chvíli, kdy je publikován záznam, který tuto zprávu vyřešil.
Každý prohlížeč má na každém webu jeden hlas na požadavek a dalším kliknutím ho vezme zpět. Hlasování se uzavře, jakmile je požadavek ve stavu Shipped nebo Declined, ale kdo už hlasoval, může svůj hlas stále vzít zpět. Hlasy jsou signál, ne sčítání lidí: po vymazání úložiště prohlížeče nebo v anonymním okně může někdo hlasovat znovu, takže podle nich zjišťuj, co lidi zajímá, a nikdy s nimi nerozhoduj o ničem důležitém. Počty, které vidí ostatní návštěvníci, mohou trochu zaostávat, zatímco ten, kdo hlasuje, vidí přesný nový počet okamžitě.
Hlasování uloží do localStorage návštěvníka dvě věci, nikdy do cookie. changelogapp-widget:votes: následované ID tvého feedu obsahuje požadavky, pro které tento prohlížeč hlasoval, nejvýše 200 posledních. changelogapp-widget:reader-id je náhodné ID, které používají i reakce, jedno na prohlížeč a origin webu, takže hlasování nevytvoří nic nového, pokud už návštěvník reagoval. Ukládáme jen hash tohoto ID spojeného s tvým týmem, nikdy samotné ID, takže stejný prohlížeč zanechá na dvou různých changelozích nesouvisející hashe. S hlasem neukládáme IP adresu návštěvníka. Pokud prohlížeč ukládání blokuje, hlasování na dané zobrazení stránky stále funguje, ale po něm se nezapamatuje.
Tabule se nikdy nezobrazí ve vyskakovacím okně s novým vydáním a ani ve widgetu omezeném atributem data-repos, protože zahrnuje celý tvůj tým. Tvoje hostovaná stránka má kartu Requests se stejnou tabulí, filtrem podle stavu a hlasy, které se počítají stejně. Tabule je také veřejný JSON na GET /v1/public/YOUR_PUBLIC_ID/board.json na stejném API, který odpovídá 404, dokud je tabule vypnutá.
Tabuli nastyluješ pomocí ::part(board) pro celý blok a ::part(board-heading) pro její nadpis, dále pomocí částí jednotlivých požadavků, všech uvedených níže v části Stylování. Tlačítko hlasování, ::part(board-vote), má aria-pressed="true", jakmile tento prohlížeč hlasoval, a je pak vykresleno s kroužkem v barvě --changelogapp-accent. ::part() nedokáže vybírat podle tohoto atributu, takže vzhled započítaného hlasu změníš nastavením --changelogapp-accent.
Stylování
Widget se vykresluje do shadow rootu, takže většina tvých stylů do něj nezasáhne. Zděděné vlastnosti dovnitř stále proniknou tam, kde widget nemá vlastní, stejně jako níže uvedené CSS vlastní proměnné nastavené na elementu nebo na jeho předkovi. Pro cokoliv dalšího použij níže uvedené názvy ::part(). Oba seznamy jsou stabilní rozhraní: jakmile je název vydán, nikdy se nepřejmenuje.
CSS vlastní proměnné
--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
Štítky tagů. Tag s barvou ji používá jako pozadí a v obou motivech se barva textu volí tak, aby byla na tomto pozadí čitelná, s kontrastem 4.5:1 nebo lepším. Bílá má přednost, kdykoliv tohoto kontrastu dosáhne. Barva, kterou widget neumí přečíst jako plnou hodnotu RGB, nedostane vybranou barvu textu a ponechá výchozí barvu motivu. Chceš-li barvu textu zvolit sám, v kterémkoliv motivu, nastav --changelogapp-pill-text. Pravidlo ::part(entry-tag) má přednost před vším, takže pokud tam nastavíš pozadí, nastav i color. --changelogapp-pill-bg je pozadí tagu, který barvu nemá. Připnuté buildy do /widget-v18.js ponechávají ve světlém motivu bílý text štítků.
Části (parts)
- Záznamy changelogu:
month-heading,entry,entry-date,entry-tag,entry-title,entry-body,entry-link,timeline-dot,entry-image,entry-header-image - Uvnitř těla záznamu:
entry-body-heading,entry-body-paragraph,entry-body-list,entry-body-list-item,entry-body-link,entry-body-code - Počet nepřečtených na kartě Updates:
unread-badge - Vyskakovací okno s novým vydáním:
popup,popup-heading,popup-close,popup-link - Formulář "Get updates by email" nahoře na kartě Updates, když jsou zapnuti odběratelé e-mailem (plán Team):
subscribe,subscribe-heading,subscribe-input,subscribe-button,subscribe-status - Emoji reakce, když jsou zapnuté:
reactions,reaction,reaction-count - Veřejná tabule zpětné vazby, když je zapnutá:
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
Pokud tvůj web posílá hlavičku Content-Security-Policy, widget potřebuje origin API ve dvou direktivách. script-src umožní načíst skript. connect-src mu umožní číst tvůj changelog, odesílat zpětnou vazbu a zaznamenávat zobrazení. Pokud nastavíš jen první, element se objeví a zůstane prázdný, což vypadá jako rozbitý feed, ne jako zablokovaný požadavek. Vyskakovací okno potřebuje stejné dvě.
script-src https://api.changeloop.dev; connect-src https://api.changeloop.dev;Od widgetu 0.16.0, který poskytuje /widget.js, současné prohlížeče žádnou změnu style-src nepotřebují: widget předává své styly jako konstruovanou šablonu stylů, kterou style-src neřídí. Starší buildy, včetně připnutých buildů do /widget-v18.js, a prohlížeče bez podpory konstruovatelných šablon stylů místo toho používají element style, který vyžaduje style-src 'unsafe-inline'.
img-src potřebuješ jen tehdy, pokud jsi v aplikaci zapnul obrázky, v Nastavení, sekce Veřejný feed, část Obrázky. Widget pak načítá obrázky přímo z tvých hostitelů obrázků a politika, která je neuvádí, zablokuje každý z nich. Nastavení vypíše přesný řádek s img-src vyplněným podle tvého seznamu, takže ho zkopíruj znovu pokaždé, když seznam změníš. Hostitelé snímků obrazovky z GitHubu navíc potřebují v img-src https://github-production-user-asset-6210df.s3.amazonaws.com, protože odkaz na snímek obrazovky z GitHubu přesměrovává tam a prohlížeč kontroluje i tuto adresu.
Pokud tvoje politika nastavuje jen default-src, přidej obě direktivy a v každé zopakuj zdroje z default-src. Direktiva script-src nebo connect-src nahrazuje default-src pro skripty nebo spojení, takže vynechání tvých vlastních zdrojů by je zablokovalo.
Přidej origin ke stávajícím direktivám, nenahrazuj je. Nastavení, sekce Veřejný feed v aplikaci ukazuje tento řádek se správným originem pro tvůj účet. Pokud tuto hlavičku neposíláš, není co dělat.
Hostovaná stránka feedu
Na této adrese hostujeme i obyčejnou stránku: tvůj changelog a tvou tabuli roadmapy, vykreslené ze stejných dvou feedů výše. Nevyžaduje přihlášení ani nic nastaveného na tvé straně. Je to také místo, kam posíláme lidi zpět, jakmile se smyčka uzavře: komentář Shipped, který zanecháváme na issue na GitHubu, odkazuje sem, stejně jako shippedEntry.link z vyhledání odeslání výše, oba přistávají na doručeném záznamu s vlastní kotvou #entry-ID, která záznam najde, i když se mezitím přesunul na pozdější stránku.
Zacházej s ní jako se záložním řešením, ne integrací. Feed changelogu a widget zůstávají způsobem, jak to umístit na tvůj vlastní web, aby to vypadalo jako tvůj produkt, ne náš; tato stránka je pro případ, kdy jsi to ještě neudělal, a pro odkazy uzavírající smyčku, které sem míří bez ohledu na to, co jiného jsi postavil.
Tvůj changelog, uvnitř tvého produktu
Changeloop sepíše každý záznam ze sloučeného pull requestu, podrží ho ke tvé kontrole a předá ho tomuto widgetu a JSON kanálu. Zdarma pro jeden repozitář, bez karty.
Začít zdarma