Sık sorulan sorular

Bu sayfa, entegrasyonda en sık gelen soruları kısa yanıtlarla toplar. Ayrıntı için bağlı sayfalara geçin.

Başlangıç ve topoloji

Sunucu anahtarını oyunun içine koyabilir miyim? Hayır. Sunucu anahtarı yalnız sizin sunucunuzdadır. Oyun istemcisi oyuncu oturumuyla çalışır; istemciye gömülen anahtar gerekiyorsa istemci anahtarı vardır, ama onun da çağırabildiği uçlar sınırlıdır ve bazı uçlarda anahtar türü kapısı yoktur (güvenlik, uç noktalar).

Neden CORS hatası alıyorum? Oyunun alan adı bir ortamın alan adı listesinde (ya da operatörün genel izinli listesinde) değilse sunucu o origin’e CORS başlığı vermez. Alan adını panelden ekleyin; origin tam https://<alan adı> olmalıdır. Oyun, Open Play’den farklı bir kayıtlı alan adındaysa oturum çerezi (SameSite=Lax) gitmez; o durumda aynı köken ters vekil kullanın. Kendi vekilinize ek CORS başlığı eklemeyin (mimari ve barındırma).

Oyunum mobil uygulama ya da Unity masaüstü; tarayıcı kısıtları geçerli mi? CORS ve aynı site kuralı yalnız tarayıcıyı ilgilendirir. Tarayıcı dışı istemciler çerez yerine Bearer oturum jetonu kullanabilir; ama eklenti komutlarında CSRF çifti ve realtime bilet isteğinde Origin gibi kurallar yine geçerlidir (eklentileri çağırma, protokol). Unity için Unity SDK.

Open Play’in gRPC arayüzünü kullanabilir miyim? Dışa açık bir yüzey olarak desteklenmiyor. Oyun entegrasyonları REST, WebSocket ve SDK’lar üzerindendir.

Hangi SDK’lar var? TypeScript (@ferdiunal/open-play-ts) ve Unity (com.openplay.sdk). Tipli CrxClient’ı olmayan modüller için ham REST kullanırsınız (uç noktalar). Ayrıntı TypeScript SDK ve Unity SDK sayfalarında.

Kimlik

Sunucu bir oyuncunun kim olduğunu nasıl doğrular? Oyuncu girişinde dönen erişim JWT’sini oyun sunucunuz JWKS ile çevrimdışı doğrular (sunucu doğrulaması). Oturum jetonu ya da çerez değildir.

Oturum ne kadar yaşar? 30 gün kayar (günde bir istek yeterlidir), mutlak tavan 180 gündür. Açık bir realtime soketi oturumu yaşatmaz (güvenlik).

Yasaklı oyuncuya ne olur? Giriş uçlarında, sahiplik kanıtlandıktan sonra 403 ve account_banned alır; diğer uçlarda 401 görünür. Eklenti uçlarında 403 forbidden (message: account banned) (hatalar).

Tekrar güvenliği, sürüm, sayılar

Idempotency-Key ne zaman yeni üretilir? Her yeni işlem için. Aynı işlemin yeniden denemelerinde aynı anahtar kullanılır; belirsiz sonuçlu komutu yeni anahtarla tekrarlamak çift uygulamaya yol açar (idempotency).

409 aldım. Aynı isteği tekrarlasam olur mu? İki farklı 409 vardır: sürüm çakışmasında (version conflict) önce durumu yeniden okuyun; “işleniyor” (idempotent request in progress) yanıtında aynı anahtarla kısa süre sonra tekrar edin.

Bakiye neden büyük bir tam sayı? Para küçük birimli tam sayıdır; kayan nokta hiçbir yerde kullanılmaz. Gösterim ondalığını kendiniz hesaplarsınız (sayılar ve kodlama).

Neden bazı sayılar metin olarak geliyor? Eklenti ve realtime int64 alanları JavaScript number’ının güvenli aralığını aşabilir; bu yüzden ondalık metin taşınır. TypeScript SDK’sı bunları bigint yapar.

Yüzde alanları neden 10000 üzerinden? Baz puan: 10000 = %100 (sayılar ve kodlama).

Hata gövdesi neden bazen düz metin, bazen JSON? Çekirdek REST düz metin döner (birkaç JSON istisna), eklenti uçları her zaman JSON döner. Karar için durum koduna ve varsa code alanına bakın (hatalar).

Hız sınırları

Anahtar başına istek sınırı var mı? Hayır; genel bir kota yok. Belirli işlemlerin (giriş, kayıt, sohbet, eklenti komutları, soket bağlantısı) sınırları vardır. Büyük toplu işlerde kendi eşzamanlılık sınırınızı uygulayın (hız sınırları).

Lansmanda yüzlerce misafir aynı anda açılacak. Sorun olur mu? Misafir açma IP başına dakikada 30’dur. Oyuncular ayrı IP’lerdense sorun olmaz; ama ters vekiliniz istemci IP’sini iletmiyorsa hepsi tek kovada toplanır. IP iletimini doğrulayın ve yük testi yapın (üretim kontrol listesi).

Eklentiler

Kendi eklentimi yükleyebilir miyim? Hayır, henüz yok. Eklentiler sunucuya derlenmiş güvenilir koddur; üçüncü taraf yükleme ve yalıtım yoktur. Bugünkü yollar: kurallar, webhook’lar ve kendi sunucunuz (eklentilere genel bakış).

Eklenti şeması değişti, istemcim bozulur mu? Eklenti şemaları özetle (schemaSha256) sabitlenir. Sunucu şemayı değiştirirse eski bağlama uyuşmazlığı görür ve güncel belgeden yeniden üretmeniz gerekir (bağlamalar).

Eklenti çağrısı 403 forbidden döndü. Neden? Çoğunlukla eklenti ortamınızda etkin değildir ya da yetki sürümü sunucudakiyle uyuşmuyordur; ya da CSRF/Origin reddi. Panelde eklentinin durumuna bakın (Eklentiler).

Realtime

Soket kopunca ne yapmalıyım? Yeni bilet alın, yeniden bağlanın ve kalıcı akışlarda son imleçle yeniden katılın; ResyncRequired gelirse imleçsiz katılın. TypeScript SDK’sı bunu kendiliğinden yapar (yeniden bağlanma).

Soket neden 5 dakikada bir kapanıyor? Girdi kabul eden bir abonelikte oyuncu etkinliği gelmediği için sunucu boşta kapatır (4100). “Devam et” ekranı gösterin ya da canlı tutma girdisi gönderin.

Bildirim ve sohbet için soket kullanabilir miyim? Tarayıcıdan doğrudan hayır: /v1/ws ve /v1/chat/ws yükseltmede x-crx-env başlığı ister ve tarayıcı bunu ekleyemez. Tarayıcıda gelen kutusunu REST ile okuyun, sohbet için REST uçlarını kullanın (realtime genel bakış).

Webhook’lar

Webhook’ları imzasız kabul edebilir miyim? Hayır. Her isteğin imzasını ham gövde üzerinde doğrulayın ve X-Crx-Event-Id ile tekilleştirin (güvenlik).

Kaçırdığım olayı yeniden gönderebilir miyim? Panelde yeniden gönderme eylemi yoktur; teslimatlar yalnız izlenir. İlgili kaynağın durumunu REST ile okuyarak telafi edin.

Yönetim

Anahtarı kaybettim, geri alabilir miyim? Hayır; gizli değer yalnız oluşturma anında gösterilir. Yeni anahtar üretin ve eskisini iptal edin (güvenlik).

Panelde ne yapabilirim, API ile ne yapmalıyım? Panel, oyunun yönetimi içindir (içerik, mağaza, ekonomi raporları, kurallar, ayarlar). Oyun içi akışlar API ve SDK ile yapılır. Panel ekranları için ilgili panel yardım sayfalarına bakın.

Dokümanda bulamadığım bir şey var. Önce sorun giderme ve sözlüğe bakın; bulamazsanız sorunuzu durum kodu, yol ve zaman bilgisiyle iletin.