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ış#
- 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). - Sunucun odayı açar:
inkiCreateGameRoom(oyuncular, oda sınıfı). Yanıttakiroom_id'yi (bo_…) oyuncuların Mini App'ine iletirsin (Oda açmak). - 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. - Mini App bağlanır:
new WebSocket(url, ['inko.v1', 'inko.bilet.' + ticket])(Mini App'ten bağlanmak). - Oda karşılar: sunucu ilk iletide
oyun.durumgönderir: senin koltuk numaran (ben), odadaki koltuklar ve bağlı olanlar (Protokol). - Oyun oynanır.
relayodasında hamleler herkese gider;hostodasında yalnız senin hakem sunucuna gider ve tahtayı o yayınlar (Oda sınıfları). - Oyun biter. Odayı
inkiCloseGameRoomile (ya da hakembitirile) kapatırsın, skorusetGameScoreile yazarsın. Kapanışinki_game_roomupdate'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öntemiinkiCreateGameRoomile aynı adı taşır ama farklı bir şeydir: odayı kullanıcı açar, oda her zamanrelaysınıfındadır, açan kişi 1. koltuğa oturur.paramsboş 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ğiTelegram.WebApp.initDataUnsafe.start_param'da gelir ve sayfanInki.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_roomgelir. - Olay adı
inki_request_game_room {game_short_name?}, yanıtinki_game_room_requested {status:"created", room_id, invite_url}ya da{status:"failed", error}.errordeğerleriinkiJoinGameRoomile 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 gider | Odadaki herkese (oyun.hamle {k, d}) | Yalnız hakeme (senin sunucun) |
| Herkes neyi görür | Diğer oyuncuların ham hamlelerini | Yalnız hakemin yayınladığını (oyun.yayin) ve kendine özel olanı (oyun.ozel) |
| Kural kimde | Her istemcide (platform yalnız göndereni ve sırayı garanti eder) | Senin sunucunda |
| Hileye karşı | Koruma yok | Yetkili durum sende |
| Oyuncular | 2–8 | 1–8 + hakem |
| Tanışıklık şartı | Var: oyuncular birbirini tanımalı | Yok: yabancılar eşleşebilir |
| Gecikme | En düşük (tek atlama) | İki atlama (oyuncu → oda → hakem → oda → oyuncular) |
- **Rekabetçi oyunda ve yabancıyla eşleşmede
hostkullan.**relayodası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 biletiunavailablealır ve odaunavailablesebebiyle kapanır. - **Yabancılar (
host):**hostodası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öntem | Parametreler (* zorunlu) | Döner |
|---|---|---|
inkiCreateGameRoom | players* (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 |
inkiGetGameRoom | room_id* | GameRoom (bağlı koltuklar dahil) |
inkiAddGameRoomPlayer | room_id*, user_id* | GameRoom (yeni koltukla) |
inkiRemoveGameRoomPlayer | room_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 |
inkiCloseGameRoom | room_id* | true — oda bot sebebiyle kapanır |
inkiGetGameRoomHostTicket | room_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
}}
| Alan | Anlamı |
|---|---|
room_id | bo_ + 20 onaltılık karakter. Tahmin edilemez; tek başına hiçbir yetki vermez |
mode | relay | host |
status | open | closed |
game_short_name | Verdiysen |
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_at | Unix zamanı; closed_at yalnız kapalı odada |
close_reason | Kapalı odada: bot · idle · lifetime · unavailable · suspended · server (Update) |
max_idle_seconds | Hiç 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.authbiletin nasıl verileceğini söyler: Her zamanr.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ı4401ile 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
agedöner). Beyandan sonra isteği kendisi yeniden dener, bileti o zaman verir; kullanıcı vazgeçerseagedö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.inkiCreateGameRoomiçin de geçerlidir. room_idbo_+ 20 onaltılık karakter değilse istek gönderilmez,not_founddö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.jsyüklüyseInki.inkiJoinGameRoomveInki.inkiCreateGameRoommobildeki gibi çalışır. Yalnız resmîtelegram-web-app.jsile: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'yewss://app.inkiveta.comekle; 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
}
}
4401bilet 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,
1006görürsün. Bunu4401gibi ele al; oda gerçekten kapandıysa bir sonraki bilet isteğicloseddöner. resumeyalnı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ıyorsaoyun.ring {tazele: true}gelir: tahtayı baştan kur (hostodasında hakemoyun.koltukBaglandigö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.
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.- Sunucundan
url'ye bağlan: biletiX-Oyun-Biletbaşlığında, alt protokol olarakinko.v1ile 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,Originbaşlığı göndermez. - Gelen
oyun.hamle {k, d}'yi kendi kuralınla denetle; sonucuyayin(herkese) ya daozel(tek koltuğa) ile gönder; oyun bitincebitir.
| Hakem gönderir | Etkisi |
|---|---|
{"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 herkeseoyun.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 | İleti | relay | host |
|---|---|---|---|
| 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_idile yazıldıysa o satırgetGameHighScoresyanıtındaroom_verified: truetaşır; öyle yazılmayan satırda alan hiç yoktur. room_verifiedyalnı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:
| Konu | Sınır |
|---|---|
| Bilet | 30 saniye, tek kullanım |
| Bilet isteği | Kiş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ğlanma | Bilet sahibi başına 60 saniyede 30 |
| İleti boyu | Oyuncu ≤ 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ği | Oda başına saniyede 512 KiB; aşılırsa oda server sebebiyle kapanır |
resume | Saniyede 1, tepe 3; halka son 128 olayı tutar |
| Koltuk | 1–8 oyuncu (relay en az 2) + 1 hakem |
| Boşta kapanma | Hiç 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:
| Konu | Test ortamı | Gerçek | Doğrulanmış uygulama |
|---|---|---|---|
| Aynı anda açık oda | 20 | 200 | 2.000 |
| Oda açma hızı | saniyede 1 | saniyede 5 | saniyede 20 |
| Günlük oda (kayan 24 saat) | 500 | 20.000 | 200.000 |
| Kişi başına açık koltuk (bütün uygulamalar) | 5 | 5 | 5 |
| Kişi başına açık koltuk (aynı uygulama) | 2 | 2 | 2 |
- "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çma429döner; bağlantı kapasitesi dolarsa el sıkışma1013ile kapanır, jitter'la yeniden dene. GAME_ROOM_PLAYERS_INVALIDhataları uygulama başına sayılır: 24 saatte 200'ü aşarsa oda açma 1 saat429döner.
Kurallar#
- **
relayodasında oyuncular tanışık olmalı.** Tanışık olmayanları eşleştirmek istiyorsanhostodası 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.
inkiGiftInkbir 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
unavailablesebebiyle kapanır. Kullanıcı uygulamanı engellerse odalardaki bütün koltukları düşer. - Davet: kişiyi odaya çağırmak senin işindir: sohbetinden
web_appdüğ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.ozeliletileri 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_SUSPENDEDdöner, açık odalarsuspendedsebebiyle 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}}
reason | Ne oldu |
|---|---|
bot | inkiCloseGameRoom ya da hakemin bitir'i |
idle | Bağlı koltuk kalmadı ve max_idle_seconds doldu; ya da oda kurulup 10 dakika içinde kimse bağlanmadı |
lifetime | 4 saatlik oda ömrü doldu |
unavailable | Bir oyuncu artık odada olamıyor (engel, hesap silme, tanışıklık…). Ayrıntı verilmez |
suspended | Uygulamanın oyun odaları askıya alındı |
server | Oda bant genişliği aşıldı ya da platform tarafında bir sorun oldu |
eventşimdilik yalnızclosed.played, kişinin odaya en az bir kez bağlanıp bağlanmadığıdır.- Koltuk bağlandı / ayrıldı bilgisi update olarak gelmez:
hostodasında hakem bunu soketten alır,relayodasındainkiGetGameRoomile sorarsın.
Hata kodları#
Bot API:
| Hata | Ne zaman |
|---|---|
400 Bad Request: GAME_ROOM_PLAYERS_INVALID | Bir 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_INVALID | Bilinmeyen mode; relay'de 2'den az oyuncu |
400 Bad Request: GAME_SHORTNAME_INVALID | game_short_name Atölye'de kayıtlı değil |
400 Bad Request: GAME_ROOM_NOT_FOUND | Oda 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_CLOSED | Kapalı odaya oyuncu ekleme / çıkarma ya da hakem bileti |
400 Bad Request: GAME_ROOM_FULL | 8 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_PLAYED | setGameScore'daki game_room_id doğrulanmadı (Skor) |
400 Bad Request: USER_ID_INVALID | inkiRemoveGameRoomPlayer: kişi bu odada koltukta değil |
400 Bad Request: max_idle_seconds must be between 30 and 600 | max_idle_seconds aralık dışı |
403 Forbidden: GAME_ROOMS_SUSPENDED | Uygulamanın oyun odaları askıda |
429 Too Many Requests: retry after N | Bir sınır aşıldı (Sınırlar) |
**Köprü (Inki.inkiJoinGameRoom, Inki.inkiCreateGameRoom) error değerleri:**
error | Anlamı | Ne yapmalı |
|---|---|---|
not_found | Oda yok ya da kullanıcının bu odada koltuğu yok | Durma; kullanıcıya göster |
closed | Oda kapandı | Durma |
parental | Ebeveyn denetimi oyunları kapatmış | Durma; kullanıcı nedeni görür |
age | Yaş kapısı (yaş doğrulanmamış ya da yetişkin dereceli uygulama) | Durma |
suspended | Uygulamanın oyun odaları askıda | Durma |
rate | Çok sık istek ya da süren bir istek var | Jitter'la bekleyip tekrar dene |
unavailable | Kullanıcı bu odaya giremiyor (engel, tanışıklık…) ya da bağlantı sorunu | Birkaç kez jitter'la dene, sonra vazgeç |
WebSocket kapanış kodları:
| Kod | Anlamı | Ne yapmalı |
|---|---|---|
1008 | Hı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 |
1013 | Geçici (kapasite dolu, sunucu yeniden başlıyor ya da sunucu durumu bilinmiyor) | Jitter'la yeni biletle yeniden dene |
4401 | Bilet ya da oturum geçersiz (kullanıcının oturumu kapandı, bilet süresi doldu, koltuktan çıkarıldı…) | Aynı bileti deneme; yeni bilet iste |
4403 | Uygulamanın oyun odaları askıda | Yeniden bağlanma |
1006 | El 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.