El widget incrustable
Si prefieres no construir nada, añade estas dos líneas. El widget es un custom element que renderiza en un shadow root, así que ni hereda tus estilos ni se filtra en ellos.
<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 atributos son obligatorios. data-public-id es tu id de feed, data-api es el origen desde el que carga el widget. Si falta alguno, el elemento escribe un error en la consola y no renderiza nada, que es lo primero que hay que comprobar si ves un espacio vacío donde debería estar.
Añade data-theme="dark" al elemento para renderizarlo en oscuro; tu página puede alternarlo en tiempo de ejecución. Para un estilo más profundo, el widget expone propiedades CSS personalizadas (--changelogapp-text, --changelogapp-bg, --changelogapp-accent y más) y nombres ::part(), que defines en tu propia hoja de estilos. La app previsualiza ambos temas en vivo en Ajustes, Feed público.
Añade data-repos para mostrar solo algunos de tus repositorios, por ejemplo el changelog de un producto en el sitio de ese producto cuando varios productos comparten una cuenta. El valor es una lista separada por comas de nombres completos, owner/repo; un nombre sin propietario no coincide con nada y muestra un feed vacío sin error. Se tienen en cuenta hasta diez repositorios. Un widget acotado muestra solo Updates y Feedback, porque el roadmap no tiene vista por repositorio, y el feedback se sigue archivando donde apunta el destino de feedback de tu equipo. En Ajustes, Feed público hay un selector que escribe el atributo por ti.
Renderiza tres pestañas en este orden: Novedades, Roadmap y Feedback. Las dos primeras leen los feeds de arriba. La tercera envía al endpoint de abajo y guarda cada id de envío en localStorage, así que quien lo visita puede volver y ver qué pasó con lo que envió.
El script se sirve versionado. /widget.js siempre sirve el build más nuevo y se cachea una hora, así que un release llega a tus visitantes sin que toques nada. /widget-vN.js fija un build: una vez servido un número de versión, sus bytes nunca vuelven a cambiar, y se cachea un año. Fíjala si prefieres adoptar los cambios a propósito.
Carga exactamente un script del widget por página
Las dos URL son alternativas, no capas. Ambas registran el mismo nombre de custom element, y un navegador solo deja registrar un nombre una vez por documento: gana el script que se ejecute primero, durante toda la vida de la página, y el segundo queda inerte. Así que una página con /widget.js y /widget-v5.js a la vez renderiza lo que el navegador ejecutara primero por azar, algo que no controlas; añadir /widget-v5.js junto a un /widget.js existente para fijar la versión no hace nada. Suele ganar el build más antiguo, porque ya está en caché.
Cuando pasa esto, el widget escribe un aviso en la consola nombrando ambos builds, así que no tienes que adivinar. No puede hacer más que avisar: cuando corre la segunda copia, la primera ya se ha quedado con el nombre. La solución es siempre sustituir la etiqueta script en vez de añadir otra, y lo mismo si un gestor de etiquetas o un parcial te inyecta una. Para pasar del build continuo a uno fijado, cambia el src.
Pop-up de novedades
Añade data-mode="popup" y el elemento no renderiza pestañas. Cuando un visitante tiene algo nuevo que ver, muestra una tarjeta pequeña con tu última versión, y si no, no muestra nada. data-mode no distingue entre mayúsculas y 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>
En pantallas anchas, la tarjeta se coloca en la esquina inferior izquierda, porque la inferior derecha suele ser del botón de un chat. En pantallas de menos de 480px de ancho ocupa todo el ancho y tapa el botón del chat hasta que se cierra. Se abre en la capa superior del navegador, así que el overflow, el transform o el z-index de un elemento padre no pueden recortarla ni taparla. Para moverla, aplica estilos a ::part(popup).
Cada versión se muestra una sola vez. La tarjeta aparece cuando el visitante tiene entradas que aún no ha visto. Muestra la más reciente, con un contador si son varias, y las da por vistas en el momento en que aparece. La siguiente carga de página no muestra nada hasta que publiques de nuevo.
Una primera visita no muestra nada: el widget solo anota hasta dónde llega tu changelog, para que los usuarios que ya tienes no reciban noticias viejas el día que lo añades. La tarjeta empieza con tu próxima versión. Si un visitante ya leyó una versión en el widget integrado, no se le vuelve a mostrar.
Lo que ha visto un visitante se guarda en localStorage, por dominio, en su navegador. No hay cookies ni se envía nada a un servidor para esto. Borrar los datos del sitio, usar otro navegador u otro de tus dominios vuelve a empezar desde una primera visita. Si el navegador bloquea el almacenamiento, cada visita cuenta como primera visita y la tarjeta nunca se muestra.
data-changelog-url es opcional. Con una dirección http o https, la tarjeta incluye un enlace "See all updates" hacia ella, normalmente tu página alojada o tu propia página de changelog. Con cualquier otro valor, no se dibuja ningún enlace. data-theme y data-repos funcionan exactamente igual que en el widget integrado.
La tarjeta nunca toma el foco ni bloquea la página: es una región con etiqueta, no un diálogo. Se cierra con su botón de cierre, o con Escape mientras el foco está dentro de la tarjeta. Escape en cualquier otra parte de tu página queda para tu propio código.
La regla de un solo script del widget por página sigue vigente. El pop-up y el widget integrado pueden compartir página: carga el script una vez y añade ambos elementos, y se ponen de acuerdo sobre lo que el visitante ya ha visto.
Los builds fijados hasta /widget-v18.js son anteriores al pop-up. Ignoran data-mode y renderizan las pestañas integradas, así que usa /widget.js o un build fijado más reciente.
En la app, Ajustes, Feed público tiene este fragmento listo para copiar, con tu id de feed, tu tema y el alcance de repositorios ya rellenados. Las vistas de la tarjeta y los clics en su enlace "Learn more" aparecen en Analytics como cifras propias.
Reacciones con emoji
Los lectores pueden reaccionar a una entrada sin escribir nada. Con las reacciones activadas, cada entrada termina con una fila de cinco, 👍 🎉 ❤️ 🚀 👀, cada una con su contador. La fila aparece en el widget integrado, en la tarjeta del pop-up de novedades y en la página de feed alojada.
Las reacciones están desactivadas hasta que las actives en la app, en Ajustes, Feed público. Tu código de inserción no cambia: el widget lee el interruptor desde tu feed, así que la fila aparece y desaparece con él. Al desactivar las reacciones se oculta la fila pero se conservan los contadores, así que vuelven si las activas de nuevo. Los builds fijados anteriores a las reacciones nunca muestran la fila.
Cada lector puede dar a una entrada cada reacción una sola vez, y si la pulsa de nuevo, la retira. El widget distingue a los lectores por un id aleatorio que crea en el navegador con el primer clic, no por una cuenta ni una dirección de correo. Guardamos solo un hash de ese id combinado con tu equipo, de modo que el mismo navegador deja hashes sin relación en dos changelogs distintos.
Los contadores son aproximados: una señal amistosa, no un voto. Si se borra el almacenamiento del navegador o se abre una ventana privada, alguien puede reaccionar otra vez, así que nunca tomes una decisión importante basándote en ellos. Los contadores de tu feed también pueden ir unos minutos por detrás, porque el feed está en caché, pero quien hace clic ve su propia reacción contada al instante. En la app, la pestaña Publicado de la bandeja de revisión muestra el total de cada entrada.
Al reaccionar se guardan dos cosas en el localStorage del visitante, nunca en una cookie. changelogapp-widget:reader-id contiene el id aleatorio, uno por navegador y origen de sitio. changelogapp-widget:reactions: seguido del id de tu feed contiene las reacciones que eligió este navegador, hasta 200 entradas, las que reaccionó más recientemente. La página alojada guarda esas mismas dos bajo su propia dirección. Si el navegador bloquea el almacenamiento, reaccionar sigue funcionando durante esa visita a la página y no se recuerda después.
Para dar estilo a la fila, usa ::part(reactions), ::part(reaction) para cada botón y ::part(reaction-count) para su número, todos listados en Estilos más abajo. Un contador en cero no muestra número. Un botón pulsado lleva aria-pressed="true" y se dibuja con un anillo del color de tu --changelogapp-accent y texto en negrita. ::part() no puede seleccionar por ese atributo, así que define --changelogapp-accent para cambiar el aspecto de un botón pulsado.
Tablero público de feedback
El tablero permite a los lectores ver lo que otras personas han pedido y votarlo. Con el tablero activado, la pestaña Feedback se abre con tus peticiones más votadas, cada una con su estado, y el formulario de siempre queda debajo.
El tablero está desactivado hasta que lo actives en la app, en Ajustes, Feed público. Tu código de inserción no cambia: el widget lee el interruptor desde tu feed. Al desactivar el tablero se oculta, pero se conservan tus peticiones y sus votos. Vive en la pestaña Feedback, así que un widget que no muestra esa pestaña tampoco muestra el tablero.
El tablero muestra solo lo que tú escribes. El feedback de un visitante nunca llega a él por sí solo: tú decides qué peticiones van al tablero y tú escribes el título y la descripción de cada una, en la página Feedback board de la app. Puedes crear una petición a partir de un mensaje que envió un visitante o publicar una idea propia, y el tablero nunca muestra el mensaje ni la dirección de correo del visitante. El tablero muestra tus 100 peticiones principales, y un equipo puede tener hasta 500.
Cada petición tiene uno de cinco estados: En estudio, Planificada, En curso, Publicada o Rechazada. Si vinculas una petición a una novedad, pasa sola a Publicada cuando se publica esa novedad, o al instante si ya está publicada. Una petición creada a partir de un mensaje de un visitante también pasa a Publicada cuando se publica una novedad que da respuesta a ese mensaje.
Cada navegador tiene un voto por petición en cada sitio, y si vuelve a hacer clic, lo retira. La votación se cierra cuando una petición está Publicada o Rechazada, aunque quien ya votó todavía puede retirar su voto. Los votos son una señal, no un recuento de personas: si se borra el almacenamiento del navegador o se abre una ventana privada, alguien puede votar otra vez, así que úsalos para ver qué le importa a la gente, nunca para zanjar una decisión importante. Los contadores que ven otros visitantes pueden ir un poco por detrás, mientras que quien vota ve el nuevo contador exacto.
Al votar se guardan dos cosas en el localStorage del visitante, nunca en una cookie. changelogapp-widget:votes: seguido del id de tu feed enumera las peticiones en las que ha votado este navegador, hasta las 200 más recientes. changelogapp-widget:reader-id es el id aleatorio que usan las reacciones, uno por navegador y origen de sitio, así que votar no crea nada nuevo si el visitante ya ha reaccionado. Guardamos solo un hash de ese id combinado con tu equipo, nunca el id en sí, de modo que el mismo navegador deja hashes sin relación en dos changelogs distintos. No guardamos la dirección IP del visitante con un voto. Si el navegador bloquea el almacenamiento, votar sigue funcionando durante esa visita a la página y no se recuerda después.
El tablero nunca aparece en el pop-up de novedades, ni tampoco en un widget limitado con data-repos, porque abarca a todo tu equipo. Tu página de changelog alojada tiene una pestaña Requests con el mismo tablero, un filtro por estado y votos que cuentan igual. El tablero también es un JSON público, en GET /v1/public/YOUR_PUBLIC_ID/board.json en la misma API, que responde 404 mientras el tablero está desactivado.
Para dar estilo al tablero, usa ::part(board) para el bloque entero y ::part(board-heading) para su encabezado, y luego las partes de cada petición, todas listadas en Estilos más abajo. El botón de voto, ::part(board-vote), lleva aria-pressed="true" cuando este navegador ya ha votado, y entonces se dibuja con un anillo del color de tu --changelogapp-accent. ::part() no puede seleccionar por ese atributo, así que define --changelogapp-accent para cambiar el aspecto de un voto contado.
Estilos
El widget se renderiza en un shadow root, así que la mayor parte de tu hoja de estilos no llega a su interior. Las propiedades heredadas siguen entrando donde el widget no define las suyas, y también las propiedades personalizadas de abajo, definidas en el elemento o en un ancestro. Para cualquier otra cosa, usa los nombres ::part() de abajo. Ambas listas son una interfaz estable: una vez publicado un nombre, nunca se renombra.
Propiedades 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
Etiquetas en forma de píldora. Una etiqueta con color lo usa como fondo, y en ambos temas el color del texto se elige para que se lea sobre ese fondo, con 4.5:1 o más. Se prefiere el blanco siempre que alcance ese contraste. Un color que el widget no pueda leer como un valor RGB sólido no recibe color de texto elegido y mantiene el predeterminado del tema. Para elegir tú el color del texto, en cualquiera de los dos temas, define --changelogapp-pill-text. Una regla ::part(entry-tag) gana sobre todo lo demás, así que si defines un fondo ahí, define también color. --changelogapp-pill-bg es el fondo de una etiqueta que no tiene color. Los builds fijados hasta /widget-v18.js mantienen el texto blanco en las píldoras del tema claro.
Partes
- Entradas del changelog:
month-heading,entry,entry-date,entry-tag,entry-title,entry-body,entry-link,timeline-dot,entry-image,entry-header-image - Dentro del cuerpo de una entrada:
entry-body-heading,entry-body-paragraph,entry-body-list,entry-body-list-item,entry-body-link,entry-body-code - El contador de no leídas en la pestaña Updates:
unread-badge - El pop-up de novedades:
popup,popup-heading,popup-close,popup-link - El formulario "Get updates by email", arriba de Updates cuando los suscriptores por email están activados (plan Team):
subscribe,subscribe-heading,subscribe-input,subscribe-button,subscribe-status - Reacciones con emoji, cuando están activadas:
reactions,reaction,reaction-count - El tablero público de feedback, cuando está activado:
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
Si tu sitio envía una cabecera Content-Security-Policy, el widget necesita el origen de la API en dos directivas. script-src permite que el script se cargue. connect-src le permite leer tu changelog, enviar feedback y registrar vistas. Con solo la primera, el elemento aparece y luego se queda vacío, lo que parece un feed roto en vez de una petición bloqueada. El pop-up necesita las mismas dos.
script-src https://api.changeloop.dev; connect-src https://api.changeloop.dev;Desde el widget 0.16.0, que sirve /widget.js, los navegadores actuales no necesitan ningún cambio en style-src: el widget entrega sus estilos como una hoja de estilos construida, que style-src no controla. Los builds anteriores, incluidos los fijados hasta /widget-v18.js, y los navegadores sin hojas de estilo construibles usan un elemento style, que necesita style-src 'unsafe-inline'.
img-src solo hace falta si has activado las imágenes en la app, en Ajustes, Feed público, Imágenes. El widget carga entonces las imágenes directamente desde tus hosts de imágenes, y una política que no los incluya las bloquea todas. Ajustes muestra la línea exacta con img-src ya rellenado a partir de tu lista, así que vuelve a copiarla cada vez que cambies la lista. Los hosts de capturas de GitHub necesitan además https://github-production-user-asset-6210df.s3.amazonaws.com en img-src, porque un enlace a una captura de GitHub redirige ahí y el navegador también comprueba esa dirección.
Si tu política define solo default-src, añade ambas directivas y repite en cada una las fuentes de tu default-src. Un script-src o un connect-src sustituye a default-src para scripts o conexiones, así que dejar fuera tus propias fuentes las bloquearía.
Añade el origen a tus directivas existentes en vez de reemplazarlas. En la app, Ajustes, Feed público muestra esta línea con el origen correcto para tu cuenta. Si no envías esa cabecera, no hay nada que hacer.
La página de feed alojada
En esa misma dirección alojamos también una página sencilla: tu changelog y tu tablero de roadmap, renderizados desde los mismos dos feeds de arriba. No necesita inicio de sesión ni ninguna configuración por tu parte. También es adonde devolvemos a la gente cuando se cierra un ciclo: el comentario Shipped que dejamos en un issue de GitHub enlaza aquí, y también shippedEntry.link desde la consulta de estado de arriba, ambos llegando a la entrada publicada con su propio ancla #entry-ID, que sigue encontrando la entrada aunque ya haya pasado a una página posterior.
Trátala como una alternativa, no como la integración. El feed del changelog y el widget siguen siendo la forma de meter esto en tu propio sitio para que parezca tu producto y no el nuestro; esta página es para mientras no lo hayas hecho, y para los enlaces de cierre de ciclo, que apuntan aquí sin importar qué más hayas construido.
Tu changelog, dentro de tu producto
Changeloop redacta cada entrada a partir de un pull request fusionado, la retiene para que la revises y la sirve a este widget y a un feed JSON. Gratis para un repositorio, sin tarjeta.
Empezar gratis