임베드 위젯
아무것도 구축하고 싶지 않다면 이 두 줄을 삽입하세요. 위젯은 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를 추가하면 일부 리포지토리만 표시할 수 있습니다. 예를 들어 여러 제품이 한 계정을 공유할 때 한 제품의 사이트에 그 제품의 changelog만 보여 줄 수 있습니다. 값은 owner/repo 형식의 전체 이름을 쉼표로 구분한 목록입니다. 소유자를 뺀 이름은 아무것에도 일치하지 않으며 오류 없이 빈 피드가 표시됩니다. 최대 10개 리포지토리까지 적용됩니다. 범위를 좁힌 위젯에는 Updates와 Feedback 탭만 표시됩니다. 로드맵에는 리포지토리별 보기가 없기 때문이며, 피드백은 여전히 팀의 피드백 대상이 가리키는 곳에 등록됩니다. 설정의 공개 피드에는 이 속성을 대신 작성해 주는 선택 도구가 있습니다.
다음 순서로 세 개의 탭을 렌더링합니다: Updates, Roadmap, Feedback. 처음 두 개는 위의 피드를 읽습니다. 세 번째는 아래 엔드포인트로 전송하고 각 제출의 ID를 localStorage에 보관하여, 방문자가 돌아와서 보낸 것이 어떻게 되었는지 확인할 수 있습니다.
스크립트는 버전이 지정되어 제공됩니다. /widget.js는 항상 최신 빌드를 제공하고 1시간 동안 캐시되므로, 여러분이 아무것도 건드리지 않아도 릴리스가 방문자에게 도달합니다. /widget-vN.js는 하나의 빌드를 고정합니다: 버전 번호가 한 번 제공되면 그 바이트는 두 번 다시 바뀌지 않으며 1년 동안 캐시됩니다. 변경 사항을 의도적으로 채택하고 싶다면 고정하세요.
페이지당 정확히 하나의 위젯 스크립트를 로드하세요
두 URL은 대안이지 계층이 아닙니다. 둘 다 동일한 커스텀 요소 이름을 등록하며, 브라우저는 문서당 이름을 한 번만 등록할 수 있게 하므로, 먼저 실행된 스크립트가 페이지가 살아있는 동안 승리하고 두 번째는 비활성화됩니다. 따라서 /widget.js와 /widget-v5.js를 모두 포함한 페이지는 브라우저가 먼저 실행한 것을 렌더링하며, 이는 여러분이 제어할 수 있는 것이 아닙니다. 버전을 고정하기 위해 기존 /widget.js 옆에 /widget-v5.js를 추가해도 아무 효과가 없습니다.
이런 일이 발생하면 위젯은 두 빌드를 모두 지목하는 경고를 콘솔에 기록하므로 추측할 필요가 없습니다. 경고 이상의 일은 할 수 없습니다: 두 번째 사본이 실행될 즈음에는 첫 번째가 이미 그 이름을 차지했기 때문입니다. 해결책은 항상 다른 것을 추가하는 대신 스크립트 태그를 교체하는 것이며, 태그 관리자나 부분 템플릿이 대신 삽입하는 경우도 마찬가지입니다. 계속 진행되는 빌드에서 고정된 빌드로 옮기려면 src를 변경하세요.
릴리스 팝업
data-mode="popup"을 추가하면 요소는 탭을 렌더링하지 않습니다. 방문자에게 새로 보여 줄 내용이 있을 때만 가장 최근 릴리스를 담은 작은 카드 하나를 표시하고, 그렇지 않으면 아무것도 표시하지 않습니다. 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)에 스타일을 지정하세요.
각 릴리스는 한 번만 표시됩니다. 카드는 방문자가 아직 보지 못한 항목이 있을 때 나타납니다. 그중 가장 최근 항목을 보여 주고, 여러 개이면 개수도 함께 표시하며, 카드가 나타나는 순간 모두 본 것으로 처리합니다. 다음에 페이지를 불러올 때는 새로 게시하기 전까지 아무것도 표시되지 않습니다.
처음 방문하면 아무것도 표시되지 않습니다. 위젯은 changelog가 어디까지 쓰여 있는지만 기록해 두므로, 위젯을 추가한 날 기존 사용자에게 오래된 소식이 뜨는 일은 없습니다. 카드는 다음 릴리스부터 시작됩니다. 인라인 위젯에서 이미 릴리스를 읽은 방문자에게는 같은 릴리스가 다시 표시되지 않습니다.
방문자가 본 내용은 쿠키가 아니라 localStorage에 저장되므로 하나의 브라우저와 하나의 사이트 오리진에 속합니다. 같은 사람이 다른 도메인에서 방문하면 처음 방문부터 다시 시작합니다. 브라우저가 저장소를 차단하면 모든 방문이 첫 방문으로 간주되어 카드가 표시되지 않습니다.
data-changelog-url은 선택 사항입니다. http 또는 https 주소를 지정하면 카드에 그 주소로 가는 "See all updates" 링크가 생기며, 보통 호스팅된 페이지나 직접 만든 changelog 페이지를 가리킵니다. 다른 값이면 링크는 표시되지 않습니다. data-theme와 data-repos는 인라인 위젯과 똑같이 동작합니다.
카드는 포커스를 가져가지 않고 페이지를 막지도 않습니다. 대화상자가 아니라 이름이 붙은 영역입니다. 닫기 버튼으로 닫을 수 있고, 포커스가 카드 안에 있을 때는 Escape로도 닫힙니다. 페이지의 다른 곳에서 누른 Escape는 여러분의 코드에 맡깁니다.
페이지당 위젯 스크립트 하나라는 규칙은 여전히 적용됩니다. 팝업과 인라인 위젯은 한 페이지에 함께 둘 수 있습니다. 스크립트를 한 번만 로드하고 두 요소를 모두 추가하면, 방문자가 이미 본 내용을 둘이 같은 기준으로 판단합니다.
/widget-v18.js까지의 고정 빌드는 팝업보다 오래된 버전입니다. 이들은 data-mode를 무시하고 인라인 탭을 렌더링하므로 /widget.js나 더 새로운 고정 빌드를 사용하세요.
앱의 설정, 공개 피드에는 여러분의 피드 ID, 테마, 리포지토리 범위가 채워진 이 스니펫이 복사할 수 있게 준비되어 있습니다. 카드 조회 수와 "Learn more" 링크 클릭 수는 분석에 별도의 수치로 표시됩니다.
이모지 반응
독자는 아무것도 쓰지 않고도 항목에 반응할 수 있습니다. 반응을 켜면 모든 항목 끝에 👍 🎉 ❤️ 🚀 👀 다섯 개가 한 줄로 표시되고, 각각 개수가 함께 나옵니다. 이 줄은 인라인 위젯, 릴리스 팝업 카드, 호스팅된 피드 페이지에 표시됩니다.
반응은 앱의 설정, 공개 피드에서 켜기 전까지 꺼져 있습니다. 임베드 코드는 바꿀 필요가 없습니다. 위젯이 스위치 상태를 여러분의 피드에서 읽어 오므로 이 줄도 스위치에 따라 나타나고 사라집니다. 반응을 끄면 줄만 숨겨지고 개수는 그대로 남아 있어서, 다시 켜면 그대로 돌아옵니다. 반응 기능이 생기기 전의 고정 빌드에는 이 줄이 표시되지 않습니다.
독자는 항목마다 각 반응을 한 번씩 남길 수 있고, 같은 반응을 다시 누르면 취소됩니다. 위젯은 계정이나 이메일 주소가 아니라 첫 클릭 때 브라우저에서 만드는 무작위 ID로 독자를 구분합니다. 서버에는 이 ID와 여러분의 팀을 합친 값의 해시만 저장하므로, 같은 브라우저라도 서로 다른 두 changelog에는 관련 없는 해시가 남습니다.
개수는 어디까지나 참고용입니다. 투표가 아니라 가벼운 신호일 뿐입니다. 브라우저 저장소를 지우거나 시크릿 창을 열면 다시 반응할 수 있으므로, 중요한 결정의 근거로는 쓰지 마세요. 피드가 캐시되기 때문에 피드의 개수는 몇 분 늦게 반영될 수도 있지만, 반응을 누른 사람에게는 자기 반응이 바로 집계되어 보입니다. 앱에서는 받은편지함의 Published 탭에서 항목별 합계를 볼 수 있습니다.
반응하면 방문자의 localStorage에 두 가지가 저장되며, 쿠키에는 저장되지 않습니다. changelogapp-widget:reader-id에는 무작위 ID가 들어 있고, 브라우저와 사이트 오리진마다 하나씩입니다. changelogapp-widget:reactions: 뒤에 여러분의 피드 ID가 붙은 키에는 이 브라우저에서 선택한 반응이 최근에 반응한 항목 순으로 최대 200개까지 저장됩니다. 호스팅된 페이지도 자체 주소에 같은 두 가지를 따로 저장합니다. 브라우저가 저장소를 차단하면 그 페이지를 보는 동안에는 반응이 정상적으로 동작하지만, 이후에는 기억되지 않습니다.
이 줄의 스타일을 지정하려면 ::part(reactions)를 사용하고, 각 버튼에는 ::part(reaction), 숫자에는 ::part(reaction-count)를 사용하세요. 모두 아래 스타일링에 나와 있습니다. 개수가 0이면 숫자는 표시되지 않습니다. 눌린 버튼은 aria-pressed="true"를 가지며, 여러분의 --changelogapp-accent 색 테두리와 굵은 글씨로 그려집니다. ::part()로는 이 속성을 기준으로 선택할 수 없으므로, 눌린 버튼의 모습을 바꾸려면 --changelogapp-accent를 설정하세요.
공개 피드백 보드
보드에서는 독자가 다른 사람들이 어떤 요청을 했는지 보고 투표할 수 있습니다. 보드를 켜면 Feedback 탭이 득표가 가장 많은 요청부터 보여 주고, 각 요청에 상태가 표시되며, 기존 양식은 그 아래에 나옵니다.
보드는 앱의 설정, 공개 피드에서 켜기 전까지 꺼져 있습니다. 임베드 코드는 바꿀 필요가 없습니다. 위젯이 스위치 상태를 여러분의 피드에서 읽어 오기 때문입니다. 보드를 끄면 숨겨질 뿐 요청과 득표는 그대로 남습니다. 보드는 Feedback 탭 안에 있으므로, Feedback 탭이 없는 위젯에는 보드도 나타나지 않습니다.
보드에는 여러분이 직접 쓴 내용만 표시됩니다. 방문자의 피드백이 저절로 올라가는 일은 없습니다. 어떤 요청을 보드에 올릴지는 여러분이 정하고, 각 요청의 제목과 설명도 앱의 Feedback board 페이지에서 직접 씁니다. 방문자가 보낸 메시지에서 요청을 시작할 수도 있고 여러분의 아이디어를 직접 올릴 수도 있으며, 보드에는 방문자의 메시지나 이메일 주소가 절대 표시되지 않습니다. 보드에는 상위 100개 요청이 표시되고, 팀은 최대 500개까지 보관할 수 있습니다.
각 요청은 Under consideration, Planned, In progress, Shipped, Declined 다섯 가지 상태 중 하나를 가집니다. 요청을 업데이트에 연결하면 그 업데이트가 게시될 때 자동으로 Shipped로 바뀌고, 이미 게시된 업데이트라면 바로 바뀝니다. 방문자의 메시지에서 시작한 요청도 그 메시지를 해결하는 업데이트가 게시되면 Shipped로 바뀝니다.
각 브라우저는 사이트마다 요청당 한 표를 가지며, 다시 클릭하면 취소됩니다. 요청이 Shipped나 Declined가 되면 투표는 마감되지만, 이미 투표한 사람은 자기 표를 취소할 수 있습니다. 득표수는 참고용 신호일 뿐 사람 수가 아닙니다. 브라우저 저장소를 지우거나 시크릿 창을 열면 다시 투표할 수 있으므로, 사람들이 무엇에 관심을 두는지 파악하는 데만 쓰고 중요한 결정을 내리는 근거로는 쓰지 마세요. 다른 방문자에게 보이는 개수는 조금 늦게 반영될 수 있지만, 투표한 방문자에게는 정확한 새 개수가 바로 보입니다.
투표하면 방문자의 localStorage에 두 가지가 저장되며, 쿠키에는 저장되지 않습니다. changelogapp-widget:votes: 뒤에 여러분의 피드 ID가 붙은 키에는 이 브라우저에서 투표한 요청이 최근 순으로 최대 200개까지 저장됩니다. changelogapp-widget:reader-id는 반응에도 쓰이는 무작위 ID로, 브라우저와 사이트 오리진마다 하나씩이므로 방문자가 이미 반응한 적이 있다면 투표해도 새로 생기는 것은 없습니다. 서버에는 이 ID와 여러분의 팀을 합친 값의 해시만 저장하고 ID 자체는 저장하지 않으므로, 같은 브라우저라도 서로 다른 두 changelog에는 관련 없는 해시가 남습니다. 투표와 함께 방문자의 IP 주소는 저장하지 않습니다. 브라우저가 저장소를 차단하면 그 페이지를 보는 동안에는 투표가 되지만, 이후에는 기억되지 않습니다.
보드는 릴리스 팝업에는 표시되지 않으며, 팀 전체를 대상으로 하기 때문에 data-repos로 범위를 좁힌 위젯에도 표시되지 않습니다. 호스팅된 changelog 페이지에는 같은 보드, 상태별 필터, 같은 방식으로 집계되는 투표를 갖춘 Requests 탭이 있습니다. 보드는 같은 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 - 이메일 구독자를 켰을 때(Team 플랜) Updates 맨 위에 표시되는 "Get updates by email" 양식:
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 헤더를 보낸다면, 위젯에는 두 개의 지시문에 API 오리진이 필요합니다. script-src는 스크립트를 로드할 수 있게 하고, connect-src는 changelog를 읽고 피드백을 보내고 조회를 기록할 수 있게 합니다. 첫 번째만 있으면 요소는 나타났다가 비어 있게 되는데, 차단된 요청이 아니라 고장 난 피드처럼 보입니다. 팝업에도 같은 두 가지가 필요합니다.
script-src https://api.changeloop.dev; connect-src https://api.changeloop.dev;/widget.js가 제공하는 위젯 0.16.0부터는 최신 브라우저에서 style-src를 바꿀 필요가 없습니다. 위젯이 스타일을 생성된 스타일시트로 넘기는데, style-src는 이를 제어하지 않기 때문입니다. /widget-v18.js까지의 고정 빌드를 포함한 이전 빌드와 생성 가능한 스타일시트를 지원하지 않는 브라우저는 대신 style 요소를 사용하며, 이때는 style-src 'unsafe-inline'이 필요합니다.
img-src는 앱의 설정, 공개 피드, 이미지에서 이미지를 켠 경우에만 필요합니다. 그러면 위젯이 이미지 호스트에서 그림을 직접 불러오는데, 정책에 그 호스트가 없으면 모두 차단됩니다. 설정에는 목록을 바탕으로 img-src가 채워진 정확한 줄이 표시되므로, 목록을 바꿀 때마다 다시 복사하세요. GitHub의 스크린샷 호스트를 쓰려면 img-src에 https://github-production-user-asset-6210df.s3.amazonaws.com도 있어야 합니다. GitHub 스크린샷 링크가 그 주소로 리디렉션되고, 브라우저가 그 주소도 검사하기 때문입니다.
정책이 default-src만 설정한다면 두 지시문을 모두 추가하고 각각에 기존 default-src 소스를 반복해서 적으세요. script-src나 connect-src는 스크립트나 연결에 대해 default-src를 대체하므로, 기존 소스를 빼면 그 소스가 차단됩니다.
기존 지시문을 교체하지 말고 거기에 오리진을 추가하세요. 앱의 설정, 공개 피드에서 여러분의 계정에 맞는 오리진이 들어간 이 줄을 확인할 수 있습니다. 해당 헤더를 보내지 않는다면 할 일은 없습니다.
호스팅된 피드 페이지
당사는 해당 주소에도 단순한 페이지를 호스팅합니다: 여러분의 changelog와 roadmap 보드가 위와 동일한 두 피드에서 렌더링됩니다. 로그인이나 여러분 측의 설정이 필요 없습니다. 이는 또한 루프가 닫힐 때 사람들을 돌려보내는 곳이기도 합니다: GitHub issue에 남기는 Shipped 댓글은 여기로 링크되며, 위의 제출 조회에서 나온 shippedEntry.link도 마찬가지로, 둘 다 전달된 항목의 자체 #entry-ID 앵커에 도달하는데, 이는 이후 나중 페이지로 이동했더라도 항목을 찾아냅니다.
이것을 통합이 아닌 대체 수단으로 취급하세요. 이것을 당사가 아닌 여러분의 제품처럼 보이도록 여러분 자신의 사이트에 배치하는 방법은 여전히 changelog 피드와 위젯입니다. 이 페이지는 아직 그렇게 하지 않았을 때, 그리고 다른 무엇을 구축했든 관계없이 여기를 가리키는 루프 종료 링크를 위한 것입니다.