This page documents how GABLVM integrates with the Quran Foundation API to power the Sign in with Quran.com feature, the My Quran Account dashboard, the Quran Player, and the Tafsir Lab. The integration is built on the official Quran Foundation developer platform and the production OAuth2 endpoints.
What we use, by API category
Content APIs
- Verses and recitations. Used to render the Quran text and audio in the Quran Player. More than twenty reciter sources are streamed directly from the verified high-quality endpoints, across verse-by-verse and chapter playback modes. The Quran Foundation team adds and rotates reciters over time, so the live dropdown is the authoritative count. Five additional full-surah reciters (Abdullah Awad al-Juhani, Ali Abdur-Rahman al-Huthaify, AbdulWadood Haneef, Badr Al Turki, and the combined Sudais and Shuraym recitation) are streamed directly from quranicaudio.com, the same audio host the Quran Foundation endpoints point to. They are available in chapter playback only and do not carry the English translation.
- Tafsir. Used to power the Tafsir Lab with three English tafsirs (Tafsir Ibn Kathir abridged, Maarif Al-Quran, and Tazkirul Quran). The Lab is named for our transparent presentation of API quirks: when consecutive verses share commentary we render it once with the verse range it applies to, and when a verse has no commentary in the chosen tafsir we say so explicitly so a screen reader user is not left wondering whether something is missing or just slow.
- Audio (English narration). Used for the optional English audio translation alongside Arabic recitation. This is real spoken audio rather than text-to-speech, which keeps the meaning delivered with the same clarity and pacing as the recitation.
User APIs
- Bookmarks (collections). Bookmarked verses sync to the user's default Quran.com collection. Adding a bookmark on GABLVM saves to Quran.com immediately; bookmarks created in the Quran.com mobile app appear here on next page load.
- Reading sessions. Each listening session above eight seconds logs a reading session to Quran.com, which feeds the streak and activity-day records.
- Streaks. The user's active or most recent reading streak is shown on the My Quran Account page.
- Goals (today's plan). If a user has set a daily reading goal via the Quran.com mobile app, today's progress against the goal renders here in real time.
- Activity days. Today's pages, verses, and seconds read are surfaced on the same page so the user has an immediate signal that their session was logged, rather than waiting for the streak to roll over at midnight UTC.
- Notes. Verse notes are private to the user's Quran.com account. Notes written on GABLVM sync to Quran.com; notes written on Quran.com appear here.
Authentication
OAuth2 authorization_code with PKCE against oauth2.quran.foundation. Two integration modes:
- Sign in with Quran.com (Architecture B, shipped May 7, 2026). Anonymous visitors land on /user/login, choose Sign in with Quran.com, complete the OAuth handshake on Quran.com, and are returned to GABLVM as a fully authenticated user. No separate GABLVM password.
- Connect after the fact. An existing GABLVM user can link their Quran.com account from /quran/my-account, which performs the same OAuth handshake but ties the QF identity to the existing GABLVM user record.
We use the documented x-auth-token plus x-client-id authentication scheme for User API calls. Token storage is encrypted at rest in Drupal user data. The integration uses the externalauth contrib module for identity binding.
Resilience and performance
The dashboard at /quran/my-account fires its six per-user QF API calls concurrently as Guzzle promises rather than sequentially, capping page render at the slowest single call. Worst-case render dropped from approximately sixty seconds to approximately twelve seconds.
Per the Quran Foundation team's recommendation following the May 7 to 8 2026 Neon database outage, we apply request timeouts (ten seconds per call), retry server-side errors (5xx) up to two times with exponential backoff and jitter, and do not retry client-side errors (4xx). When a section fails after retries, we render a polite "temporarily unavailable" placeholder for that section while keeping the rest of the dashboard usable.
Accessibility
All Quran Foundation integration surfaces are designed screen-reader-first and meet WCAG 2.2 AA with zero violations. Key accessibility features:
- The Quran Player supports the iOS Magic Tap gesture (two-finger double-tap) for play and pause, including when the GABLVM tab is in the background, via the iOS Media Session API.
- Every control on the dashboard, the Quran Player, and the Tafsir Lab is reachable from the keyboard alone.
- Screen reader announcements are tuned to avoid double-reads: verse numbers and surah names announce once, decorative content is hidden from the accessibility tree, and progress updates do not steal focus during playback.
- The connect flow, the authentication handoff, and the dashboard all narrate cleanly with VoiceOver, JAWS, and NVDA.
Reporting issues
If you find an integration issue, write to [email protected]. For security disclosures specifically, see our security policy.