Skip to main content

Reading Sessions vs Activity Days

Most Quran reader clients should use both concepts when a signed-in user reads, but they answer different product questions.

Reading Sessions​

Reading Sessions answer: where should this user resume reading?

Use them for "Continue reading" and "Recently read" UX. They store the latest Surah/Ayah location and recent reading history, not daily progress totals. The backend updates the most recent session when it was touched within the last 20 minutes; otherwise, it creates a new session.

Activity Days​

Activity Days answer: what reading progress should count for this day?

Use them for streaks, goals, and calendar-style progress. For Quran reading, the client credits active reading time and read ranges to an activity day. The endpoint docs below are the source of truth for the current request fields and examples.

When A User Reads Quran​

  • Use Reading Sessions to save the user's current position for resume/recently-read UX (Surah/Ayah location).
  • Use Activity Days to credit time/ranges toward streaks, goals, and activity calendar progress.

Quran.com's reader implementation follows this high-level pattern:

  1. When a verse becomes visible, queue the verse key and debounce POST /v1/reading-sessions with the latest chapterNumber and verseNumber.
  2. Track active reading seconds while the reader tab is focused.
  3. Every few seconds, merge queued verse keys into valid ranges.
  4. Send POST /v1/activity-days to credit the active reading time and read ranges.
  5. Clear local reading-progress caches after the sync so streak/activity views can refetch current data.