Realtime genel bakış
Bu sayfa, Open Play’in sunduğu üç WebSocket’i ve hangisini ne zaman kullanacağınızı anlatır. Oyun içi durum (hareket, oda, sahne) için eklenti realtime soketini, bildirim ve sohbet için ise ayrı iki soketi kullanırsınız; hepsinin kimlik ve kapanış kuralları farklıdır.
Üç soket
| Soket | Yol | Ne için | Kim konuşur | Kimlik |
|---|---|---|---|---|
| Realtime (eklenti) | /v1/realtime/ws | Oyun durumu: anlık girdi, durum anlık görüntüsü (snapshot), kalıcı komut ve olay | İki yönlü | Tek kullanımlık bilet (ticket) |
| Bildirim | /v1/ws | Bildirimin oyuncuya canlı itilmesi | Yalnız sunucu → oyuncu | Oyuncu oturumu (çerez ya da Bearer) |
| Sohbet | /v1/chat/ws | Kanal sohbeti (abone ol, mesaj gönder) | İki yönlü | Oyuncu oturumu (çerez ya da Bearer) |
Kural: üçü de oyuncu soketidir. Sunucu anahtarı (server key) ile soket açılmaz; sunucudan sunucuya iş için REST uçlarını kullanın.
Hangisini kullanmalıyım
| İhtiyaç | Seçim |
|---|---|
| Aracın, oyuncunun ya da odanın anlık durumunu yayınlamak ve oyuncu girdisini sıralı almak | Realtime soketi, protokol |
| Bir komutun sonucunu kalıcı ve tekrar-güvenli almak (ödül, teslimat) | Realtime Command çerçevesi ya da HTTP komut ucu (eklentileri çağırma) |
| Oyuncuya “yeni bildirim” anlık göstermek | /v1/ws; kalıcı kaynak her zaman GET /v1/notifications gelen kutusudur (bildirimler) |
| Kanal sohbeti | /v1/chat/ws ya da REST (sohbet) |
| Skor tablosu, mağaza, envanter | REST; bunlar için soket yoktur |
Not
TypeScript SDK’sı realtime soketini sizin yerinize yönetir: bilet alma, kimlik doğrulama, yeniden bağlanma ve anlık görüntü kurtarma dahildir. Elle protokol yazmanız yalnız SDK’sı olmayan bir istemci (ör. Unity yerel soketi) için gerekir. SDK kullanımı için TypeScript SDK sayfasına bakın.
Bağlantı koşulları (ortak)
- HTTPS ve izinli origin. Tarayıcı oyununuz API’yi ters vekille aynı kökenden ya da alan adı bir ortamda kayıtlıysa doğrudan Open Play adresinden (CORS) çağırır. Soketler aynı adrese açılır:
wss://<oyun-alan-adınız>/<yol>ya dawss://<open-play-adresi>/<yol>; el sıkışmasındaOriginortam başına denetlenir (CORS bunu değiştirmez). Ayrıntı: mimari ve barındırma. - Ortam başlığı. Oyuncu kimliği her zaman bir ortama (environment) bağlıdır ve
x-crx-env: <ortam uuid>başlığı gerekir. Realtime soketinde başlık HTTP bilet isteğiyle verilir; WebSocket yükseltmesi başlık taşımaz, bilet ortamı bilir./v1/wsve/v1/chat/wsise başlığı yükseltme isteğinin kendisinde ister. Tarayıcının WebSocket API’si özel başlık ekleyemez; bu yüzden bu iki soket tarayıcıdan doğrudan açılamaz (bilinen kısıt). Tarayıcı oyunlarında bildirim için gelen kutusunu REST ile yoklayın, sohbet için REST uçlarını kullanın; tarayıcı dışı istemciler başlığı kendileri gönderebilir. - Sorgu dizesinde jeton yok. Hiçbir soket oturum jetonunu URL’de kabul etmez; erişim günlüklerine sızmasın diye
?token=desteklenmez. Realtime yükseltmesi sorgu dizesi taşıyorsa reddedilir. - Origin başlığı zorunludur (realtime): hem bilet isteği hem yükseltme
Origintaşımalıdır ve ortamın izinli kökenlerinden biri olmalıdır. Tarayıcı bunu kendisi ekler; tarayıcı dışı bir istemciyse izinli birOrigindeğerini kendiniz göndermelisiniz. - Modül kapısı. Realtime soketi
plugins,/v1/wsnotifications,/v1/chat/wschatmodülüne bağlıdır. Modül kapalıysa yükseltme404vemodule_disableddöner; açık soket, modül sonradan kapanırsa1008(nedenmodule_disabled) ile kapatılır, kapı durumu doğrulanamıyorsa1013ile. Modülleri panelden yönetirsiniz: Oyun ayarları: modüller.
Bildirim soketi (/v1/ws)
- Yalnız sunucudan oyuncuya akar. İstemciden gelen çerçeveler yok sayılır.
- Gelen çerçeve bir JSON nesnesidir:
{"type":"notification","notification_id":"…","title":"…","body":"…","data":{…},"channel":"in_game","sent_at_ms":1760000000000}. Alan adlarısnake_case’dir. - Canlı çerçeve en çok bir kez (at-most-once) teslim edilir. Kalıcı kaynak gelen kutusudur; aynı bildirim hem çerçeveyle hem gelen kutusu sorgusuyla gelebilir,
notification_idile tekilleştirin. - Bağlantı presence (çevrimiçi) sinyali olarak sayılır.
Sohbet soketi (/v1/chat/ws)
Çerçeveler type alanı (camelCase değerli) ile ayrılır; diğer alan adları snake_case’dir ve bilinmeyen alan reddedilir. Örnek: {"type":"send","channel_id":"…","client_message_id":"retry-1","body":"merhaba"}.
| Yön | type | Alanlar | Anlam |
|---|---|---|---|
| İstemci → sunucu | subscribe | channel_id | Kanal aboneliği (aynı anda tek kanal) |
| İstemci → sunucu | unsubscribe | — | Aboneliği bırakır |
| İstemci → sunucu | send | channel_id, client_message_id, body | REST ile aynı tekrar-güvenli mesaj gönderme |
| İstemci → sunucu | ping | nonce (sayı) | Canlılık yoklaması |
| Sunucu → istemci | subscribed / unsubscribed | channel_id (yalnız subscribed) | Kabul |
| Sunucu → istemci | message | message, duplicate | Kanal mesajı; duplicate: true ise client_message_id daha önce işlenmişti |
| Sunucu → istemci | pong | nonce | ping yanıtı |
| Sunucu → istemci | error | code | invalid_frame, invalid_payload, forbidden_channel, unavailable, message_rejected, modül kapanırken module_disabled |
Mesaj gönderme sınırı: oyuncu başına 10 saniyede 20 mesaj; aşımı message_rejected ya da REST’te 429 olarak görürsünüz (hız sınırları). Ayrıntılı kullanım için sohbet rehberi.
Sıradaki adım
- Eklenti realtime protokolünü baştan sona görmek için protokol.
- Bağlantı koptuğunda ne olduğunu, limitleri ve boşta kapanmayı görmek için yeniden bağlanma ve limitler.