Social - Notifications (Logic)

Purpose

• Gửi đúng thông báo, đúng thời điểm để tăng quay lại học mà không gây spam.
• Tách rõ thông báo engagement nudges và thông báo hệ thống/giao dịch.

DOL English Web V2 Baseline

• Channels hỗ trợ:
  • in-app notification center,
  • web push,
  • email,
  • Zalo.
• User có thể bật/tắt từng kênh độc lập.
• Unsubscribe theo kênh chỉ ảnh hưởng kênh đó.

Engagement Reactivation Logic

• Reactivation stages:
  • mất streak,
  • 1 tuần không học,
  • 1 tháng không học,
  • 1 năm không học.
• Stage send policy:
  • mỗi stage chỉ kích hoạt 1 lần cho mỗi chuỗi vắng học.
  • sau mốc 1 năm, tiếp tục nhắc định kỳ mỗi 3 tháng nếu user chưa quay lại học.
• Nếu user vượt nhiều stage trước lần gửi đầu tiên:
  • chỉ gửi stage cao nhất.
• Nếu user quay lại và hoàn thành >=1 bài:
  • reset chain reactivation ngay.
• Chuỗi nhắc định kỳ 3 tháng chỉ dừng khi:
  • user quay lại và hoàn thành >=1 bài, hoặc
  • user unsubscribe ở kênh tương ứng.
• Nếu user chỉ mở notification nhưng không làm bài:
  • không có follow-up đặc biệt,
  • governor vẫn tiếp tục theo logic stage hiện tại.
• Reminder -> recommendation handoff:
  • khi user click reminder vào nền tảng, payload mang reactivation_intent_stage + seed context (nếu có),
  • recommendation set đầu phiên dùng one-time seed boost để có ít nhất 1 quick-win item bám intent (khi inventory cho phép),
  • boost kết thúc sau attempt đầu tiên hoặc hết session.

Governor (Anti-spam)

• Cap 1/day áp dụng cho engagement nudges.
• Cap unit: theo từng kênh.
• Domain-specific notification rules (ví dụ Vocabulary) phải đi qua governor này trước khi gửi.
• Nếu có nhiều cap đồng thời, hệ thống dùng ngưỡng nghiêm ngặt hơn.
• Nếu cùng ngày có nhiều trigger engagement:
  • ưu tiên trigger có return-risk cao hơn.
• Trigger không được gửi vì cap:
  • queue sang ngày hợp lệ tiếp theo nếu trigger còn hiệu lực.
• Multi-channel send:
  • gửi đồng thời trên tất cả kênh đang bật.
• Unsubscribe scope:
  • unsubscribe theo kênh nào thì chỉ dừng kênh đó,
  • các kênh còn lại vẫn tiếp tục nếu còn bật.

Retry & Delivery

• Retry chỉ trên kênh fail, dừng khi đạt stop-condition.
• Default retry schedule:
  • +5m, +30m, +2h (tối đa 3 lần).
• Quiet hours:
  • không gửi 22:00-07:00 (theo local timezone),
  • dời lịch sang 08:00 nếu rơi vào khung yên lặng.
• Nếu user đã quay lại học từ một kênh:
  • dừng retry/các sends còn lại của cycle hiện tại.

AI Score-ready Notification

• Luôn tạo entry trong Notification center.
• Có thể gửi thêm toast/push 1 lần (one-shot) nếu user bật kênh.
• Không nhắc lại lần 2 cho cùng sự kiện score-ready.
• Deeplink đi thẳng tới task/result liên quan.
• AI panel/chat vẫn on-demand (không auto-open).

AI Tutor Daily Required Reminder (7-day plan)

• Scope:
  • chỉ áp dụng cho AI Tutor 7-day plan và chỉ cho required item theo ngày.
  • tách biệt khỏi chuỗi Engagement Reactivation theo stage.
• Channel + timing:
  • dùng in-app + web push (nếu web push khả dụng),
  • 1 khung giờ cố định theo local timezone của user,
  • tối đa 1 reminder/ngày cho flow này.
• Permission fallback:
  • nếu web push bị tắt/không khả dụng thì chỉ gửi in-app,
  • không fallback sang email/Zalo cho reminder này.
• Stop/skip rule:
  • trước giờ gửi, luôn check required đã hoàn thành chưa,
  • nếu đã hoàn thành thì skip gửi hôm đó,
  • nếu user submit required sau khi đã gửi, dừng reminder trong ngày ngay lập tức.
• Login/device consistency:
  • nếu user không đăng nhập ở giờ gửi, không gửi catch-up trong cùng ngày,
  • lần đăng nhập tiếp theo chỉ hiển thị trạng thái required hôm nay chưa xong,
  • trạng thái reminder là account-level: hoàn thành trên 1 thiết bị thì dừng nhắc trên mọi thiết bị/kênh trong ngày.
• Time/day semantics:
  • đổi timezone chỉ áp dụng từ ngày kế tiếp,
  • day boundary dùng local 00:00,
  • completion attribution dùng submit timestamp.
• Delivery policy:
  • reminder này kế thừa quiet-hours của hệ thống notification,
  • không tạo retry/same-day resend cho daily required reminder.
• Deeplink behavior:
  • click reminder mở Practice Management,
  • auto highlight required item của ngày hiện tại.
• Required unavailable fallback:
  • nếu required item hôm nay bị unavailable, hệ thống auto thay bằng ladder A -> B -> C,
  • hiển thị notice ngắn để user biết đã thay bài.

Content Governance

• Quy trình template: Draft -> Review -> Publish.
• Marketer là role duyệt cuối.
• V2 đầu dùng 3-4 template đã duyệt, random xoay vòng.
• A/B test nâng cao: deferred phase sau.
• Nếu template gây tín hiệu xấu (ví dụ unsubscribe spike):
  • auto-disable template,
  • fallback sang safe template.
• Content rule for long-absence stage:
  • mốc 1 năm và chu kỳ mỗi 3 tháng dùng copy đơn giản, tập trung CTA quay lại làm bài/luyện tập.

Data Contracts

• notification_type = engagement | transactional | system.
• notification_channel = in_app | web_push | email | zalo.
• engagement_cap_daily = 1_per_channel.
• engagement_priority_rule = highest_return_risk_first.
• engagement_overflow_policy = queue_next_eligible_day.
• reactivation_stage_send_mode = one_shot_per_stage.
• reactivation_long_absence_recurrence = every_3_months_until_return_or_channel_unsubscribe.
• reactivation_intent_stage = lost_streak | inactive_1w | inactive_1m | inactive_1y | inactive_q3_repeat.
• reactivation_seed_program_id = optional_string.
• reactivation_seed_skill_id = optional_string.
• reactivation_entry_session_id = string.
• reactivation_recommendation_seed_ttl = first_set_in_session.
• ai_score_ready_delivery = center + optional_one_shot_toast_push.
• ai_tutor_daily_required_scope = active_plan_required_only.
• ai_tutor_daily_required_channels = in_app + web_push.
• ai_tutor_daily_required_daily_cap = 1.
• ai_tutor_daily_required_slot = fixed_local_time.
• ai_tutor_daily_required_permission_fallback = in_app_only_if_web_push_unavailable.
• ai_tutor_daily_required_not_logged_in_policy = no_same_day_catchup.
• ai_tutor_daily_required_stop_rule = stop_same_day_on_required_submit.
• ai_tutor_daily_required_pre_slot_check = skip_if_required_already_completed.
• ai_tutor_daily_required_consistency_scope = account_day_cross_device.
• ai_tutor_daily_required_timezone_change_effective = next_local_day.
• ai_tutor_daily_required_day_boundary = local_00_00.
• ai_tutor_daily_required_deeplink = practice_management_highlight_today_required.
• ai_tutor_required_unavailable_policy = auto_replace_a_b_c_with_notice.
• ai_tutor_required_completion_attribution = submit_timestamp.

Analytics

• notif_sent, notif_delivered, notif_failed, notif_retry.
• notif_click_to_attempt_start.
• notif_click_to_first_recommendation_render.
• notif_click_to_attempt_start_after_seed.
• notif_unsubscribe_by_channel.
• notif_template_auto_disabled.
• ai_score_ready_open_rate.

Change log

• 2026-02-22: Bổ sung contract handoff từ reminder click sang recommendation set đầu phiên (reactivation intent stage + optional seed program/skill, TTL 1 set/session).
• 2026-02-18: Chuẩn hóa reactivation governor theo stage, cap theo kênh, retry/quiet-hours, score-ready one-shot và governance template Draft->Review->Publish.
• 2026-02-18: Bổ sung rule riêng cho AI Tutor daily required reminder (scope, cap, timing, permission fallback, no catch-up, cross-device stop, day-boundary, deeplink highlight, unavailable fallback).