Lewati ke konten

Semua dokumentasi developer

Widget changelog untuk disematkan

Dua baris HTML menaruh changelog, roadmap, dan kotak feedback di dalam produkmu. Halaman ini membahas atribut, tema, menampilkan sebagian repositori saja, versi, dan halaman ter-hosting yang menjadi cadangan widget.

Widget yang bisa disematkan

Jika kamu lebih suka tidak membangun apa pun, masukkan dua baris ini. Widget adalah custom element yang dirender di dalam shadow root, jadi tidak mewarisi gayamu maupun bocor ke sana.

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

Kedua atribut wajib diisi. data-public-id adalah ID feedmu, data-api adalah origin tempat widget mengambil data. Jika salah satu hilang, elemen menulis error ke konsol dan tidak merender apa pun, itulah hal pertama yang perlu diperiksa jika kamu melihat ruang kosong di tempat seharusnya widget berada.

Tambahkan data-theme="dark" pada elemen untuk tampilan gelap; halamanmu bisa mengubahnya saat berjalan. Untuk penataan lebih dalam, widget menyediakan properti kustom CSS (--changelogapp-text, --changelogapp-bg, --changelogapp-accent, dan lainnya) serta nama ::part(), yang kamu atur di stylesheet-mu sendiri. Aplikasi menampilkan pratinjau langsung kedua tema di Pengaturan, Feed publik.

Tambahkan data-repos untuk menampilkan hanya sebagian repositori Anda, misalnya changelog satu produk di situs produk itu ketika beberapa produk berbagi satu akun. Nilainya adalah daftar nama lengkap owner/repo yang dipisahkan koma; nama tanpa pemilik tidak cocok dengan apa pun dan menampilkan feed kosong tanpa galat. Paling banyak sepuluh repositori yang diperhitungkan. Widget yang dibatasi hanya menampilkan Updates dan Feedback, karena roadmap tidak punya tampilan per repositori, dan masukan tetap diajukan ke tempat target masukan tim Anda menunjuk. Di Pengaturan, Feed publik ada pemilih yang menuliskan atribut ini untuk Anda.

Ini merender tiga tab dalam urutan ini: Updates, Roadmap, dan Feedback. Dua yang pertama membaca feed di atas. Yang ketiga mengirim ke endpoint di bawah dan menyimpan ID setiap kiriman di localStorage, jadi pengunjung bisa kembali dan melihat apa yang terjadi pada yang mereka kirim.

Skrip disajikan dengan versi. /widget.js selalu menyajikan build terbaru dan di-cache selama satu jam, jadi rilis sampai ke pengunjungmu tanpa kamu menyentuh apa pun. /widget-vN.js mengunci satu build: begitu nomor versi disajikan, byte-nya tidak pernah berubah lagi, dan di-cache selama satu tahun. Kunci jika kamu lebih suka mengadopsi perubahan dengan sengaja.

Muat tepat satu skrip widget per halaman

Kedua URL adalah alternatif, bukan lapisan. Keduanya mendaftarkan nama custom element yang sama, dan browser hanya mengizinkan sebuah nama didaftarkan sekali per dokumen: mana pun yang dieksekusi lebih dulu menang, selama umur halaman itu, dan yang kedua menjadi tidak aktif. Jadi halaman yang membawa /widget.js dan /widget-v5.js merender mana pun yang dieksekusi browser lebih dulu, yang bukan sesuatu yang kamu kendalikan, dan menambahkan /widget-v5.js di samping /widget.js yang sudah ada untuk mengunci versi tidak melakukan apa-apa.

Saat itu terjadi, widget menulis peringatan ke konsol yang menyebutkan kedua build, jadi kamu tidak dibiarkan menebak-nebak. Ini tidak bisa melakukan lebih dari sekadar memperingatkan: saat salinan kedua dieksekusi, yang pertama sudah mengklaim namanya. Perbaikannya selalu mengganti tag skrip alih-alih menambahkan yang lain, dan hal yang sama berlaku jika pengelola tag atau sebuah parsial menyisipkannya untukmu. Untuk beralih dari build yang berjalan terus ke yang terkunci, ubah src-nya.

Pop-up rilis

Tambahkan data-mode="popup" dan elemen tidak lagi merender tab. Saat pengunjung punya sesuatu yang baru untuk dilihat, widget menampilkan satu kartu kecil berisi rilis terbarumu, dan selain itu tidak menampilkan apa pun. data-mode tidak membedakan huruf besar dan kecil.

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

Di layar lebar, kartu berada di pojok kiri bawah, karena pojok kanan bawah biasanya dipakai peluncur chat. Di layar selebar kurang dari 480px, kartu membentang selebar layar dan menutupi peluncur chat sampai ditutup. Kartu dibuka di top layer browser, jadi overflow, transform, atau z-index elemen induk tidak bisa memotong atau menimpanya. Untuk memindahkannya, atur gaya ::part(popup).

Setiap rilis hanya ditampilkan sekali. Kartu muncul saat pengunjung punya entri yang belum dilihat. Kartu menampilkan entri terbaru di antaranya, dengan jumlahnya jika ada beberapa, dan menganggap semuanya sudah dilihat begitu kartu muncul. Pemuatan halaman berikutnya tidak menampilkan apa pun sampai kamu menerbitkan lagi.

Kunjungan pertama tidak menampilkan apa pun: widget hanya mencatat sejauh mana changelog-mu berjalan, sehingga pengguna yang sudah ada tidak disambut kabar lama di hari kamu memasangnya. Kartu mulai muncul dengan rilis berikutnya. Pengunjung yang sudah membaca sebuah rilis di widget inline tidak akan melihatnya lagi.

Apa yang sudah dilihat pengunjung disimpan di localStorage, bukan di cookie, jadi hanya berlaku untuk satu browser dan satu origin situs. Orang yang sama di domainmu yang lain mulai lagi dari kunjungan pertama. Jika browser memblokir penyimpanan, setiap kunjungan dihitung sebagai kunjungan pertama dan kartu tidak pernah muncul.

data-changelog-url bersifat opsional. Dengan alamat http atau https, kartu mendapat tautan See all updates ke alamat itu, biasanya halaman hosting-mu atau halaman changelog milikmu sendiri. Dengan nilai lain, tidak ada tautan yang ditampilkan. data-theme dan data-repos bekerja persis seperti pada widget inline.

Kartu tidak pernah mengambil fokus dan tidak pernah memblokir halaman: kartu ini adalah region berlabel, bukan dialog. Kartu ditutup dengan tombol tutupnya, atau dengan Escape selama fokus ada di dalam kartu. Escape di bagian lain halamanmu dibiarkan untuk kodemu sendiri.

Aturan satu skrip widget per halaman tetap berlaku. Pop-up dan widget inline bisa berbagi satu halaman: muat skripnya sekali dan tambahkan kedua elemen, dan keduanya sepakat tentang apa yang sudah dilihat pengunjung.

Build terkunci hingga /widget-v18.js lebih lama daripada pop-up. Build itu mengabaikan data-mode dan merender tab inline, jadi gunakan /widget.js atau build terkunci yang lebih baru.

Di aplikasi, Pengaturan, Feed publik menyediakan cuplikan ini siap disalin, dengan ID feed, tema, dan cakupan repositorimu sudah terisi. Jumlah tampilan kartu dan klik pada tautan Learn more-nya muncul di Analytics sebagai angka tersendiri.

Reaksi emoji

Pembaca bisa bereaksi pada sebuah entri tanpa menulis apa pun. Saat reaksi aktif, setiap entri diakhiri deretan lima emoji, 👍 🎉 ❤️ 🚀 👀, masing-masing dengan jumlahnya. Deretan ini tampil di widget inline, di kartu pop-up rilis, dan di halaman feed hosting.

Reaksi nonaktif sampai kamu mengaktifkannya di aplikasi, di Pengaturan, Feed publik. Kode embed-mu tidak berubah, karena widget membaca saklarnya dari feed-mu, sehingga deretan reaksi muncul dan hilang mengikutinya. Menonaktifkan reaksi menyembunyikan deretan itu tetapi jumlahnya tetap tersimpan, jadi akan kembali jika kamu mengaktifkannya lagi. Build terkunci dari sebelum reaksi ada tidak pernah menampilkan deretan ini.

Setiap pembaca bisa memberi satu kali tiap reaksi pada sebuah entri, dan menekannya lagi akan membatalkannya. Widget membedakan pembaca lewat ID acak yang dibuatnya di browser pada klik pertama, bukan lewat akun atau alamat email. Kami hanya menyimpan hash dari ID itu yang digabung dengan timmu, sehingga browser yang sama meninggalkan hash yang tidak berhubungan di dua changelog berbeda.

Jumlahnya bersifat perkiraan: sinyal ramah, bukan pemungutan suara. Menghapus penyimpanan browser atau membuka jendela pribadi memungkinkan seseorang bereaksi lagi, jadi jangan pernah mendasarkan keputusan penting pada angka itu. Jumlah di feed-mu juga bisa tertinggal beberapa menit karena feed di-cache, tetapi orang yang mengklik langsung melihat reaksinya sendiri terhitung. Di aplikasi, tab Published di kotak masuk menampilkan total setiap entri.

Saat bereaksi, dua hal disimpan di localStorage pengunjung, tidak pernah di cookie. changelogapp-widget:reader-id menyimpan ID acak, satu per browser dan per origin situs. changelogapp-widget:reactions: diikuti ID feed-mu menyimpan reaksi yang dipilih browser ini, hingga 200 entri, yaitu yang paling baru direaksi. Halaman hosting menyimpan kedua hal yang sama di alamatnya sendiri. Jika browser memblokir penyimpanan, bereaksi tetap berfungsi selama halaman itu dilihat dan tidak diingat setelahnya.

Untuk menata gaya deretan ini, gunakan ::part(reactions), ::part(reaction) untuk setiap tombol, dan ::part(reaction-count) untuk angkanya, semuanya tercantum di bawah Penataan gaya. Jumlah nol tidak menampilkan angka. Tombol yang ditekan memiliki aria-pressed="true" dan digambar dengan cincin berwarna --changelogapp-accent milikmu serta teks tebal. ::part() tidak bisa memilih berdasarkan atribut itu, jadi atur --changelogapp-accent untuk mengubah tampilan tombol yang ditekan.

Papan feedback publik

Papan ini memungkinkan pembaca melihat apa yang diminta orang lain dan memberi suara untuk itu. Saat papan aktif, tab Feedback terbuka dengan permintaan yang paling banyak dipilih, masing-masing lengkap dengan statusnya, dan formulir biasa ada di bawahnya.

Papan nonaktif sampai kamu mengaktifkannya di aplikasi, di Pengaturan, Feed publik. Kode embed-mu tidak berubah, karena widget membaca saklarnya dari feed-mu. Menonaktifkan papan menyembunyikannya, sementara permintaan dan suaranya tetap tersimpan. Papan berada di tab Feedback, jadi widget yang tidak menampilkan tab Feedback juga tidak menampilkan papan.

Papan hanya menampilkan apa yang kamu tulis. Masukan dari pengunjung tidak pernah masuk ke sana dengan sendirinya: kamu yang menentukan permintaan mana yang tampil di papan, dan kamu sendiri yang menulis judul dan deskripsi setiap permintaan, di halaman Feedback board di aplikasi. Kamu bisa memulai sebuah permintaan dari pesan yang dikirim pengunjung atau memposting idemu sendiri, dan papan tidak pernah menampilkan pesan maupun alamat email pengunjung. Papan menampilkan 100 permintaan teratas, dan sebuah tim bisa menyimpan hingga 500.

Setiap permintaan memiliki salah satu dari lima status: Under consideration, Planned, In progress, Shipped, atau Declined. Hubungkan sebuah permintaan dengan sebuah pembaruan, dan permintaan itu berpindah ke Shipped dengan sendirinya saat pembaruan tersebut dipublikasikan, atau langsung jika pembaruannya sudah terbit. Permintaan yang kamu mulai dari pesan pengunjung juga berpindah ke Shipped saat pembaruan yang memenuhi pesan itu dipublikasikan.

Setiap browser punya satu suara per permintaan di setiap situs, dan mengklik lagi akan menariknya kembali. Pemungutan suara ditutup begitu sebuah permintaan berstatus Shipped atau Declined, tetapi siapa pun yang sudah memilih tetap bisa menarik suaranya. Suara adalah sinyal, bukan jumlah orang: menghapus penyimpanan browser atau membuka jendela pribadi memungkinkan seseorang memilih lagi, jadi gunakan suara untuk melihat apa yang diperhatikan orang, jangan pernah untuk memutuskan hal yang penting. Jumlah yang dilihat pengunjung lain bisa tertinggal sedikit, sedangkan pengunjung yang memberi suara langsung melihat jumlah barunya yang tepat.

Saat memberi suara, dua hal disimpan di localStorage pengunjung, tidak pernah di cookie. changelogapp-widget:votes: diikuti ID feed-mu mencatat permintaan yang sudah dipilih browser ini, hingga 200 yang terbaru. changelogapp-widget:reader-id adalah ID acak yang dipakai reaksi, satu per browser dan per origin situs, jadi memberi suara tidak membuat apa pun yang baru jika pengunjung sudah pernah bereaksi. Kami hanya menyimpan hash dari ID itu yang digabung dengan timmu, bukan ID-nya sendiri, sehingga browser yang sama meninggalkan hash yang tidak berhubungan di dua changelog berbeda. Kami tidak menyimpan alamat IP pengunjung bersama suaranya. Jika browser memblokir penyimpanan, memberi suara tetap berfungsi selama halaman itu dilihat dan tidak diingat setelahnya.

Papan tidak pernah tampil di pop-up rilis, dan juga tidak di widget yang dibatasi dengan data-repos, karena papan mencakup seluruh timmu. Halaman changelog hosting-mu memiliki tab Requests dengan papan yang sama, filter berdasarkan status, dan suara yang dihitung dengan cara yang sama. Papan juga tersedia sebagai JSON publik, di GET /v1/public/YOUR_PUBLIC_ID/board.json pada API yang sama, yang menjawab 404 selama papan nonaktif.

Untuk menata gaya papan, gunakan ::part(board) untuk seluruh blok dan ::part(board-heading) untuk judulnya, lalu bagian-bagian dari setiap permintaan, semuanya tercantum di bawah Penataan gaya. Tombol suara, ::part(board-vote), memiliki aria-pressed="true" setelah browser ini memberi suara, dan digambar dengan cincin berwarna --changelogapp-accent milikmu. ::part() tidak bisa memilih berdasarkan atribut itu, jadi atur --changelogapp-accent untuk mengubah tampilan suara yang sudah terhitung.

Penataan gaya

Widget dirender di dalam shadow root, jadi sebagian besar stylesheet-mu tidak menjangkau bagian dalamnya. Properti yang diwariskan tetap mengalir masuk selama widget tidak mengaturnya sendiri, begitu juga properti kustom di bawah, yang diatur pada elemen atau pada induknya. Untuk hal lain, gunakan nama ::part() di bawah. Kedua daftar itu adalah antarmuka yang stabil: nama yang sudah dirilis tidak pernah diganti.

Properti kustom

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

Pil tag. Tag yang punya warna memakainya sebagai latar belakang, dan di kedua tema warna teks dipilih agar terbaca di atas latar itu, dengan rasio 4.5:1 atau lebih baik. Putih lebih diutamakan selama mencapai rasio itu. Warna yang tidak bisa dibaca widget sebagai nilai RGB solid tidak mendapat warna teks pilihan dan tetap memakai default tema. Untuk memilih sendiri warna teksnya, di tema mana pun, atur --changelogapp-pill-text. Aturan ::part(entry-tag) mengalahkan semuanya, jadi jika kamu mengatur latar belakang di sana, atur juga color. --changelogapp-pill-bg adalah latar belakang tag yang tidak punya warna. Build terkunci hingga /widget-v18.js tetap memakai teks pil putih di tema terang.

Part

  • Entri changelog: month-heading, entry, entry-date, entry-tag, entry-title, entry-body, entry-link, timeline-dot, entry-image, entry-header-image
  • Di dalam isi entri: entry-body-heading, entry-body-paragraph, entry-body-list, entry-body-list-item, entry-body-link, entry-body-code
  • Jumlah yang belum dibaca pada tab Updates: unread-badge
  • Pop-up rilis: popup, popup-heading, popup-close, popup-link
  • Formulir Get updates by email, di bagian atas Updates saat pelanggan email diaktifkan (paket Team): subscribe, subscribe-heading, subscribe-input, subscribe-button, subscribe-status
  • Reaksi emoji, saat diaktifkan: reactions, reaction, reaction-count
  • Papan feedback publik, saat diaktifkan: 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

Jika situsmu mengirim header Content-Security-Policy, widget membutuhkan origin API di dua direktif. script-src memungkinkan skrip dimuat. connect-src memungkinkannya membaca changelog-mu, mengirim umpan balik, dan mencatat tampilan. Dengan hanya yang pertama, elemen muncul lalu tetap kosong, yang terlihat seperti feed rusak, bukan permintaan yang diblokir. Pop-up membutuhkan dua direktif yang sama.

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

Mulai widget 0.16.0, yang disajikan /widget.js, browser terkini tidak memerlukan perubahan style-src: widget menyerahkan gayanya sebagai stylesheet bentukan, yang tidak diatur oleh style-src. Build lama, termasuk build terkunci hingga /widget-v18.js, dan browser tanpa constructable stylesheet memakai elemen style, yang membutuhkan style-src 'unsafe-inline'.

img-src hanya diperlukan jika kamu sudah mengaktifkan gambar di aplikasi, di Pengaturan, Feed publik, Gambar. Widget lalu memuat gambar langsung dari host gambarmu, dan kebijakan yang tidak mencantumkannya akan memblokir semuanya. Pengaturan menampilkan baris yang tepat dengan img-src yang sudah diisi dari daftarmu, jadi salin lagi setiap kali kamu mengubah daftarnya. Host tangkapan layar GitHub juga memerlukan https://github-production-user-asset-6210df.s3.amazonaws.com di img-src, karena tautan tangkapan layar GitHub dialihkan ke sana dan browser juga memeriksa alamat itu.

Jika kebijakanmu hanya mengatur default-src, tambahkan kedua direktif dan ulangi sumber default-src-mu di masing-masing. script-src atau connect-src menggantikan default-src untuk skrip atau koneksi, jadi jika sumbermu sendiri tidak disertakan, sumber itu akan terblokir.

Tambahkan origin ke direktifmu yang sudah ada, jangan menggantinya. Pengaturan, Feed publik di aplikasi menampilkan baris ini dengan origin yang tepat untuk akunmu. Jika kamu tidak mengirim header itu, tidak ada yang perlu dilakukan.

Halaman feed hosting

Kami juga menghosting halaman sederhana di alamat itu: changelog dan papan roadmap-mu, dirender dari dua feed yang sama di atas. Tidak perlu login dan tidak perlu apa pun yang dikonfigurasi di sisimu. Ini juga tempat kami mengirim orang kembali begitu sebuah lingkaran ditutup: komentar Shipped yang kami tinggalkan pada issue GitHub mengarah ke sini, begitu juga shippedEntry.link dari pencarian kiriman di atas, keduanya mendarat di entri yang dikirim dengan anchor #entry-ID-nya sendiri, yang tetap menemukan entrinya bahkan jika sudah pindah ke halaman berikutnya.

Perlakukan ini sebagai cadangan, bukan integrasi. Feed changelog dan widget tetap cara untuk menaruh ini di situsmu sendiri agar terlihat seperti produkmu bukan produk kami; halaman ini untuk saat kamu belum melakukannya, dan untuk tautan penutup lingkaran, yang mengarah ke sini terlepas dari apa lagi yang sudah kamu bangun.

Changelog-mu, di dalam produkmu

Changeloop menyusun setiap entri dari pull request yang di-merge, menahannya untuk kamu tinjau, lalu menyajikannya ke widget ini dan ke feed JSON. Gratis untuk satu repositori, tanpa kartu.

Mulai gratis

Baca dokumentasi developer