Розробка SDK для розробки міні-програм сторонніми розробниками
SDK для міні-програм — це публічний контракт вашої екосистеми. Одного разу випустивши у продакшен, ви беретесь на себе зобов'язання підтримувати зворотну сумісність роками. WeChat це зрозумів болісно у 2019-му, коли ломаюча зміна у базовому компоненті <scroll-view> повалила сотні тисяч міні-програм. Тому проектування SDK — це насамперед проектування API boundaries.
Що входить в SDK для сторонніх розробників
SDK — не одна бібліотека. Це екосистема інструментів:
- Runtime JS-бібліотека — підключається всередину міні-програми, надає API (геолокація, платежі, камера, мережа через bridge)
- CLI-інструмент — збірка, превью, публікація в маркетплейс
- Локальний симулятор — запуск міні-програми на десктопі без реального Super App
- TypeScript-означення — без них IDE не підкаже, і розробники робитимуть опечатки в іменах методів
- Документація з інтерактивними прикладами
Перша помилка команд, яку ми бачимо при аудиті: вони починають з runtime-бібліотеки та забувають про CLI та симулятор. Як результат, зовнішні розробники змушені заливати кожну версію у реальний Super App для тестування. Onboarding перетворюється на nightmare, екосистема не росте.
Проектування runtime API
Ядро SDK — JavaScript-бібліотека, яка працює всередину WebView міні-програми. Вона формує абстракцію поверх bridge-протоколу контейнера.
Структура типового виклику:
// Погано — прямий bridge виклик
window.__miniapp_bridge__.call('camera.take', {quality: 0.8}, callback)
// Добре — через SDK
import { camera } from '@superapp/sdk'
const result = await camera.take({ quality: 0.8 })
SDK бере на себе: correlation ID для асинхронних викликів, обробку таймаутів, нормалізацію помилок у стандартний формат {code, message, data}, полифіли для різниць між iOS та Android реалізацією bridge. Це критично: якщо Android повертає координати з 6 знаків після запятої, а iOS з 8 — без нормалізації розробники отримують несумісні результати на різних платформах.
Версіонування API у runtime-бібліотеці будуємо через capability detection, а не через version string:
if (sdk.supports('payment.applePay')) {
// iOS 16+, тільки певні регіони
} else {
sdk.payment.card()
}
CLI: збірка та публікація
CLI — це точка входу для більшості розробників. Він має працювати з коробки без трьохсторінкового гайду по налаштуванню.
Типовий workflow:
superapp init my-miniapp --template=react
cd my-miniapp
superapp dev # hot-reload локальний симулятор
superapp build # production bundle з tree-shaking
superapp publish # завантаження в маркетплейс, створення review request
Під капотом збірник — Webpack 5 або Vite з кастомними плагінами: tree-shake невикористаних нативних API (якщо міні-програма не використовує Bluetooth — він не потрапляє в bundle), аналіз маніфесту permissions та попередження про незадекларовані виклики, мініфікація та code splitting для прискорення cold start всередину WebView.
Розмір bundle — болісна тема. WebView всередину міні-програм не кешує ресурси як браузер. Кожен запуск — завантаження bundle. Ціль: main bundle < 200 KB gzipped. Все що важче — lazy chunks через динамічний import().
Локальний симулятор
Симулятор — десктопна додаток (Electron або нативна), яка емулює runtime-контейнер Super App на локальній машині розробника. Вона реалізує той же bridge API, що й реальний контейнер, але з devtools: інспектор bridge-викликів, мок-дані для геолокації та камери, network throttling, симуляція різних розмірів екрана.
На практиці симулятор дає 90% coverage для розробки. Решта 10% — специфічна поведінка реального WebView на конкретних пристроях. Для них підтримуємо режим remote debug: симулятор трансліює bridge-виклики на реальний пристрій через USB/ADB.
TypeScript-означення та developer experience
SDK без типів у 2024 році — антипаттерн. Розробники використовують TypeScript, і IDE-підказки напряму впливають на швидкість розробки та кількість помилок.
Означення генеруємо з єдиного джерела правди — JSON Schema маніфесту API. Це гарантує синхронність між документацією, runtime-поведінкою та типами. Монорепозиторій SDK: packages/types, packages/runtime, packages/cli, packages/simulator — зі спільною схемою в packages/schema.
Зворотна сумісність та deprecation policy
Це найбільш недооцінена частина. Коли SDK у продакшені зі сторонніми розробниками — кожна ломаюча зміна вимагає migration guide та deprecation window мінімум 6 місяців.
Що допомагає:
- Semantic versioning з чіткими правилами (patch — тільки баги, minor — нові API, major — breaking changes)
-
@deprecatedанотації у TypeScript з JSDoc-описом альтернативи - Runtime warnings при використанні deprecated API (з можливістю відключити у prod)
- Changelog з migration examples для кожної major версії
Терміни розробки повного SDK (runtime + CLI + симулятор + типи) з нуля: від 4 до 8 місяців. Тільки runtime-бібліотека проти існуючого bridge — від 6 до 12 тижнів.