QA Guidelines — LQ Tajwid iOS

🎚️ Toggles & Feature Flags

Flip these to test different scenarios. Remote Config values are entered as String in Firebase (booleans are the literal text true/false) and take effect on next app launch. Code flags require a rebuild.

Banner ads — Remote Config

Toggle	Type	Default	Effect
`custom_banner_master_is_enabled_ios`	Remote Config (String)	true	Master switch for the custom (house) banner. Default true → custom banner shows whenever AdMob has no ad → slot is never blank. Set to `"false"` → AdMob-only (slot is blank on no-fill).
`custom_banner_force_only_ios`	Remote Config (String)	false	`"true"` → show only the custom banner and skip AdMob entirely (house-promo mode). `"false"`/unset → normal AdMob-first behavior.
`custom_banner_url_<lang>_ios` `custom_banner_default_url_ios`	Remote Config (String)	empty	Image URL for the custom banner (per-language, with default fallback). Empty → bundled asset `BannerAdsUpgradePro_<lang>` ("Upgrade to Pro+").
`custom_banner_cta_url_<lang>_ios` `custom_banner_cta_url_default_ios`	Remote Config (String)	empty	Where tapping the custom banner goes. Empty → opens the in-app Pro paywall.

Recognized <lang> suffixes: en, id, ar, hi, fr, zh (anything else → en).

Ad units — code flag

Toggle	Where	Default	Effect
`LQRAdUnitId.useTestAdUnitIds`	`LQRAppConstant.swift`	false	Set to `true` → every ad unit resolves to Google's official test IDs (guaranteed-fill "Test Ad"). For QA/dev only. ⚠️ Never ship `true` (zero revenue). Simulators serve test ads automatically even when this is `false`.

Quick scenario matrix
• Normal (default): master=true, force_only=false → real AdMob ads where available, custom banner where not (never blank).
• House-promo: force_only=true → only the custom banner, no AdMob.
• AdMob-only: master=false → no custom banner (slot blank on no-fill).
• Force test ads: useTestAdUnitIds=true (rebuild) → test ads fill everywhere.

🔧 How to change a Remote Config toggle (Firebase)

All the Remote Config toggles above are changed in the Firebase Console — no app update needed. Steps:

Open Firebase Console → pick the LearnQuran / LQ Tajwid project.
Left sidebar → Run → Remote Config.
Find the parameter (e.g. custom_banner_master_is_enabled_ios). If it doesn't exist, click Add parameter and use the exact key name.
Set Data type = String and enter the value as text — for booleans type the literal true or false (not a Boolean type), for numbers type the digits.
Click Save, then Publish changes (top right). Nothing applies until you Publish.
On the device: force-quit and relaunch the app to pull the new values. You may need to relaunch twice (one launch fetches, the next applies).

If the change doesn't show up:

Fetch throttling — Remote Config caches values (a minimum fetch interval). If a change won't appear, fully delete & reinstall the app to clear the cache, then relaunch.
Conditions — make sure you edited the value that applies to your test device (the default value, or the matching condition for your platform/audience), not a non-matching condition.
Before first fetch, the app uses bundled defaults from remote_config_defaults.plist (e.g. custom_banner_master_is_enabled_ios = true). A published Remote Config value overrides that default after fetch + relaunch.

Don't have Firebase Console access? Ask the dev team to publish the value, or test the same behavior locally via the code defaults / the useTestAdUnitIds flag.

📺 How to test ads correctly

Simulator auto-serves AdMob "Test Ad" creatives for the real unit IDs — good for layout/flow, not for real fill.
Real device, production ads: use TestFlight or a debug build with useTestAdUnitIds = false.
Don't hammer ads on one device. Rapidly opening many ad screens can get the device ad-limited by AdMob → you'll see "No ad to show" for a while. It resets on its own (hours–a day). To avoid this during QA, register your device as a test device or set useTestAdUnitIds = true.
Real-ad fill is not 100% — AdMob may return "No ad to show" anytime. That's expected; the custom banner covers it (never blank).

✅ PR #46 — Onboarding redesign + Banner ads + v6.7.17 fixes

feat/onboarding-redesign → main Three areas: the new onboarding intro flow; banner-ads reliability (real AdMob where available, custom fallback that's never blank); and the v6.7.17 bug-fix batch — lesson audio, quiz Back button, iPad play-button size (section C).

Setup

Fresh install (for onboarding) + an upgrade-over-existing pass.
Free account (ads) and Pro/Pro+ account (no ads).
Portrait + landscape; languages EN, ID, AR (RTL), and one of HI/FR/ZH.

A. Onboarding redesign

A1 — Welcome. Fresh launch shows "Welcome to Learn Quran Tajwid" + Get Started. No clipping.

A2 — Slides. NEXT pages through all slides; page indicator advances; content readable. SKIP jumps to the last slide. Smooth full-screen paging.

A3 — Final slide. Shows Get Started + Already Member. Get Started → Overview Quiz / Proceed to Lesson List. Already Member → login. Both paths work.

A4 — Landscape. Rotate during onboarding. Pager stays full-screen, centered, no overlap/clipping.

A5 — Arabic (RTL). Language = Arabic. RTL correct; slide numbers as Arabic-Indic digits (١، ٢، ٣).

A6 — Shown once. Complete onboarding, relaunch. Goes straight to the app.

B. Banner ads

Expected: real AdMob banner where an ad is available; the custom "Upgrade to Pro+" banner where AdMob has no ad. Never blank.

B1 — Every ad screen (free user). Check Course Menu, Theory, Practice, MC quizzes (ABCD 2/4-row, audio MC, choose-audio, multiple-answers), Similar Pronunciation, Points of Articulation, Waqf & Ibtida, and Recitation Test. A banner shows at the bottom of each — never an empty gap.

B2 — Real ad vs custom. Where AdMob fills → real AdMob banner. Where it returns "No ad to show" → custom "Upgrade to Pro+" banner. Slot is always filled.

B3 — Recitation Test. Open a Recitation Test (the original problem screen). Shows a banner (AdMob if available, else custom).

B4 — Layout. Banner is 320×50, centered, pinned bottom; not clipped; correct in portrait and landscape.

B5 — Pro / Pro+. Sign in as Pro and revisit. No banner at all (custom or AdMob) on any screen.

B6 — Tap custom banner. While the custom banner shows, tap it. Opens the configured CTA URL, or the Pro paywall if none set.

B7 — Toggle checks. Per the Toggles matrix: force_only=true → only custom; master=false → AdMob-only; useTestAdUnitIds=true → test ads everywhere.

C. Lesson audio & quiz interaction fixes v6.7.17

Fixes for the v6.7.17 QA reports: silent audio in Bacaan (recitation) and Pilihan Ganda (multiple-choice) on advanced lessons, an unresponsive Back button between questions, and an oversized play button on iPad.

Critical setup for the audio cases
• Audio is download-gated — the bug only appears once a lesson's content is actually downloaded. Download lessons 12–20 first.
• The bug was triggered by Arabic letters in advanced-lesson titles, so also test the app in Arabic and/or Indonesian, not only English.
• Use a real device with downloaded content — the simulator can't fetch lesson audio, so these audio cases can't be reproduced there.

C1 — Bacaan audio, advanced lessons. For each of lessons 12, 13, 14, 15, 17, 19, 20: open the lesson → Recitation / Bacaan test → press play on each item. Every item produces sound.

C2 — Pilihan Ganda audio, advanced lessons. For each of lessons 12, 13, 15, 17, 19, 20: open the Multiple-Choice test → play the question / option audio. Audio plays. (Lesson 14 has no MC test — skip.)

C3 — Regression: lessons that always worked. Spot-check audio on lessons 1–11 and 16, 18 in both Bacaan and Pilihan Ganda. Still plays — no regression.

C4 — Regression: other audio. Spot-check Practice, Theory, and the lesson / general tests on an advanced lesson. Audio plays.

C5 — Back button, same-type questions (the tricky case). In a Pilihan Ganda test, answer an option and let it advance; continue until two consecutive questions are the same type. On every next question the Back button shows its glow/highlight and is tappable immediately.

C6 — Back button, mixed types & feedback window. Play through a full quiz mixing question types. Back is tappable at the start of each new question; only briefly non-tappable during the red/green answer feedback.

C7 — Play button size on iPad. On an iPad: open the "Kuis Umum" (Placement Test) audio questions and a lesson Multiple-Choice test; rotate portrait↔landscape and move between several questions repeatedly. The play button stays a normal, fixed size — never balloons or overlaps other controls.

C8 — Play button on iPhone (regression). Same screens on iPhone. Play button is its normal size; unchanged.

Regression

App launch, lesson list, navigation normal; no crash opening Course Menu.
Interstitial ads after test/practice still appear (free user).
Language switch mid-session doesn't break banners or onboarding.

Sign-off

Area	Pass/Fail	Device / OS	Notes
Onboarding (A1–A6)
Banners (B1–B7)
Lesson audio (C1–C4)
Quiz Back button (C5–C6)
Play button size (C7–C8)
Regression

PR #47 — TBD

Add the test plan for PR #47 here when it opens: scope, setup, test cases, relevant toggles, sign-off.

PR #48 — TBD

Add the test plan for PR #48 here when it opens.