Сповіщення (alerts)
Додатковий дозвіл не потрібен
Координація показу екранних сповіщень між аддонами (донати, підписки та подібні оверлеї). Аддон донатної платформи повідомляє, коли його сповіщення почалося і закінчилося; інші аддони (наприклад, музичний плеєр) можуть тимчасово призупиняти себе, поки грає хоча б одне сповіщення.
Цей API не малює UI у StreamKit+. Він лише передає між worker’ами глобальний прапорець «зараз десь іде сповіщення?».
Поняття
| Термін | Значення |
|---|---|
| Продюсер | Аддон, який показує сповіщення — викликає alerts.started() / alerts.ended() |
| Конс’юмер | Аддон, який реагує — викликає alerts.isActive() та/або alerts.onChange(...) |
| Глобально активно | true, поки іде хоча б одне сповіщення від будь-якого аддона |
Лічильники за посиланнями на аддон: на кожен started() потрібен один ended(). Проміжні зміни (1→2 або 2→1 активних сповіщень) не сповіщають підписників — лише переходи 0 → 1+ і → 0.
alerts.started()
Позначає, що цей аддон почав показувати екранне сповіщення.
alerts.started();
// … відтворення сповіщення про донат / підписку …
alerts.ended();
alerts.ended()
Позначає, що цей аддон закінчив одне сповіщення. Якщо активних сповіщень у аддона вже немає — виклик нічого не робить.
alerts.ended();
alerts.isActive()
Повертає, чи повідомляє зараз якийсь аддон про активне сповіщення.
const res = await alerts.isActive();
if (res.success && res.active) {
// пауза музики, приховування HUD тощо
}
Повертає { success: true, active: boolean }.
alerts.onChange(cb)
Підписка на зміни глобального стану показу сповіщень. Повертає { Destroy } для відписки.
| Payload | Коли |
|---|---|
{ active: true } |
Десь почалося перше сповіщення (було тихо → зараз грає) |
{ active: false } |
Закінчилося останнє сповіщення (усі аддони вільні) |
const sub = alerts.onChange(({ active }) => {
if (active) {
pauseMusic();
} else {
resumeMusic();
}
});
// Опційно: синхронізувати поточний стан під час завантаження
const state = await alerts.isActive();
if (state.success && state.active) {
pauseMusic();
}
// пізніше
sub.Destroy();
onChange не викликає колбек з поточним значенням у момент підписки — для початкового стану використовуйте isActive().
Очищення під час життєвого циклу
Коли аддон вимикають, видаляють, перезавантажують (api.restart() / перезапуск у налаштуваннях) або зупиняють після циклу падінь, StreamKit+ скидає всі активні сповіщення, приписані цьому аддону.
Якщо через це глобальний прапорець переходить з активного в неактивний, усі інші запущені аддони отримують { active: false } через onChange.
Продюсеру не обов’язково викликати ended() у addon:prepare-stop для коректності (хост сам очищає лічильники), але виклик ended() перед зупинкою допустимий.
Повний приклад: донатний продюсер + музичний конс’юмер
// Аддон донатної / алерт-платформи
events.On('onDonationAlert', async ({ body }) => {
alerts.started();
try {
await playAlertMedia(body);
} finally {
alerts.ended();
}
});
// Аддон музичного плеєра
let pausedForAlert = false;
alerts.onChange(({ active }) => {
if (active && !pausedForAlert) {
pausedForAlert = true;
pausePlayback();
} else if (!active && pausedForAlert) {
pausedForAlert = false;
resumePlayback();
}
});