Робочі процеси викладачів музичних інструментів з автоматичним записом PostHog та користувацькими подіями

KaushalSaathi — це освітня платформа, орієнтована на використання ШІ, призначена для вчителів. Вона може створювати плани уроків, керувати багатоетапним режимом навчання, складати розклади та забезпечувати чат-супровід. Оскільки значна частина цінності продукту досягається через асинхронну обробку інформації, а не просто через перемикання між сторінками, стратегія вимірювання ефективності мусила розглядати завершені завдання як важливі сигнали — а не лише клацання та зміни маршрутів.

Впровадження функцій без спостереження за реальним використанням є поширеною помилкою. Додаткові екрани не обов’язково означають кращі результати. Перш ніж додавати нову функцію, команда потребує доказів того, з чим вже працюють вчителі, де вони стикаються з труднощами та які інтерфейси вони ніколи не відкривають. Можливість спостереження за поведінкою користувачів перетворює вибір функцій з припущень на рішення, ґрунтовані на фактичних даних про використання продукту. Саме цю проблему і мав вирішити PostHog: як насправді вчителі використовують існуючий продукт?

Автозахоплення як безкоштовна база

Автозахоплення охоплює діяльність на рівні DOM без необхідності вручну налаштовувати логіку — кліки, $pageview, $pageleave та межі сеансу. Безумовне використання цього інструменту та розгляд відсутності API-ключа як сигналу вимкнення дозволяють уникнути необхідності налаштовувати облікові записи чи використовувати умовні оператори на кшталт if (enabled) під час локальної розробки та створення форків:

const POSTHOG_KEY = import.meta.env.VITE_POSTHOG_KEY ?? "phc_disabled_no_key_set";
const ENABLED = POSTHOG_KEY !== "phc_disabled_no_key_set";
<PostHogProvider
apiKey={POSTHOG_KEY}
options={{
api_host: POSTHOG_HOST,
autocapture: ENABLED,
capture_pageview: ENABLED,
session_recording: { maskAllInputs: true },
loaded: (ph) => { if (!ENABLED) ph.opt_out_capturing(); },
}}

Автозахоплення відповідає на питання де хтось здійснив навігацію. Воно не відповідає на питання що саме вони завершили. Обробник кліків у DOM ніколи не бачить завершення асинхронних операцій — наприклад, завершення створення плану уроку, закінчення періоду в режимі навчання чи успішного експорту PDF. Жодна з цих дій не створює кліку в DOM, до якого можна під’єднатися, тому за принципом розробки автозахоплення не може їх бачити. Саме через цю прогалину існує другий рівень обробки даних.

Персоналізовані події, які стають метриками

Значущі результати передаються у вигляді користувацьких подій через простий трифункціональний обгортку. Кожен виклик перевіряє значення posthog.__loaded, тому решта додатку ніколи не перевіряє наявність аналітики та не цікавиться тим, чи активне збирання даних:

export function captureEvent(name: string, props?: Record<string, unknown>) {
if (!posthog.__loaded) return;
posthog.capture(name, props);
}

Дві конвенції забезпечують корисність цих подій під час подальших запитів.

Передавайте подію при успіху, а не під час спроби. Збирання даних відбувається на асинхронному шляху успіху, а не всередині обробника кнопки, тому графіки відображають завершену роботу:

const plan = await generateLessonPlan(payload); // resolves only on success
captureEvent("lesson_plan_generated", {
grade: plan.grade, sector: plan.sector, language: plan.language,
});

Додавайте властивості, які стануть ознаками для розбивки даних. Поле такі як grade, language, sector та periodNumber передаються разом із подією під час її відправки. У PostHog вони стають фільтрами та засобами для розбивки даних без додаткових операцій — одна подія може відповісти на запити про «покоління за рівнем», «за мовою» чи «за сектором».

Ключовим інструментом є identifyUser, який виконується один раз з гака автентифікації після успішного входу. Цей виклик пов’язує тимчасовий анонімний ідентифікатор з автентифікованим обліковим записом та додає поля, що визначають роль користувача, тож подальші записи успадковують ту саму інформацію про особу:

posthog.identify(user.id,
{ role: user.role, grade: user.grade, school: user.school });
// on logout: posthog.reset() ← must run before the redirect, or events leak to the next id

Порядок викликів під час виходу має значення. Переадресування до іншої сторінки перед виконанням reset() на спільному пристрої може призвести до того, що наступна сесія буде позначена попередньою ідентичністю. Спочатку виконайте скидання, а потім переходьте далі.

Кожна подія потім надає дані для збереження. Зазвичай використовується підрахунок кількості подій з розбивкою за ім’ям користувача:

• lesson_plan_generated у всьому вікні, згрупований за годинами, створює часову серію з позначенням коли, а також таблицю детальних результатів із ранжуванням хто. Цей єдиний перегляд відображає активних користувачів, бездіяльні облікові записи та концентрацію використання. За замовчуванням ліміт кількості рядків у розбивці становить 25; підвищте його до 50, коли важлива інформація про менш поширені випадки.
• chat_message_sent, обмежений вчорашнім днем та згрупований за годинами, використовує ту саму подію, але у вужчих межах — наприклад, піковий сплеск у другій половині дня близько 15:00, пов’язаний з одним викладачем.

Та сама визначення події, різний діапазон дат та розбивка. Нове запитання стає новим збереженим переглядом, а не новим кодом програми.

Повторна відтворення сеансу для з’ясування причин

Підрахунки пояснюють що та як часто, а не чому. Функція запису залишається увімкненою за замовчуванням при налаштуванні maskAllInputs: true, оскільки вчителі вводять конфіденційні дані учнів та школи. Кліки, навігація, глибина прокрутки та затримки залишаються видимими; значення введених даних маскуються під час запису.

Ситуації, коли повторна перегляд може бути корисною:

• Локалізація витоків даних. Коли сигнал lesson_plan_generated надходить, а pdf_exported — ні для певної групи, підрахунки виявляють витік, а повторна перегляд показує саме той крок експорту, де відбувається вихід користувачів.
• Тихі баги у багатокрокових процедурах. Режим викладання може беззвучно зламатися; користувачі просто припиняють роботу. Повторна перегляд дозволяє відрізнити пошкоджений стан інтерфейсу від заплутаних позначок чи повільної обробки, що спричиняє втрату часу.

Часові шкали активності кожної особи

Як тільки ідентифікація користувача прив’язує записи та повторні відтворення до облікового запису, екран з даними про користувача у PostHog відображається у вигляді часової шкали для цього педагога: які події відбулися, які функції були використані, які сеанси збережені. Практичні застосування включають перевірку того, чи слідує за сигналом registration_completed перший сигнал lesson_plan_generated (що свідчить про належну інтеграцію), перегляд часової шкали складного користувача перед розробкою інтерфейсу відповідно до його шляху використання, або реконструкцію повідомленого багу на основі конкретного сеансу замість покладання на пам’ять.

Об’єднання шарів інформації

Функція Autocapture забезпечує базовий сигнал без додаткових витрат. Налаштовувані події та метрики перетворюють результати функціоналу на ранжовані тайм-серії з розділенням за властивостями. Функція повторного відтворення сеансу надає причинно-наслідкові деталі стосовно певних форм у графіках. Часові шкали осіб дозволяють зменшувати масштаб від загальних даних до окремого викладача. Разом ці шари достатні для визначення того, що потрібно створити на основі спостережуваної поведінки, а не на основі припущень щодо того, як продукт «має» використовуватися.