Chuyển tới nội dung chính

SDK 1.0.0

Dành cho nhà phát triển mini app

Phần này dành cho người viết mini app chạy bên trong ứng dụng i-Catholic. Nếu bạn chỉ dùng ứng dụng để học giáo lý, điểm danh hay xem lịch phụng vụ, bạn không cần đọc phần này, hãy quay lại hướng dẫn sử dụng.

Làm trang web riêng cho giáo phận, giáo xứ?

Nếu bạn dựng trang web công khai của một đơn vị và muốn đọc bài viết, trang, menu do nhân sự soạn trong trang quản trị i-Catholic, hãy đọc phần Trang web trên CMS. Phần đó không dùng SDK mini app.

Mini app là gì​

Mini app là một trang web bình thường (HTML, CSS, JavaScript). Ứng dụng i-Catholic mở trang đó toàn màn hình trong một WebView. Trước khi mã của bạn chạy, ứng dụng gắn sẵn đối tượng window.CatholicMiniApp, gọi là cầu nối (bridge). Qua cầu nối, trang của bạn đọc được hồ sơ người dùng, lưu dữ liệu, cộng điểm, chia sẻ, quét mã QR và hơn thế nữa.

Gói npm @i-catholic/mini-app-sdk cung cấp:

  • kiểu dữ liệu (type) cho mọi phương thức, sự kiện và mã lỗi của cầu nối;
  • hàm hỗ trợ làm phẳng các chỗ gồ ghề của cầu nối (earnPoints, scanQr, whenNativeReady, ...);
  • React hooks (tùy chọn) tại @i-catholic/mini-app-sdk/react.

SDK chỉ là lớp mỏng có kiểu dữ liệu. Toàn bộ hành vi nằm trong ứng dụng i-Catholic, nên khi tài liệu này và ứng dụng khác nhau, ứng dụng là đúng. Người dùng chạy nhiều phiên bản ứng dụng khác nhau, vì vậy hãy kiểm tra từng tính năng bằng hasBridgeMethod thay vì dựa vào số phiên bản (xem Lỗi và feature detection).

Tài liệu này mô tả SDK 1.0.0.

Đọc theo thứ tự nào​

  1. Bắt đầu nhanh: cài gói và chạy mini app đầu tiên.
  2. Thiết lập trang: viewport, vùng an toàn, nút của ứng dụng đè lên góc phải. Đây là nguyên nhân số một của lỗi hiển thị.
  3. Vòng đời và quyền: khi nào gọi ready(), người dùng cấp quyền ra sao.
  4. Tổng quan API: mỗi nhóm phương thức một trang.
  5. Đóng gói và nộp bundle: quy tắc cho tệp ZIP. Sai quy tắc là bị từ chối.
  6. Xử lý sự cố: bảng triệu chứng và cách sửa.

Ngôn ngữ của phần này​

Tên hàm, mã lỗi (PERMISSION_DENIED, UNSUPPORTED) và ví dụ mã đều bằng tiếng Anh, vì đó là thứ bạn sẽ tìm kiếm và dán vào issue hay công cụ AI. Các trang cửa ngõ (Giới thiệu, Bắt đầu nhanh, Đóng gói và nộp bundle) có phần mở đầu tiếng Việt; phần còn lại giữ nguyên tiếng Anh.

In English​

A mini app is an ordinary web app that the i-Catholic mobile app opens full-screen in a WebView. The app injects window.CatholicMiniApp (the bridge) before your code runs; the npm package @i-catholic/mini-app-sdk adds types, helpers and optional React hooks on top of it. This documentation describes SDK 1.0.0. The SDK is a thin layer: where these pages and the app disagree, the app is right.

Start with Quick start, then Page setup and the API overview.