Geliştirici paneli inkiveta.com

Oyun odaları (gerçek zamanlı)

Oyun odası, Mini App'teki oyuncuların ve istersen senin sunucunun aynı anda bağlandığı bir WebSocket odasıdır. Satranç, kart, kelime ya da çizim oyunu gibi sırayla ya da eşzamanlı oynanan oyunlarda hamleler odadaki herkese anında ulaşır.

Odalar sendGame / setGameScore ile kurduğun oyunun yerine geçmez, onu tamamlar: oda oyunu oynatır, skoru yine sen setGameScore ile yazarsın (Skor). Bütün uygulamalara açık, genel bir yetenektir; inkiveta'nın kendi uygulamaları da aynı yöntemleri aynı kurallarla ve aynı sınırlarla kullanır.

Örnek kullanımlar:

  • İki arkadaş Mini App'te satranç oynar; hamleler doğrudan birbirine gider.
  • Bir kart oyununda sunucun hakemlik yapar: her oyuncuya yalnız kendi elini gönderir, masayı herkese yayınlar.
  • Bir kelime oyununda sunucun birbirini tanımayan oyuncuları eşleştirir ve oyunu yönetir.

Not: Oyun odaları şu an ücretsizdir; sınırlar ve fiyatlandırma ileride değişebilir, değişiklik Değişiklikler sayfasında önceden duyurulur.

Uçtan uca akış#

  1. Oyuncular Mini App'i açar. Mini App Telegram.WebApp.initData'yı senin sunucuna gönderir; sunucun onu doğrular ve oyuncunun kimliğini (initData.user.id) alır (initData'yı doğrula).
  2. Sunucun odayı açar: inkiCreateGameRoom (oyuncular, oda sınıfı). Yanıttaki room_id'yi (bo_…) oyuncuların Mini App'ine iletirsin (Oda açmak).
  3. Mini App bilet ister: Inki.inkiJoinGameRoom(room_id, cb). inkiveta uygulaması, kullanıcının oturumuyla tek kullanımlık, 30 saniyelik bir bağlanma bileti üretir ve sayfana verir. Kullanıcının oturum bilgisi sayfana hiç geçmez.
  4. Mini App bağlanır: new WebSocket(url, ['inko.v1', 'inko.bilet.' + ticket]) (Mini App'ten bağlanmak).
  5. Oda karşılar: sunucu ilk iletide oyun.durum gönderir: senin koltuk numaran (ben), odadaki koltuklar ve bağlı olanlar (Protokol).
  6. Oyun oynanır. relay odasında hamleler herkese gider; host odasında yalnız senin hakem sunucuna gider ve tahtayı o yayınlar (Oda sınıfları).
  7. Oyun biter. Odayı inkiCloseGameRoom ile (ya da hakem bitir ile) kapatırsın, skoru setGameScore ile yazarsın. Kapanış inki_game_room update'iyle de gelir (Update).

Odada herkes koltuk numarasıyla görünür (1–8; hakem 0). Kullanıcının kimliği soket üzerinden hiç geçmez: kimin hangi koltukta oturduğunu yalnız sunucun bilir (inkiGetGameRoom).

Sunucusuz Mini App: odayı kullanıcı açar#

Sunucun yoksa (yalnız statik sayfa) Mini App odayı kendisi açabilir:

jsInki.inkiCreateGameRoom({ game_short_name: 'satranc' }, (r) => {
  // r.status: "created" | "failed"; r.room_id, r.invite_url; hata: r.error
  if (r.status === 'created') Telegram.WebApp.openLink(r.invite_url); // ya da paylaşma ekranında göster
});
  • Bu köprü çağrısı (Inki.inkiCreateGameRoom) Bot API yöntemi inkiCreateGameRoom ile aynı adı taşır ama farklı bir şeydir: odayı kullanıcı açar, oda her zaman relay sınıfındadır, açan kişi 1. koltuğa oturur. params boş olabilir; tek alanı isteğe bağlı game_short_name.
  • Yanıttaki invite_url (https://inkiveta.com/@<kullanici_adi>?startapp=bo_…) paylaşılabilir bir davettir. Kullanıcı bağlantıyı kendi sohbetinden arkadaşına yollar. Davetli bağlantıyla Mini App'i açar; oda kimliği Telegram.WebApp.initDataUnsafe.start_param'da gelir ve sayfan Inki.inkiJoinGameRoom(start_param, cb) çağırır. Davetliye boş bir koltuk verilir.
  • Davet bağlantısını kişi kendi isteğiyle açtığı için bu odalarda tanışıklık şartı aranmaz; engel, yaş ve ebeveyn kapıları aynen geçerlidir.
  • Kullanıcı başına dakikada en çok 5 oda açılır. Tavanlar hem odayı açan kullanıcıya hem uygulamana sayılır. Kapanışta sana inki_game_room gelir.
  • Olay adı inki_request_game_room {game_short_name?}, yanıt inki_game_room_requested {status:"created", room_id, invite_url} ya da {status:"failed", error}. error değerleri inkiJoinGameRoom ile aynıdır (Hata kodları). Aynı anda tek istek: süren istek varken ikincisi {status:"failed", error:"rate"} alır.

Oda sınıfları#

relay (varsayılan)host
Hamle kime giderOdadaki herkese (oyun.hamle {k, d})Yalnız hakeme (senin sunucun)
Herkes neyi görürDiğer oyuncuların ham hamleleriniYalnız hakemin yayınladığını (oyun.yayin) ve kendine özel olanı (oyun.ozel)
Kural kimdeHer istemcide (platform yalnız göndereni ve sırayı garanti eder)Senin sunucunda
Hileye karşıKoruma yokYetkili durum sende
Oyuncular2–81–8 + hakem
Tanışıklık şartıVar: oyuncular birbirini tanımalıYok: yabancılar eşleşebilir
GecikmeEn düşük (tek atlama)İki atlama (oyuncu → oda → hakem → oda → oyuncular)
  • **Rekabetçi oyunda ve yabancıyla eşleşmede host kullan.** relay odasında platform kuralı denetlemez; bir istemci istediği hamleyi gönderebilir.
  • **Tanışıklık (relay): her oyuncu çifti birbirini tanımalıdır (aynı kuralla: rehber, ortak sohbet gibi mevcut bir ilişki). Bu, oda kurulurken değil, her bilet isteğinde** denetlenir; arada ilişki biterse yeniden bağlanma da reddedilir. Tanışık olmayan bir oyuncunun bileti unavailable alır ve oda unavailable sebebiyle kapanır.
  • **Yabancılar (host):** host odasında oyuncu hamlesi diğer oyunculara hiç ulaşmaz; oyunculara giden her şeyi senin sunucun yayınlar ve içerikten sen sorumlusun (Kurallar).
  • İki sınıfta da aynı olan kapılar: koltuk üyeliği, oda açık, kullanıcı uygulamanı başlatmış ve engellememiş, oyuncular arasında engel yok, yaş ve ebeveyn kapıları, uygulamanın oyun odası askısı.

Oda açmak#

Oda yöntemleri inkiveta uzantısıdır; SDK'nın ham çağrı yoluyla çağırırsın.

YöntemParametreler (* zorunlu)Döner
inkiCreateGameRoomplayers* (1–8 kullanıcı kimliği), mode = relay (varsayılan) | host, game_short_name (Atölye'de kayıtlı oyun), max_idle_seconds (30–600, varsayılan 120)GameRoom
inkiGetGameRoomroom_id*GameRoom (bağlı koltuklar dahil)
inkiAddGameRoomPlayerroom_id*, user_id*GameRoom (yeni koltukla)
inkiRemoveGameRoomPlayerroom_id*, user_id*true — kişinin soketi düşer, koltuk boşalır, odaya oyun.koltukCikti {k} gider. Boşalan koltuk numarası başka kişiye verilmez (aynı kişiyi yeniden eklersen kendi numarası döner); bir odada en çok 8 farklı kişi yer alır
inkiCloseGameRoomroom_id*true — oda bot sebebiyle kapanır
inkiGetGameRoomHostTicketroom_id* (yalnız host odası){ticket, url, expires_in: 30} — Hakem sunucusu

players ve user_id, update'te ya da initData'da gelen kullanıcı kimliğidir (from.id). relay odası en az 2 oyuncu ister.

bashcurl -s "https://app.inkiveta.com/bot$BOT_TOKEN/inkiCreateGameRoom" -H 'Content-Type: application/json' -d '{
  "players": [4185489292941965, 7731024488190236],
  "mode": "host",
  "game_short_name": "satranc",
  "max_idle_seconds": 120
}'

**GameRoom:**

json{"ok": true, "result": {
  "room_id": "bo_3f9a1c07d2e84b6a5c10",
  "mode": "host",
  "status": "open",
  "game_short_name": "satranc",
  "players": [
    {"seat": 1, "user": {"id": 4185489292941965, "is_bot": false, "first_name": "Kullanıcı"}, "connected": false},
    {"seat": 2, "user": {"id": 7731024488190236, "is_bot": false, "first_name": "Kullanıcı"}, "connected": false}
  ],
  "created_at": 1765000000,
  "max_idle_seconds": 120
}}
AlanAnlamı
room_idbo_ + 20 onaltılık karakter. Tahmin edilemez; tek başına hiçbir yetki vermez
moderelay | host
statusopen | closed
game_short_nameVerdiysen
players[]{seat, user, connected} — user, uygulamanın gördüğü kullanıcı nesnesidir (ad ve kullanıcı adı yalnız kullanıcının profil izniyle gelir)
created_at, closed_atUnix zamanı; closed_at yalnız kapalı odada
close_reasonKapalı odada: bot · idle · lifetime · unavailable · suspended · server (Update)
max_idle_secondsHiç bağlı koltuk yokken oda bu kadar saniye sonra kapanır

Oda kurulurken her oyuncu denetlenir: kimlik bu uygulamanın kullanıcısı mı, uygulamanı başlatmış ve engellememiş mi, hesap etkin mi, oyuncular arasında engel var mı. Biri geçmezse 400 Bad Request: GAME_ROOM_PLAYERS_INVALID döner — tek kod: hangi kişinin neden geçmediği söylenmez. relay'deki tanışıklık burada değil, bilet anında denetlenir.

Hata kodlarının tamamı: Hata kodları.

Mini App'ten bağlanmak#

Köprü (inkiveta uzantısı):

jsInki.inkiJoinGameRoom('bo_3f9a1c07d2e84b6a5c10', (r) => {
  // r.status: "issued" | "failed"
  // issued: r.ticket, r.url, r.expires_in (30), r.auth ("subprotocol" | "first_frame")
  // failed: r.error ("not_found" | "closed" | "parental" | "age" | "suspended" | "rate" | "unavailable")
});
  • Bilet tek kullanımlıktır ve 30 saniyede düşer. Her bağlanma (yeniden bağlanma dahil) yeni bilet ister; köprü çağrısı ucuzdur.
  • r.auth biletin nasıl verileceğini söyler: Her zaman r.auth'a bak; değeri sunucu tarafında değişebilir.
    • "subprotocol": new WebSocket(r.url, ['inko.v1', 'inko.bilet.' + r.ticket]).
    • "first_frame": new WebSocket(r.url); bağlantı açılınca ilk ileti olarak 2 saniye içinde {"op":"bilet","t":"<ticket>"} gönder. Bilet gelmezse ya da geçersizse bağlantı 4401 ile kapanır.
  • Aynı anda tek istek: süren istek varken ikincisi beklemeden {status:"failed", error:"rate"} alır. Çağrıları sıraya koy.
  • Mini App açık kaldığı sürece yanıt her durumda gelir ama gecikebilir: kullanıcının yaş beyanı yoksa mobil uygulama önce yaş ekranını Mini App'in üstünde açar (web sürümü beklemeden age döner). Beyandan sonra isteği kendisi yeniden dener, bileti o zaman verir; kullanıcı vazgeçerse age döner. Bu bekleme dakikalar sürebilir. Bu yüzden isteği kendi kısa zaman aşımınla düşürme, yoksa geç gelen bileti kaçırırsın. Aynısı Inki.inkiCreateGameRoom için de geçerlidir.
  • room_id bo_ + 20 onaltılık karakter değilse istek gönderilmez, not_found döner.
  • Bileti başka bir sayfaya, sunucuna ya da başka bir cihaza taşıma. Bilet açık olan Mini App'in origin'ine bağlıdır; başka bir sitenin sayfası onu kullanamaz.
  • Web sürümü: inkiveta-web-app.js yüklüyse Inki.inkiJoinGameRoom ve Inki.inkiCreateGameRoom mobildeki gibi çalışır. Yalnız resmî telegram-web-app.js ile: Telegram.WebView.postEvent('inki_request_game_ticket', false, {room_id}) gönder, Telegram.WebView.onEvent('inki_game_ticket_requested', …) ile dinle (Köprü).
  • CSP: sayfanın Content-Security-Policy başlığı varsa connect-src'ye wss://app.inkiveta.com ekle; yoksa tarayıcı bağlantıyı açmaz.
  • Uygulamanın eski sürümleri bu köprüyü bilmez. İşlev olarak sına ve yoksa kullanıcıya güncelleme öner; eski sürümde oyun görünür bir hata vermeden yalnız açılmaz:
jsif (!window.Inki || typeof Inki.inkiJoinGameRoom !== 'function') {
  Telegram.WebApp.showAlert('Bu oyun için inkiveta uygulamasını güncelle.');
}

Örnek: bağlan, kopunca yeniden bağlan, kaldığın yerden devam et. Yeniden bağlanırken rastgele (jitter'lı) bekleme şarttır: sunucu yeniden başladığında bütün oyuncular aynı anda bağlanmaya çalışır.

jsconst BITIR = ['not_found', 'closed', 'parental', 'age', 'suspended'];
let ws = null, sonId = 0, deneme = 0, bitti = false;

const bilet = (oda) => new Promise((coz) => Inki.inkiJoinGameRoom(oda, coz));
const bekle = () => new Promise((coz) =>
  setTimeout(coz, Math.min(30000, 500 * 2 ** deneme++) * (0.5 + Math.random() / 2)));

async function baglan(oda) {
  while (!bitti) {
    const r = await bilet(oda);                       // her denemede YENİ bilet
    if (r.status !== 'issued') {
      if (BITIR.includes(r.error)) return goster(r.error);
      await bekle(); continue;                         // rate / unavailable: bekle, yeniden dene
    }
    ws = r.auth === 'subprotocol'
      ? new WebSocket(r.url, ['inko.v1', 'inko.bilet.' + r.ticket])
      : new WebSocket(r.url);
    ws.onopen = () => { if (r.auth === 'first_frame') ws.send(JSON.stringify({ op: 'bilet', t: r.ticket })); };
    ws.onmessage = (e) => {
      const m = JSON.parse(e.data);
      if (m.id) sonId = m.id;                          // sıra numarası olan her olay
      if (m.tip === 'oyun.durum') {
        deneme = 0;
        if (m.sonId > sonId && sonId > 0) ws.send(JSON.stringify({ op: 'resume', sonId }));
        else if (sonId === 0) sonId = m.sonId;
      } else if (m.tip === 'oyun.ring') tamDurumIste();  // halka yetmedi: durumu baştan kur
      else if (m.tip === 'oyun.odaBitti') { bitti = true; ws.close(); oyunBitti(m.sebep); }
      else oyunaIlet(m);                                // oyun.hamle, oyun.yayin, oyun.ozel, oyun.koltuk…
    };
    const kod = await new Promise((coz) => { ws.onclose = (e) => coz(e.code); });
    if (bitti || kod === 4403 || kod === 1009) return goster(kod);  // askı ya da çok büyük ileti
    await bekle();                                     // 4401, 1006, 1013, 1008: yeni biletle tekrar
  }
}
  • 4401 bilet ya da oturum geçersiz demektir: aynı bileti yeniden deneme, yeni bilet iste (örnekte her tur yeni bilet ister).
  • El sıkışma reddedildiğinde (bilet süresi dolmuş, oda kapanmış…) tarayıcı nedeni göstermez, 1006 görürsün. Bunu 4401 gibi ele al; oda gerçekten kapandıysa bir sonraki bilet isteği closed döner.
  • resume yalnız gördüğün son olaydan sonrasını ister. Halkada o kadar geri gidilemiyorsa ya da yeniden oynatma odanın çıkış bütçesine (512 KiB/sn) o an sığmıyorsa oyun.ring {tazele: true} gelir: tahtayı baştan kur (host odasında hakem oyun.koltukBaglandi görünce tahtayı yeniden gönderir).

Hakem sunucusu#

host odasında senin sunucun odaya hakem koltuğu (koltuk 0) olarak bağlanır. Oyuncu hamleleri yalnız ona gelir; tahtayı o yayınlar.

  1. inkiGetGameRoomHostTicket(room_id) → {"ticket": "…", "url": "wss://app.inkiveta.com/oyun-ws", "expires_in": 30}. Bilet tek kullanımlık ve 30 saniyeliktir; her bağlanma yeni bilet ister.
  2. Sunucundan url'ye bağlan: bileti X-Oyun-Bilet başlığında, alt protokol olarak inko.v1 ile ver. (Başlık gönderemeyen bir istemcin varsa Mini App gibi ['inko.v1', 'inko.bilet.' + ticket] alt protokolüyle de bağlanabilirsin.) Hakem bağlantısı tarayıcı değildir, Origin başlığı göndermez.
  3. Gelen oyun.hamle {k, d}'yi kendi kuralınla denetle; sonucu yayin (herkese) ya da ozel (tek koltuğa) ile gönder; oyun bitince bitir.
Hakem gönderirEtkisi
{"op":"yayin","d":…}Herkese {"id":n,"tip":"oyun.yayin","d":…} (halkaya yazılır, resume ile yeniden oynatılır)
{"op":"ozel","k":2,"d":…}Yalnız 2. koltuğa {"tip":"oyun.ozel","d":…} (halkaya yazılmaz: gizli el kartları gibi)
{"op":"bitir","sebep":"…"}Oda kapanır (inkiCloseGameRoom ile aynı; sebep bot)
  • Odada tek hakem olur. İkinci hakem bağlanınca birincisi düşer.
  • Hakem düşerse oyunculara {"tip":"oyun.hakemYok"} gider; o sırada gelen oyuncu hamleleri {"tip":"oyun.red","sebep":"hakem_yok"} alır. Hakem dönünce herkese oyun.koltukBaglandi {k: 0} gider. Hakem yeniden bağlanırken de yeni bilet ister ve jitter'la bekler.
  • Token'ı Atölye'den yenilersen ya da uygulaman askıya alınırsa hakem bağlantısı en geç 60 saniye içinde düşer.
  • Oyuncu bağlandı / ayrıldı bilgisini (oyun.koltukBaglandi, oyun.koltukAyrildi, oyun.koltukCikti) hakem soketten alır; bunlar update olarak gelmez. Kim hangi koltukta: inkiGetGameRoom.
  • Saat damgası yoktur: süreyi kendi saatinle tut. İstemcinin bildirdiği süreye güvenme.

Node.js (ws paketi; tarayıcının WebSocket'i başlık gönderemez):

jsimport WebSocket from 'ws';

const api = (yontem, govde) => fetch(`https://app.inkiveta.com/bot${process.env.BOT_TOKEN}/${yontem}`, {
  method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(govde),
}).then((r) => r.json());

export async function hakemBaglan(roomId, deneme = 0) {
  const { ok, result } = await api('inkiGetGameRoomHostTicket', { room_id: roomId });
  if (!ok) return;                                         // oda kapandı ya da yok
  const ws = new WebSocket(result.url, ['inko.v1'], { headers: { 'X-Oyun-Bilet': result.ticket } });
  const tahta = yeniTahta();
  let bitti = false;
  ws.on('error', () => {});                                // ret / kopma: 'close' ayrıca gelir
  ws.on('message', (veri) => {
    const m = JSON.parse(veri);
    if (m.tip === 'oyun.durum' || m.tip === 'oyun.koltukBaglandi') {
      deneme = 0;
      ws.send(JSON.stringify({ op: 'yayin', d: tahta.ozet() }));   // yeni gelen tahtayı görsün
    } else if (m.tip === 'oyun.hamle') {
      if (!tahta.gecerliMi(m.k, m.d)) return ws.send(JSON.stringify({ op: 'ozel', k: m.k, d: { hata: 'gecersiz_hamle' } }));
      tahta.uygula(m.k, m.d);
      ws.send(JSON.stringify({ op: 'yayin', d: tahta.ozet() }));
      if (tahta.bitti()) ws.send(JSON.stringify({ op: 'bitir', sebep: 'oyun_bitti' }));
    } else if (m.tip === 'oyun.odaBitti') { bitti = true; ws.close(); }
  });
  ws.on('close', (kod) => {
    if (bitti || kod === 4403) return;                      // oda bitti ya da askı
    setTimeout(() => hakemBaglan(roomId, deneme + 1), Math.min(30000, 500 * 2 ** deneme) * (0.5 + Math.random() / 2));
  });
}

Python (websockets ≥ 14, httpx):

pythonimport asyncio, json, os, random
import httpx, websockets

API = f"https://app.inkiveta.com/bot{os.environ['BOT_TOKEN']}"

async def hakem(room_id: str) -> None:
    deneme = 0
    async with httpx.AsyncClient() as http:
        while True:
            r = (await http.post(f"{API}/inkiGetGameRoomHostTicket", json={"room_id": room_id})).json()
            if not r["ok"]:
                return                                      # oda kapandı ya da yok
            bilet = r["result"]
            try:
                async with websockets.connect(bilet["url"], subprotocols=["inko.v1"],
                                              additional_headers={"X-Oyun-Bilet": bilet["ticket"]}) as ws:
                    tahta = yeni_tahta()
                    async for ham in ws:
                        m = json.loads(ham)
                        if m["tip"] in ("oyun.durum", "oyun.koltukBaglandi"):
                            deneme = 0
                            await ws.send(json.dumps({"op": "yayin", "d": tahta.ozet()}))
                        elif m["tip"] == "oyun.hamle" and tahta.gecerli_mi(m["k"], m["d"]):
                            tahta.uygula(m["k"], m["d"])
                            await ws.send(json.dumps({"op": "yayin", "d": tahta.ozet()}))
                            if tahta.bitti():
                                await ws.send(json.dumps({"op": "bitir", "sebep": "oyun_bitti"}))
                        elif m["tip"] == "oyun.odaBitti":
                            return
            except websockets.ConnectionClosed as e:
                if e.rcvd and e.rcvd.code == 4403:
                    return                                  # askı
            except websockets.InvalidStatus:
                pass                                        # el sıkışma reddi: yeni biletle tekrar
            await asyncio.sleep(min(30, 0.5 * 2 ** deneme) * random.uniform(0.5, 1))
            deneme += 1

Protokol#

İletiler JSON metindir. İstemci {"op": …} gönderir; sunucu {"id"?, "tip": …} gönderir. Kimlik alanı her yerde k'dir (koltuk numarası, hakem 0). id, odanın halkasına yazılan olayların artan sıra numarasıdır; resume bunu kullanır. k ve id'yi sunucu damgalar, istemci taklit edemez. d senin verindir; sunucu içine bakmaz.

Yönİletirelayhost
Sunucu → sana{"tip":"oyun.durum","ben":k,"oda":"bo_…","sinif":"relay"|"host","koltuklar":[k…],"bagli":[k…],"sonId":n}✓✓
Sunucu → herkese{"id":n,"tip":"oyun.koltukBaglandi","k":k,"bagli":[…]} · oyun.koltukAyrildi {k, bagli} · oyun.koltukCikti {k}✓✓ (hakeme de)
Oyuncu → sunucu{"op":"hamle","d":…}Herkese {"id":n,"tip":"oyun.hamle","k":k,"d":…}Yalnız hakeme {"tip":"oyun.hamle","k":k,"d":…}; diğer oyuncular görmez
Hakem → sunucu{"op":"yayin","d":…}—Herkese {"id":n,"tip":"oyun.yayin","d":…}
Hakem → sunucu{"op":"ozel","k":n,"d":…}—Yalnız n. koltuğa {"tip":"oyun.ozel","d":…}
Hakem → sunucu{"op":"bitir","sebep":"…"}—Oda kapanır
Herkes → sunucu{"op":"resume","sonId":n}✓✓ (oyun.ozel yeniden oynatılmaz)
Sunucu → sana{"tip":"oyun.ring","tazele":true} — halkada o kadar geri gidilemiyor, durumu baştan kur✓✓
Sunucu → herkese{"tip":"oyun.odaBitti","sebep":…}✓✓
Sunucu → oyunculara{"tip":"oyun.hakemYok"} (hakem düştü) · {"tip":"oyun.red","sebep":"hakem_yok"} (hamlen hakeme ulaşmadı)—✓
Mini App → sunucu{"op":"bilet","t":"…"} — yalnız auth: "first_frame" iken, ilk ileti✓✓
  • Aynı koltuk yeniden bağlanınca eski bağlantı düşer; odaya "ayrıldı" gitmez.
  • İleti en çok 4.096 bayt (hakem 16.384 bayt), yalnız metin.

Skor#

Skoru yalnız sen yazarsın: setGameScore (mesajsız biçim, game_short_name). Platform hiçbir uygulamanın oyununu hakemlemez.

Odada oynanan bir oyunun skorunu yazarken isteğe bağlı **game_room_id** ver:

bashcurl -s "https://app.inkiveta.com/bot$BOT_TOKEN/setGameScore" -H 'Content-Type: application/json' \
  -d '{"user_id":4185489292941965,"game_short_name":"satranc","score":1250,"game_room_id":"bo_3f9a1c07d2e84b6a5c10"}'
  • Platform şunları doğrular: kişinin bu uygulamanın bu odasında koltuğu vardı ve odaya en az bir kez bağlandı; oda kapanmışsa kapanışının üzerinden 24 saat geçmedi. Tutmazsa 400 Bad Request: GAME_ROOM_NOT_PLAYED.
  • Skor game_room_id ile yazıldıysa o satır getGameHighScores yanıtında room_verified: true taşır; öyle yazılmayan satırda alan hiç yoktur.
  • room_verified yalnız kişinin bu odada oynadığını (katılımı) kanıtlar, skoru DEĞİL. Skorun doğruluğu senin sorumluluğundur; rekabetçi oyunda skoru hakemli (host) odada kendi sunucunda hesapla.

Sınırlar#

Bağlantı ve oda:

KonuSınır
Bilet30 saniye, tek kullanım
Bilet isteğiKişi başına dakikada 30; hakem bileti uygulama başına dakikada 60
Mini App'ten oda açma (Inki.inkiCreateGameRoom)Kullanıcı başına dakikada 5
BağlanmaBilet sahibi başına 60 saniyede 30
İleti boyuOyuncu ≤ 4.096 bayt; hakem ≤ 16.384 bayt (aşım → 1009)
İleti hızıOyuncu saniyede 20, tepe 60; hakem saniyede 100, tepe 200 (aşım → 1008)
Oda yayınıOda başına saniyede 60 olay; aşan gönderici 1008 alır
Oda çıkış bant genişliğiOda başına saniyede 512 KiB; aşılırsa oda server sebebiyle kapanır
resumeSaniyede 1, tepe 3; halka son 128 olayı tutar
Koltuk1–8 oyuncu (relay en az 2) + 1 hakem
Boşta kapanmaHiç bağlı koltuk yoksa max_idle_seconds (30–600, varsayılan 120); kurulup hiç bağlanılmayan oda 10 dakika
Oda ömrüEn çok 4 saat

Uygulama ve kişi başına:

KonuTest ortamıGerçekDoğrulanmış uygulama
Aynı anda açık oda202002.000
Oda açma hızısaniyede 1saniyede 5saniyede 20
Günlük oda (kayan 24 saat)50020.000200.000
Kişi başına açık koltuk (bütün uygulamalar)555
Kişi başına açık koltuk (aynı uygulama)222
  • "Doğrulanmış uygulama", herkese açık doğrulama rozetine sahip uygulamadır (Yayına alma).
  • Aşımda 429 Too Many Requests: retry after N (parameters.retry_after). Platformun toplam kapasitesi dolarsa da oda açma 429 döner; bağlantı kapasitesi dolarsa el sıkışma 1013 ile kapanır, jitter'la yeniden dene.
  • GAME_ROOM_PLAYERS_INVALID hataları uygulama başına sayılır: 24 saatte 200'ü aşarsa oda açma 1 saat 429 döner.

Kurallar#

  • **relay odasında oyuncular tanışık olmalı.** Tanışık olmayanları eşleştirmek istiyorsan host odası aç.
  • Hakem olarak oyuncu yükünü başka oyunculara olduğu gibi aktaramazsın; odalarda serbest mesajlaşma kanalı kuramazsın. Oyun içi sohbet bir platform kanalı değildir.
  • Hakem olarak yayınladığın içerikten sen sorumlusun (içerik kuralları: Uygulama Geliştirici Şartları).
  • Kumar ve bahis yasak. Ink yatırarak oynanan oyun, bahis ve şansa bağlı ödül yoktur. inkiGiftInk bir oda sonucuna bahis olarak bağlanamaz.
  • Ebeveyn denetimi oyun odasında uygulamanın kategorisinden bağımsızdır: oyunları kapalı olan kullanıcı, kategorisi "Oyun" olmayan bir uygulamanın odasına da giremez (parental). Kilit oyun sırasında açılırsa kullanıcının bağlantısı 60 saniye içinde düşer.
  • Yetişkin dereceli uygulamanın odasına yalnız yaşı doğrulanmış kullanıcı girer (age).
  • Engel: oyuncular arasında engel varsa oda kurulamaz; oyun sürerken biri ötekini engellerse oda unavailable sebebiyle kapanır. Kullanıcı uygulamanı engellerse odalardaki bütün koltukları düşer.
  • Davet: kişiyi odaya çağırmak senin işindir: sohbetinden web_app düğmeli bir mesaj (start_param = oda) gönderirsin ya da eşleşmeyi Mini App içinde yaparsın. Bu mesaj kullanıcıya yazma kurallarına tabidir.
  • Trafik kaydı: 5651 sayılı Kanun gereği her bağlantının (oyuncu ve hakem) IP adresi, kaynak portu, zamanı, uygulaması, odası ve koltuğu platformda kaydedilir. Oyun içeriği kaydedilmez. Hakem sunucunun kendi trafik kaydı ve yükümlülükleri sana aittir.
  • İçerik saklanmaz: odada taşınan içerik yalnız bellekte durur ve oda kapanınca düşer. İstisna şikâyettir: kullanıcı Mini App'in ••• menüsündeki "Bildir" ile odayı şikâyet ederse, o kullanıcının odada aldığı son içerik (en çok 128 ileti) inceleme için 30 gün saklanır ve yalnız inkiveta moderasyon ekibi görür. Başkasına giden oyun.ozel iletileri buna girmez.
  • Askı: 30 günde en az 5 farklı kişi ve oyuncuların en az %1'i şikâyet ederse, ya da bu kurallara aykırılıkta, uygulamanın oyun odaları askıya alınır: oda açma 403 GAME_ROOMS_SUSPENDED döner, açık odalar suspended sebebiyle kapanır, hakemler düşer. Kaldırmak için Atölye → Destek.

Update: inki_game_room#

Oda kapanınca gelir — yalnız allowed_updates'e inki_game_room eklediysen. Oyun içeriği ve profil verisi taşımaz: her oyuncu koltuk numarası ve senin zaten bildiğin takma user_id'dir (ad / kullanıcı adı gerekiyorsa inkiGetGameRoom, profil iznine göre). Kapanıştan yaklaşık 1 dakika sonra gelir: played bağlantı kayıtları tamamlanınca hesaplanır, kısa bir oyunda yanlış false olmasın diye. Hesabı silinen oyuncu listede yer almaz.

json{"update_id": 9140, "inki_game_room": {
  "room_id": "bo_3f9a1c07d2e84b6a5c10",
  "event": "closed",
  "reason": "idle",
  "players": [
    {"seat": 1, "user_id": 4185489292941965, "played": true},
    {"seat": 2, "user_id": 7731024488190236, "played": false}
  ],
  "duration_seconds": 412,
  "date": 1765000412}}
reasonNe oldu
botinkiCloseGameRoom ya da hakemin bitir'i
idleBağlı koltuk kalmadı ve max_idle_seconds doldu; ya da oda kurulup 10 dakika içinde kimse bağlanmadı
lifetime4 saatlik oda ömrü doldu
unavailableBir oyuncu artık odada olamıyor (engel, hesap silme, tanışıklık…). Ayrıntı verilmez
suspendedUygulamanın oyun odaları askıya alındı
serverOda bant genişliği aşıldı ya da platform tarafında bir sorun oldu
  • event şimdilik yalnız closed. played, kişinin odaya en az bir kez bağlanıp bağlanmadığıdır.
  • Koltuk bağlandı / ayrıldı bilgisi update olarak gelmez: host odasında hakem bunu soketten alır, relay odasında inkiGetGameRoom ile sorarsın.

Hata kodları#

Bot API:

HataNe zaman
400 Bad Request: GAME_ROOM_PLAYERS_INVALIDBir kimlik çözülmüyor; kişi uygulamanı başlatmamış, engellemiş, hesabı askıda ya da silinmiş; aynı kişi iki kez; oyuncular arasında engel var. Tek kod, kim olduğu söylenmez
400 Bad Request: GAME_ROOM_MODE_INVALIDBilinmeyen mode; relay'de 2'den az oyuncu
400 Bad Request: GAME_SHORTNAME_INVALIDgame_short_name Atölye'de kayıtlı değil
400 Bad Request: GAME_ROOM_NOT_FOUNDOda yok ya da başka bir uygulamanın veya ortamın. Yok ile başkasının ayırt edilmez
400 Bad Request: GAME_ROOM_CLOSEDKapalı odaya oyuncu ekleme / çıkarma ya da hakem bileti
400 Bad Request: GAME_ROOM_FULL8 koltuk dolu ya da 8 koltuk numarasının hepsi bu odada kullanıldı (çıkarılan koltuk başkasına verilmez)
400 Bad Request: GAME_ROOM_NOT_PLAYEDsetGameScore'daki game_room_id doğrulanmadı (Skor)
400 Bad Request: USER_ID_INVALIDinkiRemoveGameRoomPlayer: kişi bu odada koltukta değil
400 Bad Request: max_idle_seconds must be between 30 and 600max_idle_seconds aralık dışı
403 Forbidden: GAME_ROOMS_SUSPENDEDUygulamanın oyun odaları askıda
429 Too Many Requests: retry after NBir sınır aşıldı (Sınırlar)

**Köprü (Inki.inkiJoinGameRoom, Inki.inkiCreateGameRoom) error değerleri:**

errorAnlamıNe yapmalı
not_foundOda yok ya da kullanıcının bu odada koltuğu yokDurma; kullanıcıya göster
closedOda kapandıDurma
parentalEbeveyn denetimi oyunları kapatmışDurma; kullanıcı nedeni görür
ageYaş kapısı (yaş doğrulanmamış ya da yetişkin dereceli uygulama)Durma
suspendedUygulamanın oyun odaları askıdaDurma
rateÇok sık istek ya da süren bir istek varJitter'la bekleyip tekrar dene
unavailableKullanıcı bu odaya giremiyor (engel, tanışıklık…) ya da bağlantı sorunuBirkaç kez jitter'la dene, sonra vazgeç

WebSocket kapanış kodları:

KodAnlamıNe yapmalı
1008Hız ya da kural aşımıGönderim hızını düşür; yeni biletle bağlan
1009İleti çok büyükİletiyi küçült; aynı iletiyi yeniden gönderme
1013Geçici (kapasite dolu, sunucu yeniden başlıyor ya da sunucu durumu bilinmiyor)Jitter'la yeni biletle yeniden dene
4401Bilet ya da oturum geçersiz (kullanıcının oturumu kapandı, bilet süresi doldu, koltuktan çıkarıldı…)Aynı bileti deneme; yeni bilet iste
4403Uygulamanın oyun odaları askıdaYeniden bağlanma
1006El sıkışma reddedildi ya da bağlantı koptu (tarayıcı nedeni göstermez)Yeni biletle tekrar dene

El sıkışma reddinin HTTP kodları (sunucudan bağlanırken görürsün): 400 (inko.v1 alt protokolü yok), 401 (bilet yok ya da geçersiz), 403 (askı, origin uyuşmuyor ya da hakem bağlantısı Origin başlığı gönderdi — sunucu istemcin Origin göndermemeli), 429 (çok sık bağlanma; bilet bu durumda da harcanmış sayılır, yeni bilet iste), 503 (geçici; tekrar dene).

SSS#

Oda kimliği tahmin edilirse ne olur? Hiçbir şey. room_id 80 bitlik rastgele bir değerdir ve tek başına yetki vermez: bilet yalnız odada koltuğu olan kullanıcıya, onun kendi oturumuyla verilir. Koltuğu olmayan için oda "yok" görünür.

Skoru platform doğruluyor mu? Hayır. game_room_id ile yalnız kişinin odada oynadığı doğrulanır. Skoru doğru hesaplamak senin işindir; rekabetçi oyunda host odası aç ve skoru hakem sunucunda hesapla.

Test ortamında nasıl denerim? Test token'ıyla …/test/inkiCreateGameRoom çağır; odalar ortam başınadır ve test odalarına yalnız test erişimin olan kullanıcılar girer. Test ortamının sınırları daha düşüktür (Sınırlar, Test ortamı).

Kullanıcı odadaki bir oyuncuyu engelleyebilir mi? Oda içinden hayır, çünkü Mini App oyuncunun kimliğini bilmez. Kullanıcı uygulamanı engellerse bütün koltukları düşer; şikâyet için Mini App'in ••• menüsündeki "Bildir"i kullanır.

Mini App'imin sunucusu yok; oda açabilir miyim? Evet: Inki.inkiCreateGameRoom ile kullanıcı odayı açar ve davet bağlantısını paylaşır (Sunucusuz Mini App). Bu odalar yalnız relay sınıfındadır.

Oyuncunun bağlantısı neden kendiliğinden düştü? Kullanıcının oturumu kapanmış (4401), ebeveyn kilidi açılmış, koltuktan çıkarılmış ya da oda kapanmış olabilir. Yeni bilet iste; bilet isteğinin error değeri nedeni söyler.