Bắt đầu nhanh

Trang này đưa bạn từ con số không đến một mini app biết nói chuyện với ứng dụng i-Catholic. Bạn cần: một dự án web dùng bundler (Vite, esbuild, ...) và Node. SDK không có phụ thuộc runtime và chỉ phát hành dạng ESM. Gói gốc không bao giờ nhập React, nên Vue, Svelte hay JavaScript thuần đều dùng được; chỉ khi muốn hooks mới cần React 18 trở lên.

Ba việc cần nhớ trước khi đọc ví dụ bên dưới:

getSDK() trả về null ngoài ứng dụng (trình duyệt máy tính). Luôn kiểm tra null trước mỗi lệnh gọi, hoặc dùng cầu nối giả khi phát triển.
Gọi sdk.ready() ngay khi màn hình đầu tiên đã vẽ xong, để ứng dụng gỡ màn hình chờ. Quá 15 giây, ứng dụng sẽ báo «tải quá lâu».
Quyền được hỏi theo từng mini app; luôn xử lý PERMISSION_DENIED (Vòng đời và quyền).

Phần còn lại của trang giữ nguyên tiếng Anh, giống mọi trang tham chiếu khác.

npm install @i-catholic/mini-app-sdk

Entry	Contents	Needs React
`@i-catholic/mini-app-sdk`	types, `getSDK`, events, errors, `earnPoints`, `scanQr`, `parseICatholicQr`	no
`@i-catholic/mini-app-sdk/react`	`useSDK`, `useTheme`, `useUser`, `usePoints`, `useSafeArea`	yes (>= 18, optional peer)

The root entry never imports React. Vanilla JS, Vue, Svelte or any other stack can use it without installing React.

The package has no runtime dependencies and ships ESM only.

Quick start

Vanilla (TS/JS)
React

import { getSDK, getSDKErrorCode, whenNativeReady } from '@i-catholic/mini-app-sdk'

// 1. Subscribe to the launch event as early as possible (module top level).
const ready = whenNativeReady().catch(() => null) // rejects outside the app

const sdk = getSDK() // null outside the i-Catholic app — guard every call

async function main() {
  renderApp()

  if (!sdk) return // running in a desktop browser: show a fallback, or use a mock (see below)

  // 2. Tell the host your first screen is painted, so it removes its loading overlay.
  sdk.ready()

  // 3. Use the bridge.
  try {
    const user = await sdk.getUser() // asks the user for `user.profile` the first time
    sdk.showToast({ title: `Xin chào ${user?.name ?? ''}`, action: 'success' })
  } catch (e) {
    if (getSDKErrorCode(e) === 'PERMISSION_DENIED') {
      // the user refused — carry on without the profile
    }
  }

  // 4. Opened from a share link? Route to it.
  const launch = await ready
  if (launch?.deepLinkPath) openRoute(launch.deepLinkPath)
}

main()

import { useEffect } from 'react'
import { useSafeArea, useSDK, useUser } from '@i-catholic/mini-app-sdk/react'

export function App() {
  const { sdk, inApp, theme, locale } = useSDK()
  const { user, loading } = useUser()
  const insets = useSafeArea()

  useEffect(() => {
    sdk?.ready() // first render done — hide the host's loading overlay
  }, [sdk])

  return (
    <main className={theme} style={{ paddingTop: insets.top, paddingBottom: insets.bottom }}>
      {!inApp && <p>Open this page in the i-Catholic app.</p>}
      {loading ? <p>…</p> : <h1>Xin chào {user?.name ?? 'bạn'}</h1>}
      <p>Locale: {locale}</p>
    </main>
  )
}

Quick start​

Quick start