コンテンツへスキップ

開発者向けドキュメント一覧

埋め込み型のchangelogウィジェット

HTML 2行で、changelog、ロードマップ、フィードバック欄を製品の中に置けます。このページでは属性、テーマ、一部のリポジトリだけを表示する方法、バージョン管理、そしてウィジェットの代わりになるホスト型ページを説明します。

埋め込みウィジェット

何も構築したくない場合は、この2行を挿入してください。ウィジェットは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 を追加すると、一部のリポジトリだけを表示できます。たとえば複数のプロダクトが 1 つのアカウントを共有している場合に、あるプロダクトのサイトにそのプロダクトの changelog だけを出す、といった使い方です。値は owner/repo 形式のフルネームをカンマで区切ったリストです。所有者を省いた名前は何にも一致せず、エラーなしで空のフィードが表示されます。対象になるのは最大 10 リポジトリです。絞り込んだウィジェットには Updates と Feedback のタブだけが表示されます。ロードマップにはリポジトリ単位の表示がないためで、フィードバックは引き続きチームのフィードバック送信先に登録されます。設定の「公開フィード」には、この属性を自動で書き出すセレクターがあります。

次の順序で3つのタブをレンダリングします:Updates、Roadmap、Feedback。最初の2つは上記のフィードを読み取ります。3つ目は下記のエンドポイントに送信し、各送信のIDをlocalStorageに保存するため、訪問者は戻ってきて送信したものがどうなったかを確認できます。

スクリプトはバージョン付きで提供されます。/widget.jsは常に最新のビルドを提供し、1時間キャッシュされるため、あなたが何もしなくてもリリースは訪問者に届きます。/widget-vN.jsは1つのビルドを固定します:バージョン番号が一度提供されると、そのバイトは二度と変わらず、1年間キャッシュされます。変更を意図的に採用したい場合は固定してください。

1ページにつきウィジェットスクリプトを正確に1つ読み込む

2つのURLは代替であって、レイヤーではありません。どちらも同じカスタム要素名を登録し、ブラウザはドキュメントごとに名前を一度しか登録できないため、先に実行されたスクリプトがそのページの生存期間中は勝ち、2つ目は無効になります。したがって、/widget.jsと/widget-v5.jsの両方を含むページは、ブラウザが先に実行した方をレンダリングします。これはあなたが制御できるものではなく、既存の/widget.jsの隣にバージョン固定のために/widget-v5.jsを追加しても何も起こりません。

これが起こると、ウィジェットは両方のビルドを名指ししてコンソールに警告を書き込むため、推測に頼る必要はありません。それは警告以上のことはできません:2つ目のコピーが実行される頃には、1つ目がすでにその名前を確保しているからです。修正方法は常に、別のスクリプトを追加するのではなくスクリプトタグを置き換えることです。タグマネージャーや部分テンプレートがあなたの代わりに挿入する場合も同様です。継続的なビルドから固定されたビルドに移行するには、srcを変更してください。

リリースのポップアップ

data-mode="popup" を追加すると、要素はタブを表示しなくなります。訪問者にまだ見ていない新しい情報があるときだけ、最新のリリースを載せた小さなカードを 1 枚表示し、それ以外のときは何も表示しません。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) にスタイルを指定してください。

各リリースが表示されるのは 1 回だけです。カードは、訪問者がまだ見ていないエントリがあるときに現れます。その中で最新のものを表示し、複数ある場合は件数も添えます。表示された時点で、それらは既読として扱われます。次にページを読み込んだときは、あなたが新しく公開するまで何も表示されません。

初めての訪問では何も表示されません。ウィジェットは changelog がどこまで進んでいるかを記録するだけなので、導入した当日に既存のユーザーへ古い情報が表示されることはありません。カードの表示は次のリリースから始まります。インラインのウィジェットですでにリリースを読んだ訪問者には、それが再び表示されることはありません。

訪問者が何を見たかは、cookie ではなく localStorage に保存されます。そのため、1 つのブラウザと 1 つのサイトオリジンに限られます。同じ人があなたの別のドメインを開くと、また初めての訪問として扱われます。ブラウザがストレージをブロックしている場合は、毎回の訪問が初めての訪問として扱われ、カードは一度も表示されません。

data-changelog-url は省略できます。http または https のアドレスを指定すると、カードにそこへの「See all updates」リンクが付きます。通常は、ホスト型ページかご自身の changelog ページを指定します。それ以外の値の場合、リンクは表示されません。data-theme と data-repos は、インラインのウィジェットとまったく同じように動作します。

カードがフォーカスを奪うことはなく、ページの操作を妨げることもありません。ダイアログではなく、ラベル付きのリージョンです。閉じるには、閉じるボタンを押すか、カード内にフォーカスがある状態で Escape を押します。カード以外の場所での Escape は、あなたのコードに任されます。

1 ページにつきウィジェットスクリプトは 1 つ、というルールは変わりません。ポップアップとインラインのウィジェットは同じページに置けます。スクリプトを 1 回だけ読み込んで両方の要素を追加すれば、訪問者がすでに見たものについて両者の認識が揃います。

/widget-v18.js までの固定ビルドは、ポップアップより古いものです。data-mode を無視してインラインのタブを表示するので、/widget.js か、それより新しい固定ビルドを使ってください。

アプリの「設定」の「公開フィード」には、このスニペットがコピーできる状態で用意されており、フィード ID、テーマ、リポジトリの範囲もすでに入力されています。カードの表示回数と「Learn more」リンクのクリック数は、「分析」に独立した数値として表示されます。

絵文字リアクション

読者は何も書かなくても、エントリにリアクションできます。リアクションをオンにすると、すべてのエントリの末尾に 👍 🎉 ❤️ 🚀 👀 の 5 つが並び、それぞれの件数が表示されます。この列は、インラインのウィジェット、リリースのポップアップのカード、ホスト型ページに表示されます。

リアクションは、アプリの「設定」の「公開フィード」でオンにするまでオフのままです。埋め込みコードを変える必要はありません。ウィジェットはフィードからスイッチの状態を読み取るので、列はその切り替えに合わせて表示されたり消えたりします。リアクションをオフにすると列は非表示になりますが、件数は残るため、再びオンにすれば元に戻ります。リアクションの機能ができる前の固定ビルドでは、この列は表示されません。

読者は、1 つのエントリに対して各リアクションを 1 回ずつ付けられ、もう一度押すと取り消せます。ウィジェットは、アカウントやメールアドレスではなく、最初のクリック時にブラウザ内で作るランダムな ID で読者を区別します。保存するのは、その ID とあなたのチームを組み合わせたハッシュだけです。そのため、同じブラウザでも 2 つの別々の changelog では、関連のないハッシュが残ります。

件数はあくまで目安で、投票ではなく気軽なシグナルです。ブラウザのストレージを消去したりプライベートウィンドウを開いたりすると、同じ人がもう一度リアクションできるため、大事な判断の根拠にはしないでください。フィードはキャッシュされるので、フィードの件数が数分遅れることもありますが、クリックした本人には自分のリアクションがすぐ反映されます。アプリでは、受信トレイの「公開済み」タブに各エントリの合計が表示されます。

リアクションすると、訪問者の localStorage に 2 つの項目が保存されます。cookie には保存されません。changelogapp-widget:reader-id にはランダムな ID が入り、ブラウザとサイトオリジンごとに 1 つです。changelogapp-widget:reactions: にフィード ID を続けたものには、そのブラウザが選んだリアクションが、最後にリアクションしたものから最大 200 件のエントリ分保存されます。ホスト型ページも、自分のアドレスで同じ 2 つを保持します。ブラウザがストレージをブロックしている場合も、そのページを開いている間はリアクションできますが、その後は記憶されません。

列のスタイルを変えるには、::part(reactions)、各ボタンの ::part(reaction)、その数字の ::part(reaction-count) を使います。いずれも下の「スタイル設定」に一覧があります。件数が 0 のときは数字を表示しません。押された状態のボタンには aria-pressed="true" が付き、--changelogapp-accent の色のリングと太字のテキストで描画されます。::part() ではこの属性による選択はできないため、押されたボタンの見た目を変えたい場合は --changelogapp-accent を設定してください。

公開フィードバックボード

ボードでは、ほかの人がどんな要望を出していて、それに投票できるかを読者が確認できます。ボードをオンにすると、フィードバックタブには票の多い要望がステータス付きで上から並び、いつものフォームはその下に表示されます。

ボードは、アプリの「設定」の「公開フィード」でオンにするまでオフのままです。埋め込みコードを変える必要はありません。ウィジェットはフィードからスイッチの状態を読み取ります。ボードをオフにすると非表示になりますが、要望と票は残ります。ボードはフィードバックタブの中にあるため、フィードバックタブを表示しないウィジェットにはボードも表示されません。

ボードに載るのは、あなたが書いた内容だけです。訪問者のフィードバックが自動でボードに載ることはありません。どの要望を載せるかはあなたが決め、各要望のタイトルと説明もアプリの「フィードバックボード」ページで自分で書きます。訪問者から届いたメッセージをもとに要望を作ることも、自分でアイデアを投稿することもでき、訪問者のメッセージやメールアドレスがボードに表示されることはありません。ボードには上位 100 件の要望が表示され、チームには最大 500 件まで保存できます。

各要望のステータスは、検討中、予定、進行中、リリース済み、見送りの 5 つのいずれかです。要望をアップデートにひも付けると、そのアップデートが公開された時点で自動的に「リリース済み」に移ります。すでに公開済みなら、すぐに移ります。訪問者のメッセージから作った要望も、そのメッセージに応えるアップデートが公開されると「リリース済み」に移ります。

各ブラウザは、サイトごとに 1 つの要望につき 1 票を投じられ、もう一度クリックすると取り消せます。要望が「リリース済み」か「見送り」になると投票は締め切られますが、すでに投票した人は票を取り消せます。票は人数の集計ではなくシグナルです。ブラウザのストレージを消去したりプライベートウィンドウを開いたりすると、同じ人がもう一度投票できるため、みんなが何を気にしているかを知るために使い、大事な判断の決め手にはしないでください。ほかの訪問者に見える件数は少し遅れることがありますが、投票した本人には正確な新しい件数が表示されます。

投票すると、訪問者の localStorage に 2 つの項目が保存されます。cookie には保存されません。changelogapp-widget:votes: にフィード ID を続けたものには、このブラウザが投票した要望が、新しい順に最大 200 件まで入ります。changelogapp-widget:reader-id はリアクションと共通のランダムな ID で、ブラウザとサイトオリジンごとに 1 つです。そのため、訪問者がすでにリアクションしていれば、投票で新しいものは作られません。保存するのは、その ID とあなたのチームを組み合わせたハッシュだけで、ID そのものは保存しません。そのため、同じブラウザでも 2 つの別々の changelog では、関連のないハッシュが残ります。投票と一緒に訪問者の IP アドレスを保存することもありません。ブラウザがストレージをブロックしている場合も、そのページを開いている間は投票できますが、その後は記憶されません。

ボードはチーム全体を対象とするため、リリースのポップアップには表示されず、data-repos で絞り込んだウィジェットにも表示されません。ホスト型の changelog ページには「リクエスト」タブがあり、同じボード、ステータスによる絞り込み、同じ数え方の投票を使えます。ボードは同じ API の GET /v1/public/YOUR_PUBLIC_ID/board.json で公開 JSON としても取得でき、ボードがオフのときは 404 を返します。

ボードのスタイルを変えるには、ブロック全体に ::part(board)、見出しに ::part(board-heading) を使い、続けて各要望のパーツを使います。いずれも下の「スタイル設定」に一覧があります。投票ボタンの ::part(board-vote) は、このブラウザが投票済みになると aria-pressed="true" が付き、--changelogapp-accent の色のリングで描画されます。::part() ではこの属性による選択はできないため、投票済みのボタンの見た目を変えたい場合は --changelogapp-accent を設定してください。

スタイル設定

ウィジェットは shadow root 内にレンダリングされるため、あなたのスタイルシートの大半は内部まで届きません。ウィジェットが独自に値を設定していない継承プロパティは、そのまま引き継がれます。要素または祖先要素に設定した、下記のカスタムプロパティも同様です。それ以外は、下記の ::part() の名前を使ってください。どちらの一覧も安定したインターフェースであり、一度公開された名前が変更されることはありません。

カスタムプロパティ

  • --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」フォーム。メール購読者を有効にしている場合(Teamプラン)、Updates の先頭に表示されます: 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 ヘッダーを送信している場合、ウィジェットには 2 つのディレクティブに API オリジンが必要です。script-src はスクリプトの読み込みを許可し、connect-src は changelog の取得、フィードバックの送信、表示の記録を許可します。前者だけだと、要素は表示されたあと空のままになり、リクエストがブロックされたのではなくフィードが壊れているように見えます。ポップアップにも同じ 2 つが必要です。

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

ウィジェット 0.16.0 以降(/widget.js が配信しているもの)では、最新のブラウザで style-src を変更する必要はありません。ウィジェットはスタイルを constructed stylesheet として渡しますが、これは style-src の対象外だからです。/widget-v18.js までの固定ビルドを含む古いビルドや、constructable stylesheet に対応していないブラウザでは代わりに style 要素を使うため、style-src 'unsafe-inline' が必要です。

img-src が必要になるのは、アプリの「設定」の「公開フィード」の「画像」で画像をオンにしている場合だけです。その場合、ウィジェットは画像ホストから直接画像を読み込むため、それらを含まないポリシーではすべての画像がブロックされます。「設定」には、あなたのリストをもとに img-src を埋めた正確な行が表示されるので、リストを変更したら必ずもう一度コピーしてください。GitHub のスクリーンショット用ホストを使う場合は、img-src に https://github-production-user-asset-6210df.s3.amazonaws.com も必要です。GitHub のスクリーンショットのリンクはそこへリダイレクトされ、ブラウザはそのアドレスも確認するためです。

ポリシーで default-src だけを設定している場合は、2 つのディレクティブを両方追加し、それぞれに default-src のソースを繰り返し書いてください。script-src や connect-src は、スクリプトや接続に関して default-src を置き換えるため、自分のソースを書かずにおくとそれらがブロックされます。

既存のディレクティブを置き換えるのではなく、そこにオリジンを追加してください。アプリの「設定」の「公開フィード」には、あなたのアカウントに合ったオリジンを入れたこの行が表示されます。そのヘッダーを送信していない場合は、何もする必要はありません。

ホスト型フィードページ

当社はその住所にシンプルなページもホストしています:あなたのchangelogとroadmapボードが、上記と同じ2つのフィードからレンダリングされます。サインインもあなた側での設定も不要です。ループが閉じたときに人々を送り返す先でもあります:GitHub issueに残すShippedコメントはここにリンクし、上記の送信検索からのshippedEntry.linkも同様に、両方とも配信されたエントリの独自の#entry-IDアンカーにたどり着きます。これは、その後別のページに移動していてもエントリを見つけます。

これを統合ではなくフォールバックとして扱ってください。あなたのサイトにこれを配置して、当社ではなくあなたの製品のように見せる方法は、changelogフィードとウィジェットのままです。このページは、まだそれを行っていない場合や、他に何を構築していてもここを指すループを閉じるリンクのためのものです。

changelogを製品の中に

Changeloopはマージされたプルリクエストから各エントリーを下書きし、あなたのレビューまで保留して、このウィジェットとJSONフィードに配信します。1リポジトリまで無料、カード不要。

無料で始める

開発者向けドキュメントを読む