O widget incorporável
Se preferir não construir nada, insira estas duas linhas. O widget é um custom element que renderiza dentro de um shadow root, então nem herda seus estilos nem vaza para eles.
<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>
Ambos os atributos são obrigatórios. data-public-id é o ID do seu feed, data-api é a origem de onde o widget busca dados. Se algum estiver faltando, o elemento escreve um erro no console e não renderiza nada, o que é a primeira coisa a verificar se você vir um espaço vazio onde deveria estar.
Adicione data-theme="dark" ao elemento para uma renderização escura; sua página pode alternar isso em tempo de execução. Para um estilo mais profundo, o widget expõe propriedades CSS personalizadas (--changelogapp-text, --changelogapp-bg, --changelogapp-accent e outras) e nomes ::part(), que você define na sua própria folha de estilos. O app mostra os dois temas ao vivo em Configurações, Feed público.
Adicione data-repos para mostrar apenas alguns dos seus repositórios, por exemplo o changelog de um produto no site desse produto quando vários produtos compartilham uma conta. O valor é uma lista de nomes completos owner/repo separados por vírgula; um nome sem o dono não corresponde a nada e mostra um feed vazio sem erro. São considerados até dez repositórios. Um widget assim delimitado mostra só Updates e Feedback, porque o roadmap não tem visão por repositório, e o feedback continua sendo registrado onde o destino de feedback da sua equipe aponta. Em Configurações, Feed público há um seletor que escreve o atributo para você.
Ele renderiza três abas nesta ordem: Updates, Roadmap e Feedback. As duas primeiras leem os feeds acima. A terceira envia para o endpoint abaixo e guarda o ID de cada envio no localStorage, então um visitante pode voltar e ver o que aconteceu com o que enviou.
O script é servido versionado. /widget.js sempre serve o build mais recente e é armazenado em cache por uma hora, então um lançamento chega aos seus visitantes sem você tocar em nada. /widget-vN.js fixa um build: assim que um número de versão foi servido, seus bytes nunca mudam de novo, e fica em cache por um ano. Fixe se preferir adotar mudanças de propósito.
Carregue exatamente um script do widget por página
As duas URLs são alternativas, não camadas. Ambas registram o mesmo nome de custom element, e um navegador só permite registrar um nome uma vez por documento: quem executar primeiro vence, pela vida útil da página, e o segundo fica inerte. Então uma página com /widget.js e /widget-v5.js renderiza qualquer um que o navegador tenha executado primeiro, o que não é algo que você controla, e adicionar /widget-v5.js ao lado de um /widget.js existente para fixar a versão não faz nada.
Quando isso acontece, o widget escreve um aviso no console nomeando os dois builds, então você não fica adivinhando. Ele não pode fazer mais que avisar: quando a segunda cópia executa, a primeira já reivindicou o nome. A correção é sempre substituir a tag de script em vez de adicionar outra, e o mesmo vale se um gerenciador de tags ou um parcial inserir uma para você. Para migrar do build contínuo para um fixo, mude o src.
Pop-up de lançamento
Adicione data-mode="popup" e o elemento não renderiza abas. Quando o visitante tem algo novo para ver, ele mostra um único cartão pequeno com o seu lançamento mais recente e, caso contrário, nada. data-mode não diferencia maiúsculas de minúsculas.
<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>
Em telas largas, o cartão fica no canto inferior esquerdo, porque o canto inferior direito costuma pertencer a um botão de chat. Em telas com menos de 480px de largura, ele ocupa a largura toda e cobre o botão de chat até ser fechado. Ele abre na camada superior do navegador, então o overflow, o transform ou o z-index de um elemento pai não conseguem cortá-lo nem escondê-lo. Para movê-lo, estilize ::part(popup).
Cada lançamento é mostrado uma vez. O cartão aparece quando o visitante tem entradas que ainda não viu. Ele mostra a mais recente delas, com uma contagem quando há várias, e as marca como vistas no instante em que aparece. O carregamento de página seguinte não mostra nada até você publicar de novo.
Uma primeira visita não mostra nada: o widget apenas registra até onde vai o seu changelog, para que os usuários existentes não sejam recebidos com notícias antigas no dia em que você o adiciona. O cartão começa com o seu próximo lançamento. Um visitante que já leu um lançamento no widget embutido não o vê de novo.
O que o visitante já viu fica guardado no localStorage, não em um cookie, então pertence a um único navegador e a uma única origem de site. A mesma pessoa em outro dos seus domínios recomeça de uma primeira visita. Se o navegador bloquear o armazenamento, toda visita conta como primeira visita e o cartão nunca aparece.
data-changelog-url é opcional. Com um endereço http ou https, o cartão ganha um link See all updates para ele, geralmente a sua página hospedada ou a sua própria página de changelog. Com qualquer outra coisa, nenhum link é desenhado. data-theme e data-repos funcionam exatamente como no widget embutido.
O cartão nunca recebe o foco e nunca bloqueia a página: é uma região rotulada, não uma caixa de diálogo. Ele fecha com o botão de fechar, ou com Escape enquanto o foco estiver dentro do cartão. Escape em qualquer outro lugar da sua página fica por conta do seu próprio código.
A regra de um único script do widget por página continua valendo. O pop-up e o widget embutido podem dividir uma página: carregue o script uma vez e adicione os dois elementos, e eles concordam sobre o que o visitante já viu.
Builds fixados até /widget-v18.js são mais antigos que o pop-up. Eles ignoram data-mode e renderizam as abas embutidas, então use /widget.js ou um build fixado mais novo.
No app, Configurações, Feed público tem este trecho pronto para copiar, com o ID do seu feed, o tema e o escopo de repositórios preenchidos. As visualizações do cartão e os cliques no link Learn more aparecem em Analytics como números próprios.
Reações com emoji
Os leitores podem reagir a uma entrada sem escrever nada. Com as reações ativadas, cada entrada termina com uma fileira de cinco, 👍 🎉 ❤️ 🚀 👀, cada uma com a sua contagem. A fileira aparece no widget embutido, no cartão do pop-up de lançamento e na página de feed hospedada.
As reações ficam desativadas até você ativá-las no app, em Configurações, Feed público. O seu código de incorporação não muda: o widget lê a chave no seu feed, então a fileira aparece e some junto com ela. Desativar as reações esconde a fileira e mantém as contagens, que voltam se você as ativar de novo. Builds fixados de antes de as reações existirem nunca mostram a fileira.
Cada leitor pode dar a cada entrada cada reação uma vez, e tocar nela de novo a desfaz. O widget distingue os leitores por um ID aleatório que ele cria no navegador no primeiro clique, não por uma conta nem por um endereço de e-mail. Guardamos apenas um hash desse ID combinado com a sua equipe, então o mesmo navegador deixa hashes sem relação entre si em dois changelogs diferentes.
As contagens são aproximadas: um sinal amigável, não uma votação. Limpar o armazenamento do navegador ou abrir uma janela privada permite que alguém reaja de novo, então nunca baseie uma decisão importante nelas. As contagens no seu feed também podem atrasar alguns minutos, porque o feed fica em cache, mas quem clica vê a própria reação contada na hora. No app, a aba Publicado da caixa de revisão mostra o total de cada entrada.
Ao reagir, são guardadas duas coisas no localStorage do visitante, nunca em um cookie. changelogapp-widget:reader-id guarda o ID aleatório, um por navegador e por origem de site. changelogapp-widget:reactions: seguido do ID do seu feed guarda as reações que este navegador escolheu, para até 200 entradas, as mais recentes em que ele reagiu. A página hospedada guarda as mesmas duas sob o próprio endereço. Se o navegador bloquear o armazenamento, reagir continua funcionando naquela visualização da página, mas não é lembrado depois dela.
Para estilizar a fileira, use ::part(reactions), ::part(reaction) para cada botão e ::part(reaction-count) para o seu número, todos listados em Estilização abaixo. Uma contagem zero não mostra número. Um botão pressionado tem aria-pressed="true" e é desenhado com um anel na cor do seu --changelogapp-accent e texto em negrito. ::part() não consegue selecionar por esse atributo, então defina --changelogapp-accent para mudar a aparência de um botão pressionado.
Quadro público de feedback
O quadro permite que os leitores vejam o que outras pessoas pediram e votem nesses pedidos. Com o quadro ativado, a aba Feedback abre com os seus pedidos mais votados, cada um com o seu status, e o formulário de sempre fica logo abaixo.
O quadro fica desativado até você ativá-lo no app, em Configurações, Feed público. O seu código de incorporação não muda: o widget lê a chave no seu feed. Desativar o quadro o esconde e mantém os seus pedidos e os votos deles. Ele fica na aba Feedback, então um widget sem a aba Feedback também não mostra o quadro.
O quadro mostra só o que você escreve. O feedback de um visitante nunca vai para ele sozinho: você decide quais pedidos entram no quadro e escreve o título e a descrição de cada um, na página Feedback board do app. Você pode criar um pedido a partir de uma mensagem que um visitante enviou ou publicar uma ideia sua, e o quadro nunca mostra a mensagem nem o endereço de e-mail do visitante. O quadro mostra os seus 100 principais pedidos, e uma equipe pode manter até 500.
Cada pedido tem um de cinco status: Under consideration, Planned, In progress, Shipped ou Declined. Vincule um pedido a uma atualização e ele passa para Shipped sozinho quando essa atualização é publicada, ou na hora, se ela já estiver publicada. Um pedido que você criou a partir de uma mensagem de visitante também passa para Shipped quando é publicada uma atualização que entrega essa mensagem.
Cada navegador tem um voto por pedido em cada site, e clicar de novo o desfaz. A votação fecha quando um pedido chega a Shipped ou Declined, embora quem já votou ainda possa retirar o voto. Os votos são um sinal, não uma contagem de pessoas: limpar o armazenamento do navegador ou abrir uma janela privada permite que alguém vote de novo, então use-os para ver o que importa para as pessoas, nunca para decidir algo importante. As contagens que os outros visitantes veem podem atrasar um pouco, enquanto o visitante que vota vê a nova contagem exata.
Ao votar, são guardadas duas coisas no localStorage do visitante, nunca em um cookie. changelogapp-widget:votes: seguido do ID do seu feed lista os pedidos em que este navegador votou, até os 200 mais recentes. changelogapp-widget:reader-id é o ID aleatório que as reações usam, um por navegador e por origem de site, então votar não cria nada de novo se o visitante já reagiu. Guardamos apenas um hash desse ID combinado com a sua equipe, nunca o ID em si, então o mesmo navegador deixa hashes sem relação entre si em dois changelogs diferentes. Não guardamos o endereço IP do visitante junto com um voto. Se o navegador bloquear o armazenamento, votar continua funcionando naquela visualização da página, mas não é lembrado depois dela.
O quadro nunca aparece no pop-up de lançamento, nem em um widget delimitado com data-repos, porque ele cobre a sua equipe inteira. A sua página de changelog hospedada tem uma aba Requests com o mesmo quadro, um filtro por status e votos que contam do mesmo jeito. O quadro também é um JSON público, em GET /v1/public/YOUR_PUBLIC_ID/board.json na mesma API, que responde 404 enquanto o quadro está desativado.
Para estilizar o quadro, use ::part(board) para o bloco inteiro e ::part(board-heading) para o título, depois as partes de cada pedido, todas listadas em Estilização abaixo. O botão de voto, ::part(board-vote), tem aria-pressed="true" quando este navegador já votou e passa a ser desenhado com um anel na cor do seu --changelogapp-accent. ::part() não consegue selecionar por esse atributo, então defina --changelogapp-accent para mudar a aparência de um voto contado.
Estilização
O widget renderiza dentro de um shadow root, então a maior parte da sua folha de estilo não chega lá dentro. Propriedades herdadas ainda passam onde o widget não define as suas, e as propriedades personalizadas abaixo também, definidas no elemento ou em um ancestral. Para qualquer outra coisa, use os nomes ::part() abaixo. As duas listas são uma interface estável: depois que um nome é lançado, ele nunca é renomeado.
Propriedades personalizadas
--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
Pílulas de tag. Uma tag com cor usa essa cor como fundo e, nos dois temas, a cor do texto é escolhida para ser legível sobre esse fundo, com 4.5:1 ou mais. O branco é preferido sempre que atinge isso. Uma cor que o widget não consegue ler como um valor RGB sólido não recebe cor de texto escolhida e mantém o padrão do tema. Para escolher a cor do texto você mesmo, em qualquer um dos temas, defina --changelogapp-pill-text. Uma regra ::part(entry-tag) vence todas as outras, então, se você definir um fundo ali, defina também color. --changelogapp-pill-bg é o fundo de uma tag sem cor. Os builds fixados até /widget-v18.js mantêm o texto das pílulas branco no tema claro.
Partes
- Entradas do changelog:
month-heading,entry,entry-date,entry-tag,entry-title,entry-body,entry-link,timeline-dot,entry-image,entry-header-image - Dentro do corpo de uma entrada:
entry-body-heading,entry-body-paragraph,entry-body-list,entry-body-list-item,entry-body-link,entry-body-code - A contagem de não lidas na aba Updates:
unread-badge - O pop-up de lançamento:
popup,popup-heading,popup-close,popup-link - O formulário Get updates by email, no topo de Updates quando os assinantes por e-mail estão ativados (plano Team):
subscribe,subscribe-heading,subscribe-input,subscribe-button,subscribe-status - Reações com emoji, quando estão ativadas:
reactions,reaction,reaction-count - O quadro público de feedback, quando está ativado:
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
Se o seu site envia um cabeçalho Content-Security-Policy, o widget precisa da origem da API em duas diretivas. script-src permite que o script carregue. connect-src permite que ele leia o seu changelog, envie feedback e registre visualizações. Só com a primeira, o elemento aparece e depois fica vazio, o que parece um feed quebrado em vez de uma requisição bloqueada. O pop-up precisa das mesmas duas.
script-src https://api.changeloop.dev; connect-src https://api.changeloop.dev;A partir do widget 0.16.0, que o /widget.js serve, os navegadores atuais não precisam de nenhuma mudança em style-src: o widget entrega seus estilos como uma folha de estilo construída, que o style-src não controla. Builds mais antigos, incluindo os fixados até /widget-v18.js, e navegadores sem folhas de estilo construíveis usam um elemento style, que exige style-src 'unsafe-inline'.
img-src só é necessário se você ativou as imagens no app, em Configurações, Feed público, Imagens. O widget então carrega as imagens direto dos seus hosts de imagem, e uma política que não os lista bloqueia todas elas. Configurações mostra a linha exata com img-src preenchido a partir da sua lista, então copie-a de novo sempre que mudar a lista. Os hosts de capturas de tela do GitHub também precisam de https://github-production-user-asset-6210df.s3.amazonaws.com em img-src, porque um link de captura de tela do GitHub redireciona para lá e o navegador também verifica esse endereço.
Se a sua política define apenas default-src, adicione as duas diretivas e repita as fontes do seu default-src em cada uma. Um script-src ou connect-src substitui o default-src para scripts ou conexões, então deixar de fora as suas próprias fontes as bloquearia.
Adicione a origem às suas diretivas existentes em vez de substituí-las. Configurações, Feed público no app mostra esta linha com a origem certa para a sua conta. Se você não envia esse cabeçalho, não há nada a fazer.
A página de feed hospedada
Também hospedamos uma página simples nesse endereço: seu changelog e seu quadro de roadmap, renderizados a partir dos mesmos dois feeds acima. Não exige login nem nada configurado do seu lado. É também para onde enviamos as pessoas quando um loop se fecha: o comentário Shipped que deixamos em uma issue do GitHub aponta para cá, assim como shippedEntry.link da consulta de envio acima, ambos chegando à entrada entregue com sua própria âncora #entry-ID, que ainda encontra a entrada mesmo que ela tenha ido para uma página posterior.
Trate-a como um recurso alternativo, não a integração. O feed de changelog e o widget continuam sendo a forma de colocar isso no seu próprio site para que pareça seu produto em vez do nosso; esta página serve para quando você ainda não fez isso, e para links de fechamento de loop, que apontam para cá independentemente do que mais você tenha construído.
Seu changelog, dentro do seu produto
O Changeloop escreve cada entrada a partir de um pull request mesclado, guarda para sua revisão e entrega a este widget e a um feed JSON. Grátis para um repositório, sem cartão.
Começar grátis