Geliştirme araçları

@viswoo/plugin-sdk paketinin komut satırı aracı viswoo-plugin’dir.

viswoo-plugin init <kod> [--template basic|interactive|server] [--dir <klasör>]
viswoo-plugin dev [klasör] [--port 5199] [--webhook http://localhost:8787/webhook]
viswoo-plugin validate [klasör]
viswoo-plugin pack [klasör] [--out dist]
viswoo-plugin publish [klasör] [--api https://api.viswoo.com]

init

Şablondan yeni bir klasör açar: manifest, panel sekmesi, ekran görünümü, varsa telefon sayfası ve sunucu örneği, README, .gitignore, ES5 uyumlu Prettier ayarı (trailingComma: "es5") ve .viswooignore. Klasör boş olmalıdır.

dev: simülatör

npm run dev

Simülatör http://localhost:5199 adresinde açılır:

• Panel sekmesi, TV ve telefon yan yana. TV 16:9 ya da 9:16, 1280×720, 1920×1080 veya 3840×2160 çizilir ve sığdırılır.
• Üst çubuk: tema, dil, kullanıcı rolü, çözünürlük, yön, dokunmatik, çevrimdışı, Yeni ziyaretçi (telefonun günlük sınırını sıfırlar), Verileri sıfırla.
• Ayarlar: ayarları JSON olarak düzenlersiniz; şema hataları altında listelenir. Şemaya uymayan ayar da kaydedilir, böylece kurulumu eksik eklentinin davranışını görürsünüz.
• Köprü çağrıları: her çağrı, yüzeyi, sonucu ve süresiyle.
• Durum: eklenti verisi, kodlar, stok, olaylar ve telefonda saklanan değerler. Hepsi .viswoo-dev/state.json dosyasındadır.

Simülatör platformun kurallarını uygular: izinler, izleyici rolünün yazamaması, ayar şeması ve kurulumun tamamlığı, sunucuya özel alanların ekrana ve telefona gitmemesi, çekiliş stoğu, telefon başına günlük sınır, ekranda iki çekiliş arası bekleme, kodların süresi ve tek teslimi. Ekran görünümü oynatıcıdaki CSP ile açılır: ağ isteği ve dış betik çalışmaz.

Simülatörde yerleşim yoktur; TV çerçevesi eklentinin yerleştirildiği ekran sayılır.

Gerçek telefonla

Telefon sayfası aynı ağdaki telefondan http://<bilgisayarın IP'si>:5199/phone adresinde açılır. Ekran görünümündeki QR (context.publicUrl) bu adresi gösterir; telefonla okutup deneyebilirsiniz.

Kendi sunucunuzla

Manifestteki server.webhookUrl https olmalıdır; geliştirmede yerel adresi --webhook ile verin:

npx viswoo-plugin dev . --webhook http://localhost:8787/webhook

Simülatör açılışta imza sırrını (whsec_dev_…) ve kurulum belirtecini (vzp_dev_…) yazar, installed olayını gönderir. Sunucunuz platform API’sini http://localhost:5199/api/v1/plugin/<kod>/... adresinde çağırabilir. Ayrıntı: Kendi sunucunuz.

validate ve pack

validate paketi platformun kurallarıyla denetler; pack aynı denetimden sonra .vzp üretir:

• manifest şeması, dosya türleri, boyutlar (paket 5 MB, ekran görünümü 512 KB), yollar
• izin tutarlılığı (settings şeması → settings izni, draw → draw, public sayfa → public …)
• kit kullanımı: panel sekmesi ve genel sayfa viswoo-ui.css’e, ekran görünümü viswoo-screen.css’e başvurur
• ekran görünümü olan eklentide en az bir TV görseli
• ES5: ekran görünümündeki betikler ES5 olarak ayrıştırılır; let, const, ok fonksiyonu, şablon dizesi, sondaki virgül gibi sözdizimi satırıyla bildirilir

Sunucu yüklenen paketi aynı kurallarla yeniden denetler.

publish

Paketi geliştirici portalına yükler. Belirteci portalda Komut satırı → Yeni belirteç ile oluşturun (iki adımlı doğrulama gerekir); değeri bir kez gösterilir. Belirteç yalnız sürüm yükleyebilir ve sahibinin 2FA’sı açık kaldıkça geçerlidir.

VISWOO_TOKEN=vzd_… npx viswoo-plugin publish .

Komut önce validate’in denetimlerini yapar, sonra paketi yükler; hatada sunucunun kodunu ve satırlarını yazar (örneğin plugin.not_es5, plugin.version_exists, plugin.code_not_registered). CI’da VISWOO_TOKEN’ı gizli değişken olarak verin.

Pakete girmeyenler: nokta ile başlayan dosyalar, node_modules, dist, package.json ve kilit dosyaları, .viswooignore’daki yollar (satır başına bir yol; klasör için sonda /).