Реалізація In-App Changelog (історія оновлень) для SaaS-застосунку

SaaS внутрішній changelog

In-app changelog — вбудований журнал змін: користувач бачить нові функції без переходу на зовнішній сайт. Збільшує adoption нових фіч та знижує запити в підтримку.

Готові рішення

Headway — віджет з зовнішнім хостингом changelog. Швидкий старт:

<!-- Вставити в layout -->
<script async src="https://cdn.headwayapp.co/widget.js"></script>
<script>
  var HW_config = {
    selector: "#headway-badge",
    account: "YOUR_ACCOUNT_ID",
    translations: {
      title: "Новое в продукте",
      readMore: "Читать далее",
      footer: "Показать все обновления",
    }
  };
</script>
<span id="headway-badge">Що нового</span>

Beamer — аналог з push-сповіщеннями та сегментацією.

Власна реалізація

model ChangelogEntry {
  id          String           @id @default(cuid())
  title       String
  content     String           @db.Text  // Markdown
  category    ChangelogCategory
  publishedAt DateTime
  isPublished Boolean          @default(false)
  createdAt   DateTime         @default(now())

  reads       ChangelogRead[]
}

enum ChangelogCategory {
  NEW        // нова функція
  IMPROVEMENT // поліпшення
  FIX        // виправлення
  DEPRECATION // застаріває
}

model ChangelogRead {
  userId    String
  entryId   String
  readAt    DateTime @default(now())

  user  User            @relation(fields: [userId], references: [id])
  entry ChangelogEntry  @relation(fields: [entryId], references: [id])

  @@id([userId, entryId])
}

API та компонент

// Непрочитані записи для користувача
export async function getUnreadChangelog(userId: string): Promise<{
  entries: ChangelogEntry[];
  unreadCount: number;
}> {
  const readIds = await db.changelogRead.findMany({
    where: { userId },
    select: { entryId: true },
  });

  const readEntryIds = new Set(readIds.map(r => r.entryId));

  const entries = await db.changelogEntry.findMany({
    where: {
      isPublished: true,
      publishedAt: { lte: new Date() },
    },
    orderBy: { publishedAt: 'desc' },
    take: 10,
  });

  const unreadCount = entries.filter(e => !readEntryIds.has(e.id)).length;

  return {
    entries: entries.map(e => ({
      ...e,
      isRead: readEntryIds.has(e.id),
    })),
    unreadCount,
  };
}

export async function markAllAsRead(userId: string): Promise<void> {
  const unread = await db.changelogEntry.findMany({
    where: {
      isPublished: true,
      reads: { none: { userId } },
    },
    select: { id: true },
  });

  await db.changelogRead.createMany({
    data: unread.map(e => ({ userId, entryId: e.id })),
    skipDuplicates: true,
  });
}

// components/ChangelogPopover.tsx
'use client';

import { useState } from 'react';
import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
import { Badge } from '@/components/ui/badge';
import ReactMarkdown from 'react-markdown';

const CATEGORY_STYLES = {
  NEW: 'bg-green-100 text-green-800',
  IMPROVEMENT: 'bg-blue-100 text-blue-800',
  FIX: 'bg-yellow-100 text-yellow-800',
  DEPRECATION: 'bg-red-100 text-red-800',
};

const CATEGORY_LABELS = {
  NEW: 'Нове',
  IMPROVEMENT: 'Поліпшення',
  FIX: 'Виправлення',
  DEPRECATION: 'Застаріває',
};

export function ChangelogPopover({
  entries,
  unreadCount,
  onOpen,
}: {
  entries: ChangelogEntryWithRead[];
  unreadCount: number;
  onOpen: () => void;
}) {
  const [open, setOpen] = useState(false);

  const handleOpen = (isOpen: boolean) => {
    setOpen(isOpen);
    if (isOpen && unreadCount > 0) {
      onOpen(); // Відмічаємо як прочитані
    }
  };

  return (
    <Popover open={open} onOpenChange={handleOpen}>
      <PopoverTrigger asChild>
        <button className="relative p-2 rounded-lg hover:bg-gray-100">
          <BellIcon className="w-5 h-5" />
          {unreadCount > 0 && (
            <span className="absolute -top-1 -right-1 bg-blue-600 text-white text-xs rounded-full w-5 h-5 flex items-center justify-center">
              {unreadCount > 9 ? '9+' : unreadCount}
            </span>
          )}
        </button>
      </PopoverTrigger>

      <PopoverContent className="w-96 p-0 max-h-[500px] overflow-y-auto" align="end">
        <div className="p-4 border-b">
          <h3 className="font-semibold">Що нового</h3>
        </div>

        <div className="divide-y">
          {entries.map((entry) => (
            <div
              key={entry.id}
              className={`p-4 ${!entry.isRead ? 'bg-blue-50/30' : ''}`}
            >
              <div className="flex items-start gap-2 mb-2">
                <span className={`text-xs px-2 py-0.5 rounded-full font-medium ${CATEGORY_STYLES[entry.category]}`}>
                  {CATEGORY_LABELS[entry.category]}
                </span>
                <span className="text-xs text-gray-500 ml-auto">
                  {entry.publishedAt.toLocaleDateString('uk-UA')}
                </span>
              </div>
              <h4 className="font-medium text-sm mb-1">{entry.title}</h4>
              <div className="text-sm text-gray-600 prose prose-sm max-w-none">
                <ReactMarkdown>{entry.content}</ReactMarkdown>
              </div>
            </div>
          ))}
        </div>
      </PopoverContent>
    </Popover>
  );
}

Admin: управління changelog

// app/admin/changelog/new/page.tsx
export default function NewChangelogEntryPage() {
  return (
    <form action={createChangelogEntry}>
      <Input name="title" placeholder="Заголовок" required />
      <Select name="category">
        {Object.keys(CATEGORY_LABELS).map(k => (
          <option key={k} value={k}>{CATEGORY_LABELS[k as ChangelogCategory]}</option>
        ))}
      </Select>
      <MarkdownEditor name="content" />
      <Input name="publishedAt" type="datetime-local" />
      <CheckboxField name="isPublished" label="Опубліковати одразу" />
      <Button type="submit">Зберегти</Button>
    </form>
  );
}

Розробка in-app changelog з badge, popover та admin-інтерфейсом — 2–3 робочих дні.