Gömülebilir widget
Bir şey inşa etmek istemiyorsan bu iki satırı ekle. Widget, bir shadow root içine render eden bir custom element'tir, bu yüzden ne stillerini devralır ne de onlara sızar.
<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>
Her iki öznitelik de zorunludur. data-public-id akış kimliğindir, data-api widget'ın veri çektiği kaynaktır. İkisinden biri eksikse eleman konsola bir hata yazar ve hiçbir şey renderlamaz; orada bir şey görmen gerekirken boş bir alan görüyorsan kontrol edeceğin ilk şey budur.
Koyu görünüm için elemana data-theme="dark" ekle; sayfan bunu çalışma zamanında değiştirebilir. Daha derin bir stil için widget, kendi stil dosyanda ayarladığın CSS özel özelliklerini (--changelogapp-text, --changelogapp-bg, --changelogapp-accent ve daha fazlası) ve ::part() adlarını sunar. Uygulama her iki temayı Ayarlar, Herkese açık akış altında canlı olarak önizler.
Depolarınızın yalnızca bir kısmını göstermek için data-repos ekleyin; örneğin birden fazla ürün tek bir hesabı paylaşıyorsa, bir ürünün changelog'unu o ürünün sitesinde gösterebilirsiniz. Değer, virgülle ayrılmış owner/repo biçimindeki tam adların listesidir; sahibi olmayan bir ad hiçbir şeyle eşleşmez ve hata vermeden boş bir akış gösterir. En fazla on depo dikkate alınır. Bu şekilde daraltılmış bir widget yalnızca Updates ve Feedback sekmelerini gösterir, çünkü yol haritasının depo bazında bir görünümü yoktur; geri bildirim ise ekibinizin geri bildirim hedefinin gösterdiği yere kaydedilmeye devam eder. Ayarlar, Herkese açık akış altında bu özniteliği sizin için yazan bir seçici vardır.
Şu sırayla üç sekme render eder: Updates, Roadmap ve Feedback. İlk ikisi yukarıdaki akışları okur. Üçüncüsü aşağıdaki endpoint'e gönderir ve her gönderim kimliğini localStorage'da tutar, böylece bir ziyaretçi geri gelip gönderdiğine ne olduğunu görebilir.
Betik sürümlenmiş olarak sunulur. /widget.js her zaman en yeni build'i sunar ve bir saat önbelleğe alınır, böylece bir sürüm sana dokunmadan ziyaretçilerine ulaşır. /widget-vN.js bir build'i sabitler: bir sürüm numarası bir kez sunulduktan sonra byte'ları asla değişmez ve bir yıl önbelleğe alınır. Değişiklikleri kasıtlı olarak benimsemek istersen sabitle.
Sayfa başına tam olarak bir widget betiği yükle
İki URL alternatiftir, katman değildir. İkisi de aynı custom element adını kaydeder ve bir tarayıcı bir adın belge başına yalnızca bir kez kaydedilmesine izin verir: hangi betik önce çalışırsa sayfanın ömrü boyunca o kazanır ve ikincisi devre dışı kalır. Yani hem /widget.js hem de /widget-v5.js taşıyan bir sayfa, tarayıcının hangisini ilk çalıştırdığına bağlı olarak renderlar, bu senin kontrolünde olan bir şey değildir ve mevcut bir /widget.js'in yanına sürümü sabitlemek için /widget-v5.js eklemek hiçbir şey yapmaz.
Bu olduğunda widget her iki build'i de adlandıran bir uyarıyı konsola yazar, böylece tahmin etmek zorunda kalmazsın. Uyarmaktan fazlasını yapamaz: ikinci kopya çalıştığında ilki adı zaten talep etmiştir. Çözüm her zaman betik etiketini bir başkasını eklemek yerine değiştirmektir, ve bunu senin için bir etiket yöneticisi veya bir parça eklese bile aynı şey geçerlidir. Devam eden build'den sabitlenmiş bir tanesine geçmek için src'yi değiştir.
Sürüm açılır penceresi
data-mode="popup" ekle, eleman hiç sekme render etmez. Ziyaretçinin görmediği yeni bir şey olduğunda en yeni sürümünle tek bir küçük kart gösterir, aksi halde hiçbir şey göstermez. data-mode büyük/küçük harfe duyarlı değildir.
<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>
Geniş ekranlarda kart sol alt köşede durur, çünkü sağ alt köşe genellikle bir sohbet başlatıcısına aittir. 480px altındaki ekranlarda tam genişliği kaplar ve kapatılana kadar sohbet başlatıcısının üstünü örter. Tarayıcının üst katmanında açılır, bu yüzden üst elemanın overflow, transform ya da z-index değeri onu kesemez veya altta bırakamaz. Konumunu değiştirmek için ::part(popup) için stil yaz.
Her sürüm bir kez gösterilir. Kart, ziyaretçinin henüz görmediği kayıtlar olduğunda belirir. Bunların en yenisini, birden fazla varsa sayısıyla birlikte gösterir ve göründüğü anda hepsini görülmüş sayar. Sen yeni bir şey yayımlayana kadar sonraki sayfa yüklemelerinde hiçbir şey görünmez.
İlk ziyarette hiçbir şey gösterilmez: widget yalnızca changelog'unun nereye kadar uzandığını not alır, böylece mevcut kullanıcılar onu eklediğin gün eski haberlerle karşılanmaz. Kart bir sonraki sürümünle başlar. Bir sürümü satır içi widget'ta zaten okumuş olan ziyaretçiye o sürüm tekrar gösterilmez.
Ziyaretçinin gördükleri bir çerezde değil localStorage'da tutulur, bu yüzden tek bir tarayıcıya ve tek bir site kaynağına aittir. Aynı kişi senin başka bir alan adında yeniden ilk ziyaretten başlar. Tarayıcı depolamayı engellerse her ziyaret ilk ziyaret sayılır ve kart hiç görünmez.
data-changelog-url isteğe bağlıdır. Bir http veya https adresi verirsen kart, o adrese giden bir "See all updates" bağlantısı alır, genellikle barındırılan sayfan ya da kendi changelog sayfan. Başka bir değer verirsen bağlantı çizilmez. data-theme ve data-repos, satır içi widget'taki gibi aynen çalışır.
Kart hiçbir zaman odağı almaz ve sayfayı hiçbir zaman engellemez: bir iletişim kutusu değil, etiketli bir bölgedir. Kapat düğmesiyle ya da odak kartın içindeyken Escape ile kapanır. Sayfanın başka yerindeki Escape tuşu senin kendi kodunda bırakılır.
Sayfa başına tek widget betiği kuralı burada da geçerli. Açılır pencere ile satır içi widget aynı sayfada yer alabilir: betiği bir kez yükle ve iki elemanı da ekle, ziyaretçinin neyi zaten gördüğü konusunda ikisi aynı fikirde olur.
/widget-v18.js dahil sabitlenmiş build'ler açılır pencereden eskidir. data-mode'u yok sayar ve onun yerine satır içi sekmeleri render eder, bu yüzden /widget.js ya da daha yeni bir sabitlenmiş build kullan.
Uygulamada Ayarlar, Herkese açık akış altında bu kod parçası, akış kimliğin, temanın ve depo kapsamın doldurulmuş olarak kopyalanmaya hazırdır. Kartın görüntülenmeleri ve "Learn more" bağlantısına yapılan tıklamalar Analitik altında kendi sayıları olarak görünür.
Emoji tepkileri
Okurlar bir şey yazmadan bir kayda tepki verebilir. Tepkiler açıkken her kaydın sonunda, her biri kendi sayısıyla birlikte beş emojilik bir sıra çıkar: 👍 🎉 ❤️ 🚀 👀. Sıra satır içi widget'ta, sürüm açılır penceresi kartında ve barındırılan akış sayfasında görünür.
Tepkiler, uygulamada Ayarlar, Herkese açık akış altından açana kadar kapalıdır. Gömme kodun değişmez: widget anahtarı akışından okur, bu yüzden sıra onunla birlikte görünür ve kaybolur. Tepkileri kapatmak sırayı gizler ama sayıları korur, yani yeniden açarsan geri gelirler. Tepkilerin var olmadığı dönemden kalma sabitlenmiş build''ler sırayı hiçbir zaman göstermez.
Her okur bir kayda her tepkiyi bir kez verebilir, düğmeye yeniden basınca tepki geri alınır. Widget okurları, bir hesaba ya da e-posta adresine değil, ilk tıklamada tarayıcıda oluşturduğu rastgele bir kimliğe göre ayırt eder. Biz bu kimliğin yalnızca ekibinle birleştirilmiş bir hash''ini saklarız, bu yüzden aynı tarayıcı iki farklı changelog''da birbiriyle ilgisiz hash''ler bırakır.
Sayılar en iyi çaba esasıyla tutulur: bir oylama değil, dostça bir işarettir. Tarayıcı depolamasını temizlemek ya da gizli pencere açmak biri için yeniden tepki vermeyi mümkün kılar, bu yüzden önemli hiçbir kararı bunlara dayandırma. Akışındaki sayılar akış önbelleğe alındığı için birkaç dakika geriden de gelebilir, ama tıklayan kişi kendi tepkisinin hemen sayıldığını görür. Uygulamada gelen kutusunun Published sekmesi her kaydın toplamını gösterir.
Tepki vermek, ziyaretçinin localStorage''ında iki şey tutar, hiçbir zaman çerezde tutmaz. changelogapp-widget:reader-id rastgele kimliği taşır, her tarayıcı ve site kaynağı için bir tane. changelogapp-widget:reactions: ve ardından akış kimliğin, bu tarayıcının seçtiği tepkileri taşır, en son tepki verdiği en fazla 200 kayıt için. Barındırılan sayfa aynı ikisini kendi adresi altında tutar. Tarayıcı depolamayı engellerse tepki vermek o sayfa görüntülemesi için yine çalışır ama sonrasında hatırlanmaz.
Sırayı biçimlendirmek için ::part(reactions), her düğme için ::part(reaction) ve düğmenin sayısı için ::part(reaction-count) kullan, hepsi aşağıda Stil verme altında listelenir. Sıfır olan bir sayı hiç rakam göstermez. Basılı bir düğme aria-pressed="true" taşır ve --changelogapp-accent renginde bir halka ve kalın metinle çizilir. ::part() bu özniteliğe göre seçim yapamaz, bu yüzden basılı bir düğmenin görünümünü değiştirmek için --changelogapp-accent değerini ayarla.
Herkese açık geri bildirim panosu
Pano, okurların başkalarının neler istediğini görmesini ve oy vermesini sağlar. Pano açıkken Feedback sekmesi en çok oy alan taleplerinle açılır, her talebin durumu da yanında görünür, olağan form ise bunların altında durur.
Pano, uygulamada Ayarlar, Herkese açık akış altından açana kadar kapalıdır. Gömme kodun değişmez: widget anahtarı akışından okur. Panoyu kapatmak onu gizler, taleplerini ve oylarını korur. Pano Feedback sekmesinde yer alır, bu yüzden Feedback sekmesi göstermeyen bir widget pano da göstermez.
Pano yalnızca senin yazdıklarını gösterir. Bir ziyaretçinin geri bildirimi kendiliğinden panoya düşmez: hangi taleplerin panoda yer alacağına sen karar verirsin ve her talebin başlığını ile açıklamasını uygulamadaki Geri bildirim panosu sayfasında kendin yazarsın. Bir talebi ziyaretçinin gönderdiği bir mesajdan başlatabilir ya da kendi fikrini ekleyebilirsin. Pano ziyaretçinin mesajını ya da e-posta adresini hiçbir zaman göstermez. Pano en çok oy alan 100 talebini gösterir, bir ekip ise en fazla 500 talep tutabilir.
Her talebin beş durumdan biri vardır: Değerlendiriliyor, Planlandı, Devam ediyor, Yayımlandı ya da Reddedildi. Bir talebi bir güncellemeye bağlarsan, o güncelleme yayımlandığında talep kendiliğinden Yayımlandı durumuna geçer, güncelleme zaten yayımlanmışsa hemen geçer. Bir ziyaretçinin mesajından başlattığın talep de, o mesajı karşılayan bir güncelleme yayımlandığında Yayımlandı durumuna geçer.
Her tarayıcı, her sitede her talep için bir oy kullanabilir, yeniden tıklayınca oy geri alınır. Bir talep Yayımlandı ya da Reddedildi durumuna geçince oylama kapanır, ancak daha önce oy veren herkes oyunu yine geri alabilir. Oylar bir işarettir, kişi sayısı değil: tarayıcı depolamasını temizlemek ya da gizli pencere açmak biri için yeniden oy vermeyi mümkün kılar, bu yüzden insanların neyi önemsediğini görmek için kullan, önemli bir kararı onlara bağlama. Diğer ziyaretçilerin gördüğü sayılar biraz geriden gelebilir, oy veren ziyaretçi ise yeni sayıyı tam olarak görür.
Oy vermek, ziyaretçinin localStorage'ında iki şey tutar, hiçbir zaman çerezde tutmaz. changelogapp-widget:votes: ve ardından akış kimliğin, bu tarayıcının oy verdiği talepleri, en yeni 200 taleple sınırlı olarak listeler. changelogapp-widget:reader-id tepkilerin de kullandığı rastgele kimliktir, her tarayıcı ve site kaynağı için bir tane, bu yüzden ziyaretçi zaten tepki verdiyse oy vermek yeni bir şey oluşturmaz. Kimliğin kendisini değil, yalnızca onun ekibinle birleştirilmiş bir karmasını saklarız, bu yüzden aynı tarayıcı iki farklı changelog'da birbiriyle ilgisiz karmalar bırakır. Bir oyla birlikte ziyaretçinin IP adresini saklamayız. Tarayıcı depolamayı engellerse oy vermek o sayfa görüntülemesi için yine çalışır ve sonrasında hatırlanmaz.
Pano sürüm açılır penceresinde hiçbir zaman görünmez, data-repos ile kapsamı daraltılmış bir widget'ta da görünmez, çünkü tüm ekibini kapsar. Barındırılan changelog sayfanda aynı panoyu, duruma göre bir filtreyi ve aynı şekilde sayılan oyları içeren bir Requests sekmesi bulunur. Pano aynı API üzerinde GET /v1/public/YOUR_PUBLIC_ID/board.json adresinde herkese açık JSON olarak da sunulur, pano kapalıyken bu adres 404 döndürür.
Panoyu biçimlendirmek için tüm blok için ::part(board), başlığı için ::part(board-heading) ve ardından her talebin parçalarını kullan, hepsi aşağıda Stil verme altında listelenir. Oy düğmesi ::part(board-vote), bu tarayıcı oy verdikten sonra aria-pressed="true" taşır ve --changelogapp-accent renginde bir halkayla çizilir. ::part() bu özniteliğe göre seçim yapamaz, bu yüzden sayılmış bir oyun görünümünü değiştirmek için --changelogapp-accent değerini ayarla.
Stil verme
Widget bir shadow root içine render eder, bu yüzden stil dosyanın çoğu içeri ulaşmaz. Widget'ın kendi değerini ayarlamadığı yerlerde miras alınan özellikler yine de içeri akar, elemanda ya da bir üst elemanda ayarladığın aşağıdaki özel CSS özellikleri de öyle. Başka her şey için aşağıdaki ::part() adlarını kullan. İki liste de kararlı bir arayüzdür: bir ad yayımlandıktan sonra asla yeniden adlandırılmaz.
Özel CSS özellikleri
--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
Etiket hapları. Rengi olan bir etiket, o rengi arka plan olarak kullanır ve her iki temada da metin rengi, o arka planda 4.5:1 veya daha iyi bir oranla okunacak şekilde seçilir. Bunu sağladığı sürece beyaz tercih edilir. Widget'ın düz bir RGB değeri olarak okuyamadığı bir renk için metin rengi seçilmez ve temanın varsayılanı korunur. Metin rengini her iki temada da kendin seçmek için --changelogapp-pill-text değerini ayarla. Bir ::part(entry-tag) kuralı her şeyin önüne geçer, bu yüzden orada arka plan ayarlarsan color değerini de ayarla. --changelogapp-pill-bg, rengi olmayan bir etiketin arka planıdır. /widget-v18.js dahil, o sürüme kadar sabitlenmiş build'ler açık temada beyaz hap metnini korur.
Parçalar
- Changelog kayıtları:
month-heading,entry,entry-date,entry-tag,entry-title,entry-body,entry-link,timeline-dot,entry-image,entry-header-image - Bir kaydın gövdesinin içi:
entry-body-heading,entry-body-paragraph,entry-body-list,entry-body-list-item,entry-body-link,entry-body-code - Updates sekmesindeki okunmamış sayısı:
unread-badge - Sürüm açılır penceresi:
popup,popup-heading,popup-close,popup-link - E-posta aboneleri açıkken (Team planı) Updates sekmesinin en üstündeki "Get updates by email" formu:
subscribe,subscribe-heading,subscribe-input,subscribe-button,subscribe-status - Emoji tepkileri, açık olduklarında:
reactions,reaction,reaction-count - Herkese açık geri bildirim panosu, açık olduğunda:
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
Siten bir Content-Security-Policy başlığı gönderiyorsa widget'ın API kaynağına iki yönergede ihtiyacı vardır. script-src betiğin yüklenmesini sağlar. connect-src changelog'unu okumasını, geri bildirim göndermesini ve görüntülemeleri kaydetmesini sağlar. Yalnızca birincisiyle eleman görünür ve sonra boş kalır, bu da engellenmiş bir istekten çok bozuk bir akış gibi görünür. Açılır pencere de aynı ikisine ihtiyaç duyar.
script-src https://api.changeloop.dev; connect-src https://api.changeloop.dev;/widget.js'in sunduğu widget 0.16.0 sürümünden itibaren güncel tarayıcılarda style-src değişikliği gerekmez: widget stillerini style-src'nin denetlemediği oluşturulmuş bir stil sayfası olarak teslim eder. /widget-v18.js dahil sabitlenmiş build'ler ve oluşturulabilir stil sayfalarını desteklemeyen tarayıcılar bunun yerine bir style elemanı kullanır, bu da style-src 'unsafe-inline' gerektirir.
img-src yalnızca uygulamada Ayarlar, Herkese açık akış, Görseller altında görselleri açtıysan gerekir. Widget bu durumda resimleri doğrudan görsel host'larından yükler ve onları listelemeyen bir politika her birini engeller. Ayarlar, img-src'yi listenden doldurulmuş hâliyle tam satırı yazdırır, bu yüzden listeyi her değiştirdiğinde onu yeniden kopyala. GitHub'ın ekran görüntüsü host'ları için img-src içinde https://github-production-user-asset-6210df.s3.amazonaws.com da gerekir, çünkü bir GitHub ekran görüntüsü bağlantısı oraya yönlendirir ve tarayıcı o adresi de kontrol eder.
Politikan yalnızca default-src ayarlıyorsa iki yönergeyi de ekle ve default-src kaynaklarını her birinde tekrarla. Bir script-src ya da connect-src, betikler veya bağlantılar için default-src'nin yerini alır, bu yüzden kendi kaynaklarını dışarıda bırakmak onları engellerdi.
Kaynağı mevcut yönergelerinin yerine koymak yerine onlara ekle. Uygulamada Ayarlar, Herkese açık akış hesabın için doğru kaynakla bu satırı gösterir. O başlığı göndermiyorsan yapacak bir şey yok.
Barındırılan akış sayfası
O adreste sade bir sayfayı da biz barındırıyoruz: changelog'un ve roadmap panon, yukarıdaki aynı iki akıştan renderlanmış olarak. Giriş yapmana veya kendi tarafında bir şey kurmana gerek yoktur. Bir döngü kapandığında insanları geri gönderdiğimiz yer de burasıdır: bir GitHub issue'suna bıraktığımız Shipped yorumu buraya bağlanır, yukarıdaki gönderim sorgusundan gelen shippedEntry.link de öyle, ikisi de sonradan daha ileri bir sayfaya taşınsa bile kaydı yine de bulan kendi #entry-ID çapasıyla teslim edilen kayda iner.
Bunu bir yedek olarak ele al, entegrasyon olarak değil. Bunu kendi sitene, bizim değil kendi ürününmüş gibi görünecek şekilde koymanın yolu hâlâ changelog akışı ve widget'tır; bu sayfa henüz onu yapmadığın zamanlar ve başka ne inşa etmiş olursan ol buraya işaret eden döngü kapanış bağlantıları içindir.
Changelog'un, ürününün içinde
Changeloop her kaydı birleştirilmiş bir pull request'ten yazar, incelemen için bekletir ve bu widget'a ve bir JSON akışına sunar. Tek depo için ücretsiz, kart gerekmez.
Ücretsiz başla