Kendi sunucunuz

Platformun hazır işlevleri yetmezse (dış sisteme bağlanmak, kendi hesaplamanız) eklentinin kendi sunucusu olur. Manifestte server ve server izni:

"permissions": ["settings", "data", "server"],
"server": {
  "webhookUrl": "https://eklenti.ornek.com/viswoo/webhook",
  "events": ["installed", "settings.changed", "action"]
}

Adres https olmalıdır; iç ağa yönelen adres reddedilir. events verilmezse event dışındaki bütün olaylar gelir; sık gelen event’i almak için listeye açıkça yazın.

Olaylar

Platform her olayı JSON gövdeyle POST eder:

{ "id": "…", "type": "action", "code": "eklenti-kodu", "tenantId": "…", "createdAt": "2026-11-01T10:00:00Z", "data": {} }

Olay	data	Not
installed	{ token, version, permissions }	Müşteri izinleri her onayladığında yeni belirteç; eskisi geçersiz olur
settings.changed	{ settings }	Sunucuya özel alanlar dahil
uninstalled	{}	Müşteri eklentiyi kapattı (hemen ya da dönem sonunda). Kurulum belirteci artık geçersizdir; veriyi saklama politikanıza göre silin
event	{ source, screenId?, events: [{ name, count }] }	Ekran ya da telefon report ile olay gönderdikçe, toplu. Yalnız events listesinde açıkça varsa gelir
action	{ action, source, screenId?, payload }	source: player ya da public. Eşzamanlıdır: 5 sn içinde dönen JSON gövde call’un sonucudur

action dışındaki olaylar yeniden denemeyle gider; id ile tekrarı ayıklayın. action’da sunucunuz 2xx dışı dönerse call plugin.server_error, 5 sn’de dönmezse plugin.server_timeout ile düşer.

Belirteç müşteri başınadır: tenantId’ye göre saklayın.

İmza

Her istek X-Viswoo-Signature: t=<unix saniye>,v1=<hex> başlığı taşır:

v1 = HMAC-SHA256(sır, "<t>.<ham gövde>")

Sır eklenti başınadır (whsec_…) ve Viswoo tarafından verilir. Sunucunuz:

1. Gövdeyi ayrıştırmadan önce ham hâliyle imzayı hesaplar.
2. Sabit zamanlı karşılaştırır.
3. 5 dakikadan eski ya da ileri t’yi reddeder.

Node.js

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(secret, header, rawBody) {
  const parts = Object.fromEntries(String(header ?? '').split(',').map((part) => part.split('=')));
  const t = Number(parts.t);
  if (!parts.v1 || !Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(parts.v1, 'hex');
  return given.length === expected.length && timingSafeEqual(given, expected);
}

.NET

using System.Security.Cryptography;
using System.Text;

static bool Verify(string secret, string? header, string rawBody)
{
    var parts = (header ?? "").Split(',').Select(p => p.Split('=', 2)).Where(p => p.Length == 2)
        .ToDictionary(p => p[0], p => p[1]);
    if (!parts.TryGetValue("t", out var t) || !parts.TryGetValue("v1", out var v1)) return false;
    if (!long.TryParse(t, out var time) || Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - time) > 300) return false;
    var expected = HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), Encoding.UTF8.GetBytes($"{t}.{rawBody}"));
    byte[] given;
    try { given = Convert.FromHexString(v1); } catch (FormatException) { return false; }
    return CryptographicOperations.FixedTimeEquals(given, expected);
}

PHP

function viswoo_verify(string $secret, ?string $header, string $rawBody): bool {
    parse_str(str_replace(',', '&', $header ?? ''), $parts);
    if (!isset($parts['t'], $parts['v1']) || !ctype_digit($parts['t'])) return false;
    if (abs(time() - (int) $parts['t']) > 300) return false;
    $expected = hash_hmac('sha256', $parts['t'] . '.' . $rawBody, $secret);
    return hash_equals($expected, $parts['v1']);
}

$raw = file_get_contents('php://input');
if (!viswoo_verify(getenv('VISWOO_WEBHOOK_SECRET'), $_SERVER['HTTP_X_VISWOO_SIGNATURE'] ?? null, $raw)) {
    http_response_code(401);
    exit;
}

Örnek akış

server şablonu eksiksiz bir Node sunucusu içerir: imzayı doğrular, installed ile belirteci alır, action’a cevap verir ve platform API’siyle veri yazar.

npx @viswoo/plugin-sdk init gunun-sozu --template server
cd gunun-sozu && npm install
npx viswoo-plugin dev . --webhook http://localhost:8787/webhook
npm run server

Simülatör imza sırrını ve belirteci açılışta yazar; şablondaki sunucu geliştirmede sırrı simülatörün durum dosyasından okur.