Vòng đời và quyền

host opens the WebView ─▶ bridge injected (window.CatholicMiniApp exists before your JS runs)
                         ─▶ your page loads and renders
                         ─▶ host sends CatholicMiniApp:nativeReady  (after every page load)
your page calls sdk.ready() ─▶ host removes its loading overlay
                         …  user works in your mini app; themeChange / resume / pointsUpdate events
user taps ✕, or you call sdk.close() ─▶ host closes the mini app

getSDK() is safe at module level. The bridge is injected before any page script runs.
Loading overlay. The host shows a branded overlay until your page finishes loading or calls sdk.ready(), whichever comes first. If the overlay is still up after 15 seconds (READY_TIMEOUT), the host removes it and shows a "took too long to load" warning. Call sdk.ready() once your first meaningful screen is painted.
nativeReady fires on every page load (first load, reload from the ⋮ menu, recovery after the OS killed the WebView), not only once. See whenNativeReady.
Your page can be reloaded. Keep state you care about in storage, not only in memory.

Permissions

Most bridge methods are gated by a permission. The user grants or refuses it per mini app.

Permission	Unlocks
`user.profile`	`getUser`
`user.email`	reserved: `getUser` returns no email today
`storage`	`storage.get` / `set` / `remove` / `clear`
`points.read`	`getPoints`
`points.earn`	`earnPoints`
`ui.toast`	`showToast`
`ui.share`	`share`
`navigation`	`navigate`
`deeplink`	`createShareLink`, `shareContent`
`camera.scan`	`scanQr`

No permission needed: getSDKVersion, getLocale, getTheme, getDeviceInfo, getSafeArea, showAlert, ready, close, setStatusBarStyle, setTextSelectable, setScrollbarVisible.

How consent works:

Declare the permissions you need when your mini app is registered with i-Catholic. The user can then be asked when the mini app opens.
An undeclared permission is asked just in time. The call is held while the prompt is on screen, then continues if the user allows.
A refusal rejects a Promise method with PERMISSION_DENIED. It silently drops a fire-and-forget method (showToast, navigate): no error reaches your page. The refusal is remembered until the mini app is closed, so the user is not asked again in a loop.
Always handle PERMISSION_DENIED. Your mini app should still work, with less, when the user says no.

PERMISSIONS and PERMISSION_GROUPS are exported if you want to render the list yourself.

Permissions​

Permissions