介紹
小程序是在 IM App 裡執行的 H5 應用：你用網頁技術（Vue 3 + Vite + TypeScript）開發，打包成離線包（.imapp），經平台審核簽章後發佈。使用者在 App 的發現頁或聊天卡片點開，App 內建的小程序容器就會載入它。
運作方式
你的專案 ──im-miniapp build──▶ .imapp（開發者簽章）
│ 上傳、審核
▼
平台簽章（platform.sig）→ CDN
│
使用者點開 ──▶ 容器下載、驗簽、解壓到手機 ──▶ 本機服務提供檔案 ──▶ WebView 載入
▲
JSBridge：sdk.* 呼叫容器的原生能力- 離線包：所有檔案都在包裡，容器逐檔驗證 sha256 與平台簽章，驗不過就不載入。執行時不會從網路載入程式碼。
- 本機服務：容器在手機上起一個只有這個小程序能用的 HTTP 服務（
http://127.0.0.1:<隨機埠>/<隨機密鑰>/）提供包內的檔案。每次開啟的網址都不同。 - JSBridge：小程序透過
@im/miniapp-sdk呼叫容器的能力（取得登入身分、顯示對話框、送網路請求、存資料、分享到聊天…）。SDK 會把同一時間的呼叫合併送出，並處理逾時與錯誤。 - 雙執行緒（選用）：可以把業務邏輯放在容器的獨立 JS 引擎執行，畫面層只負責渲染。詳見單執行緒與雙執行緒。
你能做什麼、不能做什麼
| 可以 | 不行 |
|---|---|
用 sdk.http.fetch 連你在 domains 宣告的 https 後端 | 連沒有宣告的網域、用 http |
用 sdk.auth.getSession 取得登入者與只對你的後端有效的 token | 取得使用者的 IM 憑證、聯絡人、聊天內容 |
用 sdk.storage 存持久資料（每人每小程序 10 MB） | 用 cookie、IndexedDB、Cache Storage、Service Worker 存持久資料 |
| 用容器注入的 CSS 變數做出和 App 一致的外觀 | 寫死顏色、自己畫導覽列 |
用 sdk.share.toChat 讓使用者把頁面分享到聊天 | 不經使用者確認就送出訊息 |
用 sdk.system.openUrl 在外部瀏覽器開網頁 | 在小程序裡導向外部網頁 |
完整清單見開發規範。
小程序在 App 裡的樣子
- 容器畫導覽列：中間是標題（預設為小程序名稱，可用
sdk.ui.setTitle改），右上角是膠囊（「⋯」更多、「✕」關閉）。 - 「⋯」選單固定有：重新进入小程序、转发给朋友、举报（App 文案）。
- 開啟時先顯示容器的骨架畫面，小程序呼叫
sdk.ready()後淡出。 - Android 返回鍵、iOS 邊緣右滑：網頁內有上一頁時先在網頁內返回，回到第一頁才關閉小程序。
名詞
| 名詞 | 說明 |
|---|---|
| 容器 | IM App 裡負責下載、驗證、執行小程序的部分 |
離線包（.imapp） | 小程序的發佈單位，zip 格式，內含 manifest.json、簽章與所有檔案 |
| manifest | 離線包的描述檔，由 CLI 依 miniapp.config.ts 產生 |
| 畫面層 | WebView 裡執行的程式（你的 Vue 應用） |
| 邏輯層 | 雙執行緒時，在容器 JS 引擎執行的程式（logic.ts） |
| 保活 | 關閉小程序後暫時保留執行中的實例，再次開啟直接接回 |
| 容器版本 | App 內小程序容器的能力版本，和 App 版本號無關，見容器版本 |