English

Switch to the English documentation

Open Play geliştirici dokümanı

Oyununuzu Open Play’e bağlamak ve yönetim panelini kullanmak için sayfalar aşağıdadır. Türkçe sayfalar kaynaktır; İngilizce sürüm çeviridir.

Henüz yazılmamış sayfalar planlıdır; bağlantıları sayfa eklenince çalışır. Durum: pages.yaml (docs/developer/pages.yaml).

Başlarken

• Genel bakış
• Temel kavramlar
• Hızlı başlangıç
• Mimari ve barındırma
• Yapay zekâ araçlarıyla kullanım (MCP)
• Oyununuz için AGENTS.md

Kimlik doğrulama

• Genel bakış
• Misafir girişi
• E-posta ve parola
• OAuth ile giriş
• Oturumlar ve CSRF
• Hesap bağlama
• Hesabı silme
• Sunucuda doğrulama

SDK’lar

• TypeScript SDK
• Unity SDK

Rehberler

• Karakterler
• Envanter ve eşyalar
• Ekonomi
• Mağaza ve uygulama içi satın alma
• Ödüller
• Sosyal özellikler
• Sohbet
• Yarışma ve skor tabloları
• Bildirimler
• Webhook’lar
• Sahneler, varlıklar ve modeller
• İçerik grupları
• Oyun kuralları
• Oyuncu verisi (bulut kaydı)

Gerçek zamanlı

• Genel bakış
• Protokol
• Yeniden bağlanma ve sınırlar

Eklentiler

• Genel bakış
• Eklenti yazmak
• Eklentileri çağırma
• Üretilmiş bağlayıcılar

Başvuru

• Hatalar
• Idempotency ve eşzamanlılık
• Sayfalama
• Hız sınırları
• Sayılar ve kodlama
• Sürümleme
• Uç noktalar (üretilir)
• Webhook olayları (üretilir)
• Sözlük

Operasyon

• Güvenlik
• Canlıya çıkış kontrol listesi
• Sorun giderme
• Sık sorulan sorular

Panel yardım sayfaları

• Oyuncular
• API anahtarları

Panel sayfaları yönetim panelindeki “Yardım” çekmecesinin ve bilgi balonlarının kaynağıdır.

Open Play’e genel bakış

Bu sayfa, Open Play’in oyununuz için hangi hazır parçaları sunduğunu ve bu parçalarla hangi kanaldan konuşacağınızı özetler. Entegrasyona başlamadan önce okuyun; ayrıntılar için her bölümün sonundaki bağlantıları izleyin.

Open Play nedir?

Open Play, oyunların arka uç ihtiyaçlarını tek bir sunucu olarak karşılar: oyuncu kimliği ve oturumu, karakterler, envanter, ekonomi, mağaza, ödüller, sosyal özellikler, skor tabloları, bildirimler, webhook’lar ve gerçek zamanlı bağlantı. Oyununuzu bu sunucuya HTTP (REST) ve WebSocket üzerinden bağlarsınız; oyunu yöneten ekip aynı sunucuyu yönetim panelinden yapılandırır.

Not

Open Play bugün bir Docker Compose yığınıdır ve sizin ya da ekibinizin altyapısında çalışır. Kurulum ve dağıtım için üretim dağıtımı rehberine (docs/production-and-adapters.tr.md) bakın; bu belge oyun geliştiricisinin bakış açısını anlatır.

Neler sunar? Modül haritası

Özelliklerin çoğu modül olarak açılıp kapatılır. Kapalı bir modülün uçları çalışmaz ve 404 ile module_disabled kodunu döndürür (bkz. Kavramlar). Modüller panelde Oyun ayarları › Modüller sekmesinden yönetilir.

Modül anahtarı olmayan çekirdek yüzeyler her zaman açıktır:

• Oyuncu kimliği ve oturumu: misafir, e-posta/parola, Google. Bkz. Kimlik doğrulama.
• İçerik grupları ve katalog: panelden yönetilen, oyunun okuduğu veri. Bkz. İçerik grupları.
• Oyun kuralları ve otomasyonlar. Bkz. Oyun kuralları.
• API anahtarları, ortamlar ve alan adları. Bkz. Kavramlar.

Hangi kanaldan konuşursunuz?

Uyarı

Sunucu anahtarı bir sırdır. Tarayıcıya, mobil uygulamaya ya da oyun paketine koymayın. İstemci tarafında yalnızca oyuncu oturumu ve (gerekirse) istemci anahtarı kullanın.

gRPC arayüzü sunucu tarafında vardır ancak oyun geliştiricisi için dışa açık bir kanal değildir; varsayılan olarak yalnız loopback’te dinler ve SDK’lar kullanmaz. Bu belge onu anlatmaz.

Nereden başlamalı?

1. Kavramlar: stüdyo, oyun, ortam, modül, anahtar türleri, oyuncu oturumu.
2. Hızlı başlangıç: ilk sunucu çağrınız ve ilk oyuncu girişiniz.
3. Mimari ve barındırma: aynı köken (same-origin) kuralı, alan adları, neyin nerede çalıştığı.
4. Kimlik doğrulama ve SDK’lar.

Bugünkü sınırlar

Aşağıdakiler bilinçli olarak dürüst yazılmıştır; yol haritanızı buna göre kurun.

• CORS yalnız ortamın alan adı listesindeki origin’lere açıktır ve çerez aynı site ister. Tarayıcı oyunu, alan adı bir ortama bağlıysa Open Play’i doğrudan çağırabilir; oyun Open Play’den farklı bir kayıtlı alan adındaysa SameSite=Lax oturum çerezi gitmez (ters vekil kullanın). Bkz. Mimari ve barındırma.
• Üçüncü taraf eklenti yükleme desteklenmez. Eklentiler sunucuya derlenmiş olarak gelir; panelden eklenti yüklenmez. Bkz. Eklentiler.
• SDK kapsamı kısmidir. TypeScript SDK’sında tipli istemci olmayan modüller ham REST ile kullanılır. Bkz. TypeScript SDK.
• Unity’de yalnız Unity 6000.6.7f1 doğrulanmıştır. Bkz. Unity SDK.
• Hata gövdeleri çoğunlukla düz metindir. Yalnız birkaç yerde JSON hata zarfı vardır. Bkz. Hatalar.

Temel kavramlar

Open Play’de her şey birkaç kavramın etrafında döner: verinin ait olduğu ortam, özellikleri açıp kapatan modüller, iki farklı API anahtarı türü, oyuncunun oturumu ve oyuna özel mantığı taşıyan eklenti. Bu sayfayı bir kez okuyun; diğer sayfalar bu kelimeleri bilindiğini varsayar.

Stüdyo, oyun, ortam

Open Play üç katmanlı bir hiyerarşi kullanır. Panelde Stüdyolar ve oyunlar ekranında (yalnız süper yönetici görür) bu ağacı yönetirsiniz.

Ortam, veri sınırıdır. Bir ortamdaki oyuncu, karakter, cüzdan ya da anahtar başka bir ortamdan görünmez. Her API çağrısı tek bir ortama karşı çalışır:

• API anahtarıyla yapılan çağrılarda ortam anahtardan çıkar; ayrıca bir başlık göndermezsiniz.
• Oyuncu oturumuyla yapılan çağrılarda ortamı x-crx-env: <ortam-kimliği> başlığıyla siz bildirirsiniz. Kimlik bir UUID’dir. SDK’lar bunu environmentId ayarından gönderir.

Not

Panel bugün ortam kimliğini (UUID) okunur bir alanda göstermez. Kimliği operatör ekibinizden isteyin ya da panel oturumundaki Oyun ayarları › Modüller sekmesinin yaptığı GET /v1/panel/modules isteğinin yanıtındaki environmentId alanından okuyun. Bu eksiklik kayıtlıdır.

Panel adımları için bkz. Hızlı başlangıç ve Oyun ayarları.

Modüller

Özelliklerin çoğu modüldür: characters, economy, items, trading, store, rewards, social, chat, competition, notifications, webhooks, scenes, plugins (13 modül). Modüller ortam başına açılıp kapatılır; kurulumda sihirbaz bir başlangıç kümesi seçtirir, sonrasında Oyun ayarları › Modüller sekmesi kullanılır (yalnız süper yönetici).

• Kapalı modülün uçları çalışmaz: HTTP 404 ve gövde {"code":"module_disabled","message":"…","module":"<ad>"}. Kimliği geçersiz çağıran 401 alır; modülün kapalı olduğunu öğrenemez.
• Kapatmak veriyi silmez, yalnız yüzeyi durdurur; yeniden açınca veri yerindedir.
• Bazı modüller başkalarına bağlıdır (örneğin trading, economy ve items’a dayanır) ve etkin bir eklentinin ihtiyaç duyduğu modül kapatılamaz.
• Çekirdek yüzeyler (oyuncu girişi, içerik grupları, API anahtarları) modül değildir ve kapatılamaz.

Hata ayrıntıları için bkz. Hatalar.

API anahtarları: sunucu ve istemci

API anahtarı, bir ortama bağlı gizli bir dizgedir ve Authorization: Bearer başlığıyla gönderilir. Biçimi:

crx_live_<önek>_<gizli>

Panelde yalnız crx_live_<önek> kısmı (önek) görünür; gizli değer oluşturulduğu anda bir kez gösterilir ve geri alınamaz. Kaybederseniz yeni anahtar oluşturur ya da anahtarı döndürürsünüz (rotate): eski gizli değer geçersiz olur, yenisi bir kez gösterilir.

Kesin kural uç noktaya göre değişir ve kodda uç nokta başına sınanır. Hangi ucun hangi anahtar türünü kabul ettiği uç nokta başvurusunda listelenir. Anahtar türü yetersizse çağrı 403 alır.

Panelde anahtar oluşturma: Oyun ayarları › API anahtarları › Yeni API anahtarı (bkz. API anahtarları). Oluştururken ad, tür (Sunucu anahtarı ya da İstemci anahtarı), geçerlilik süresi ve denetim kaydına yazılan bir not (8–500 karakter) girilir.

Uyarı

Gelişmiş ayarlar (kapsam etiketleri, izinler, ek bilgiler) bugün yalnızca kayıt amaçlıdır; anahtarın neye erişebileceğini kısıtlamaz. Erişimi yalnızca anahtar türü belirler. Sunucu anahtarını “kısıtlı” saymayın.

Anahtar ve gizli değer yönetimi için bkz. Güvenlik.

Oyuncu oturumu

Oyuncular API anahtarıyla değil, kendi oturumlarıyla konuşur. Oturum şu yollarla açılır: misafir girişi, e-posta ve parola, Google. Başarılı girişte sunucu bir oturum çerezi (__Secure-crx.session) ve bir yenileme çerezi (__Secure-crx.refresh) yazar; aynı belirteçler yanıt gövdesinde de döner, böylece çerezsiz istemciler (Unity yerel derlemesi, komut satırı araçları) Authorization: Bearer <oturum-belirteci> kullanabilir.

Oyuncu oturumuyla yapılan her istek x-crx-env başlığı taşır. Çerezli (tarayıcı) oturumda durum değiştiren istekler ayrıca CSRF koruması ister (x-csrf-token başlığı). Bu ayrıntıları SDK’lar sizin yerinize yönetir; ham REST’te kendiniz uygularsınız:

• Kimlik doğrulamaya genel bakış
• Oturumlar ve CSRF

Oyuncu oturumu oyun sunucunuza da taşınabilir: oyuncunun kısa ömürlü erişim JWT’si (EdDSA) ortak bir JWKS ile çevrimdışı doğrulanır. Bkz. Sunucuda doğrulama.

Eklenti (plugin)

Eklenti, bir oyuna özel sunucu mantığını (komutlar, sorgular, gerçek zamanlı modüller) taşıyan, sunucuya derlenmiş bir pakettir. Eklenti çağrıları /v1/plugins/{eklenti}/... altında yapılır; durum değiştiren komutlar idempotency anahtarı taşır ve şema isterse expectedVersion ile sürüm denetimi yapar. Eklentinin şeması bir artefakttır (<eklenti>.plugin.schema.json) ve TypeScript/Unity bağlamaları bu şemadan üretilir.

Not

Üçüncü taraf eklenti yükleme (panelden ya da API’den) bugün desteklenmez. Eklentiler Open Play sunucusunun yayınıyla birlikte gelir. Bkz. Eklentilere genel bakış.

Ortak çağrı kuralları

Birçok uçta aynı üç kural geçerlidir; ayrıntıları başvuru sayfalarında bulursunuz:

• Idempotency-Key: durum değiştiren komutlarda aynı anahtar ve aynı gövde sonucu yeniden oynatır; aynı anahtarla farklı gövde 422 verir. Bkz. Idempotency ve eşzamanlılık.
• If-Match / expectedVersion: kaynağın okuduğunuz sürümünü bildirerek eşzamanlı yazma çakışmasını yakalarsınız (409).
• Sayılar: büyük tam sayılar (i64) JavaScript’te bigint olur; eklenti protokolünde ondalık dizge olarak taşınır. Bkz. Sayılar ve kodlama.

Terimlerin kısa tanımı için bkz. Sözlük.

Hızlı başlangıç

Bu rehberde sıfırdan şunları yaparsınız: panelde bir oyun ve sunucu anahtarı oluşturur, curl ve TypeScript ile ilk sunucu çağrınızı atar, tarayıcı oyununuzdan bir oyuncuyu misafir olarak girdirir ve aynısını Unity’den yaparsınız. Yaklaşık yarım saat sürer. Başlamadan önce Kavramlar sayfasına göz atın.

Ön koşullar

• Çalışan bir Open Play sunucusu ve panele giriş yapabilen bir yönetici hesabı (süper yönetici). Kurulum için üretim dağıtımı rehberine (docs/production-and-adapters.tr.md) bakın.
• Sunucunun genel HTTPS adresi. Bu sayfada OPEN_PLAY_URL olarak anılır (örneğin https://oyun.example.com/open-play).
• Node.js 22 ya da üstü ve curl; ham REST örnekleri için jq ve openssl.

1. Oyun ve ortam oluşturun

Kurulum sihirbazı ilk stüdyoyu ve oyunu zaten açtıysa bu adımı atlayın.

1. Panelde Stüdyolar ve oyunlar ekranını açın ve Yeni stüdyo düğmesiyle bir stüdyo oluşturun.
2. Stüdyo kartında Yeni oyun’u seçin; oyunun adını (ve isterseniz kısa adını) girin. Oyunla birlikte dev ve prod ortamları otomatik oluşur.
3. Üst çubuktaki Aktif oyun ve ortam seçicisinden oluşturduğunuz oyunun dev ortamını seçin. Panelin geri kalanı seçili ortamın verisini gösterir.

Ayrıntılar: Stüdyolar ve oyunlar.

2. Modülleri kontrol edin

Oyun ayarları › Modüller sekmesinde bu rehberdeki çağrı için characters modülünün Açık olduğunu doğrulayın. Kapalı modül 404 ve module_disabled döndürür. Ayrıntılar: Modüller.

3. Sunucu anahtarı oluşturun

1. Oyun ayarları › API anahtarları sekmesinde Yeni API anahtarı’nı seçin.
2. Bir ad verin (örneğin Oyun sunucusu), türü Sunucu anahtarı seçin, geçerlilik süresini belirleyin ve denetim kaydı için kısa bir not yazın (8–500 karakter).
3. Oluştur’a basın. Açılan karttaki gizli değeri hemen kopyalayıp sunucunuzun gizli ayarlarına kaydedin. Bu değeri bir daha göremezsiniz.

Anahtar şu biçimdedir: crx_live_<önek>_<gizli>. Bu sayfada ortam değişkeni olarak kullanacağız:

export OPEN_PLAY_URL="https://oyun.example.com/open-play"
export OPEN_PLAY_SERVER_KEY="crx_live_<önek>_<gizli>"

Uyarı

Gerçek anahtarı belgeye, depoya, sohbete ya da günlüğe yazmayın. Sızdığından şüphelenirseniz anahtarı panelden döndürün (rotate) ya da silin.

4. İlk sunucu çağrınız

Sunucu anahtarıyla ortamdaki karakterlerin ilk sayfasını isteyin. Ortam anahtardan çıktığı için ek başlık gerekmez.

curl -sS "$OPEN_PLAY_URL/v1/characters?limit=1" \
  -H "Authorization: Bearer $OPEN_PLAY_SERVER_KEY"

Henüz karakter yoksa beklenen yanıt (200):

{"items":[],"next_cursor":null}

Aynı çağrı TypeScript SDK’sıyla (kurulum için TypeScript SDK):

import { CrxClient, CrxError } from "@ferdiunal/open-play-ts";

/**
 * Sunucu anahtarıyla ilk çağrı: ortamdaki karakterlerin ilk sayfasını okur.
 * Bu kod yalnızca güvenilen arka uçta çalışır; sunucu anahtarını tarayıcıya göndermeyin.
 */
export async function listFirstCharacters(baseUrl: string, serverKey: string): Promise<number> {
  const client = new CrxClient({ baseUrl, apiKey: serverKey });
  try {
    const page = await client.listCharacters({ query: { limit: 1 } });
    return page.items.length;
  } catch (error) {
    if (error instanceof CrxError) {
      // kind, status ve attempts güvenlidir; anahtar ve istek gövdesi hata nesnesine girmez.
      console.error("Open Play çağrısı başarısız:", error.kind, error.status);
    }
    throw error;
  }
}

// Kullanım (Node 22, ESM):
//   const count = await listFirstCharacters(process.env.OPEN_PLAY_URL!, process.env.OPEN_PLAY_SERVER_KEY!);

Olası sorunlar:

5. Oyununuzun alan adını ortama bağlayın

Tarayıcı, durum değiştiren isteklere Origin başlığı ekler; sunucu bu origin’in o ortama ait olduğunu denetler. Oyun sayfanızın alan adı tanımlı değilse oyuncu girişi 403 ile reddedilir.

1. Oyun ayarları › Ortamlar ve alan adları sekmesinde ilgili ortamın Alan adları alanına oyun sayfanızın alan adını yazın (satır başına bir alan adı; örneğin oyun.example.com). Joker karakter, IP ve port kabul edilmez.
2. Bir gerekçe yazın ve Alan adlarını kaydet’e basın.

Alan adı girmezseniz sunucunun genel izinli listesi geçerlidir; bu liste operatörün ayarıdır. Ayrıntılar: Mimari ve barındırma.

6. Tarayıcıdan ilk oyuncu girişi (misafir)

Oyun sayfanız API’yi ya aynı origin’den (ters vekil) ya da alan adı bir ortama bağlıysa doğrudan Open Play adresinden (CORS) çağırır (bkz. Mimari ve barındırma). Aşağıdaki kod kayıtlı oturumu geri yükler; yoksa misafir oturumu açar. environmentId, ortamın UUID’sidir.

import { createPlayerClient, type PlayerClient } from "@ferdiunal/open-play-ts";

/**
 * Tarayıcıdaki oyun sayfasından oyuncu oturumu açar: kayıtlı oturum varsa onu geri yükler,
 * yoksa misafir oturumu açar. `baseUrl` oyun sayfasıyla aynı origin'dir (aynı köken kuralı).
 */
export async function signInAsGuest(environmentId: string): Promise<PlayerClient> {
  const client = createPlayerClient({ baseUrl: window.location.origin, environmentId });

  // restore() yalnızca bakar; oturum yoksa misafir yaratmaz.
  const restored = await client.session.restore();
  const session = restored.status === "authenticated" ? restored : await client.session.signInGuest();

  console.log("oyuncu:", session.playerId, "misafir mi:", session.isGuest, "ad:", session.displayName);
  return client;
}

SDK sizin yerinize misafir sırrını üretip saklar, CSRF belirtecini alır ve çerezleri yönetir. Aynı tarayıcıda sayfayı yenilediğinizde restore() aynı oyuncuyu geri getirir.

Aynısı ham REST ile

Aşağıdaki betik SDK’nın arka planda yaptığını gösterir (HTTPS gerekir; sunucu Secure çerez yazar):

export OPEN_PLAY_ENV="<ortam-kimliği-uuid>"
JAR="$(mktemp)"

# 1) CSRF belirteci al (çerez kavanozuna da yazılır)
TOKEN="$(curl -sS -c "$JAR" "$OPEN_PLAY_URL/v1/auth/csrf" | jq -r .token)"

# 2) 32 baytlık rastgele misafir sırrı: 64 küçük harfli onaltılık karakter. Sakladığınız sürece aynı oyuncuya döner.
BOOTSTRAP="$(openssl rand -hex 32)"

# 3) Misafir girişi
curl -sS -b "$JAR" -c "$JAR" -X POST "$OPEN_PLAY_URL/v1/auth/sign-in/guest" \
  -H "content-type: application/json" \
  -H "x-crx-env: $OPEN_PLAY_ENV" \
  -H "x-csrf-token: $TOKEN" \
  -d "{\"bootstrap_token\":\"$BOOTSTRAP\"}"

Yanıt (200; ilk kez ise is_new_player true):

{
  "player": { "id": "0192…", "display_name": "Guest", "email": null, "email_verified": false, "is_guest": true, "image": null, "created_at": "2026-11-03T10:00:00+00:00" },
  "tokens": { "session_token": "<64 hex>", "refresh_token": "<64 hex>", "access_token": "<jwt>", "expires_in_secs": 900 },
  "is_new_player": true
}

Çerez kavanozunda artık __Secure-crx.session ve __Secure-crx.refresh vardır. Oturumu doğrulayın:

curl -sS -b "$JAR" "$OPEN_PLAY_URL/v1/auth/session" -H "x-crx-env: $OPEN_PLAY_ENV"

Her durum değiştiren istekte CSRF belirteci tek kullanımlıktır: yanıtın x-csrf-token başlığı bir sonrakini taşır. Ayrıntılar: Oturumlar ve CSRF, Misafir girişi.

7. Unity’den ilk oyuncu girişi

Unity paketini kurduktan sonra (Unity SDK) aşağıdaki bileşeni bir GameObject’e ekleyin. baseUrl ve environmentId alanlarını doldurun. WebGL derlemesinde baseUrl sayfayla aynı origin olmalıdır.

using System;
using OpenPlay;
using OpenPlay.Session;
using OpenPlay.Unity;
using UnityEngine;

/// <summary>
/// Misafir girişi: kayıtlı oturum varsa geri yükler, yoksa misafir oturumu açar.
/// Bir GameObject'e ekleyin; baseUrl ve environmentId alanlarını doldurun.
/// </summary>
public sealed class QuickstartGuest : MonoBehaviour
{
    [SerializeField] private string baseUrl = "https://oyun.example.com";   // WebGL'de sayfayla aynı origin olmalı
    [SerializeField] private string environmentId = "";                      // ortam kimliği (UUID)
    [SerializeField] private bool allowInsecureTransport = false;            // yalnız http://localhost için

    private OpenPlayClient _client;

    private async void Start()
    {
        try
        {
            var options = OpenPlayUnity.Options(new Uri(baseUrl), Guid.Parse(environmentId));
            options.AllowInsecureTransport = allowInsecureTransport;
            _client = OpenPlayClient.Create(options);

            var state = await _client.Session.RestoreAsync();   // oturum yoksa misafir YARATMAZ
            if (state.Status != SessionStatus.Authenticated) state = await _client.Session.SignInGuestAsync();

            if (state.Status == SessionStatus.Banned)
            {
                Debug.Log("Hesap askıya alındı."); // terminal durum; yalnız LogoutAsync ile çıkılır
                return;
            }
            Debug.Log("hazır: oyuncu=" + state.PlayerId + " misafir=" + state.IsGuest);
        }
        catch (OpenPlayException ex)
        {
            Debug.LogError("Open Play hatası: " + ex.Kind + " (" + ex.Code + ")");
        }
    }

    private async void OnDestroy()
    {
        if (_client != null) await _client.DisposeAsync();
    }
}

Not

Unity SDK’sı yalnız Unity 6000.6.7f1 ile doğrulanmıştır. Ayrıntı için Unity SDK.

Sırada ne var?

• Kimlik doğrulama: e-posta, Google, hesap bağlama, oturum yönetimi.
• Karakterler, Ekonomi, Mağaza ve IAP: ilk özelliğinizi bağlayın.
• Webhook’lar: olayları sunucunuza imzalı alın.
• Üretim kontrol listesi: canlıya çıkmadan önce.

Mimari ve barındırma

Bu sayfa, oyununuzu Open Play ile nasıl konumlandıracağınızı anlatır: yığının parçaları, tarayıcı oyunlarının Open Play’i doğrudan (CORS) ya da ters vekille nasıl çağıracağı, ortama alan adı bağlama ve çerez/TLS gereksinimleri. Bir tarayıcı ya da WebGL oyunu yayımlayacaksanız bu sayfayı baştan sona okuyun.

Neyin nerede çalıştığı

Referans dağıtım bir Docker Compose yığınıdır:

Oyuncu tarayıcısı ──HTTPS──▶ oyun.example.com ─┬─ /            ▶ oyununuzun statik dosyaları
                                               └─ /open-play/* ▶ Open Play public-gateway ▶ api
Oyun sunucunuz ───────HTTPS──────────────────────────────────▶ Open Play public-gateway ▶ api
Open Play worker ──imzalı webhook──────────────────────────────▶ sizin sunucunuz

Public TLS, bu yığının içinde sonlandırılmaz; Cloudflare, bir yük dengeleyici ya da bir Caddy/nginx girişi gerekir. Panel çerezi Secure olduğundan panel de HTTPS ister. Kurulum, kaynak bütçeleri ve ağ ayrıntıları için üretim dağıtımı rehberine (docs/production-and-adapters.tr.md) bakın.

Not

gRPC arayüzü oyun geliştiricisi için dışa açık bir kanal değildir; varsayılan olarak yalnız loopback’te dinler ve SDK’lar onu kullanmaz.

Tarayıcıdan çağrı: doğrudan CORS ya da ters vekil

Oyununuzun alan adı ortamın alan adı listesindeyse tarayıcı oyununuz Open Play’i doğrudan çağırabilir. Sunucu, kamusal API’de (panel ve kurulum uçları hariç) CORS (cross-origin resource sharing, çapraz kaynak paylaşımı) başlıkları gönderir. İzin kümesi, panelde Oyun ayarları › Ortamlar ve alan adları altında tüm ortamlara yazılmış alan adları ile operatörün genel izinli listesinin (CRX_AUTH_TRUSTED_ORIGINS) birleşimidir; oyuna özel bir ayar yoktur. Örneğin oyun https://oyun.example.com adresinde, Open Play https://open-play.example.com adresinde çalışıyorsa ve oyun.example.com bir ortamın alan adıysa, oyun baseUrl: "https://open-play.example.com/open-play" ile doğrudan konuşur.

Kurallar:

• İzinli origin tam olarak https://<alan adı> biçimindedir (yol yok, varsayılan olmayan port yok). Yanıt Access-Control-Allow-Origin olarak o origin’i aynen yansıtır ve Access-Control-Allow-Credentials: true ekler; * hiçbir zaman kullanılmaz, bilinmeyen origin’e başlık verilmez.
• Önkontrol (preflight, OPTIONS) izinli origin için 204, izinsiz için 403 döner; Access-Control-Max-Age 600 sn’dir.
• Üretim dışı ortamlarda (CRX_ENV development ya da test) listede localhost ya da 127.0.0.1 varsa http://localhost:<port> ve http://127.0.0.1:<port> de izinlidir.
• Panelde yeni eklenen alan adı en geç birkaç saniyede (sunucu anlık görüntüsü 5 sn’de bir yenilenir) geçerli olur.
• CORS yetki değildir. Origin/CSRF/ortam denetimleri aynen çalışır; CORS yalnız tarayıcının yanıtı okumasına izin verir. Panel yolu (/v1/panel/*) hiçbir koşulda CORS başlığı almaz. Gerçek zamanlı WebSocket el sıkışması değişmedi: Origin ortam başına denetlenir.

Uyarı

Oturum çerezi aynı site ister. Çerezler __Secure-, HttpOnly, SameSite=Lax ile yazılır. Oyun, Open Play’den farklı bir kayıtlı alan adındaysa (ör. oyun.example.com ve open-play.baska.dev) tarayıcı çapraz-site fetch isteklerine oturum çerezini eklemez; CORS başlıkları doğru olsa da oturum kurulamaz. Aynı kayıtlı alan adının alt alanları (ör. oyun.example.com ve open-play.example.com) aynı sitedir ve çalışır. Farklı sitede bu desteklenmez; bu durumda aşağıdaki ters vekili kullanın.

Ters vekil hâlâ bir seçenektir. Oyunu ve API’yi aynı origin’den sunmak istiyorsanız (ya da oyun farklı bir sitedeyse), oyunun kendi ağ geçidinde API yolunu Open Play’e yönlendiren bir ters vekil (reverse proxy) kurarsınız; bu durumda CORS devreye girmez. Örnek (Caddy):

oyun.example.com {
  # /open-play/ önekini sıyırıp Open Play public-gateway'e iletir.
  handle_path /open-play/* {
    reverse_proxy open-play-gateway:8080
  }
  # Geri kalan her şey oyununuzun statik dosyaları.
  handle {
    root * /srv/oyun
    try_files {path} /index.html
    file_server
  }
}

Ters vekil kurulumunda istemci tarafı ayarı şudur:

Ters vekilde dikkat edin:

• WebSocket yükseltmesi (Upgrade/Connection) geçmelidir; gerçek zamanlı bağlantı /v1/realtime/ws üzerindedir. Caddy reverse_proxy bunu kendiliğinden yapar; nginx’te proxy_http_version 1.1 ve Upgrade başlıklarını açıkça verin.
• Origin ve Cookie başlıkları olduğu gibi iletilmelidir.
• İstemci IP’si: X-Forwarded-For başlığını doğru yazın. Önde fazladan bir vekil varsa ve sunucuya güvenilen vekil adresleri tanıtılmadıysa bütün oyuncular tek IP kovasına düşer; belirtisi, farklı oyuncuların aynı anda 429 almasıdır. Bunu operatör ekibinizle çözün (bkz. Oran sınırları).
• Panel yolunu açmayın. /v1/panel/* yolu public-gateway’de 404’tür; oyun alan adınız üzerinden panele yol vermeyin.

Çerez davranışı

Secure çerezler HTTPS ister. Yerel geliştirmede SDK’lar yalnız loopback adreslerinde (localhost, 127.0.0.1, ::1) düz http’ye izin verir; tarayıcınızın localhost için Secure çerezleri kabul edip etmediğini denetleyin, kabul etmiyorsa yerelde de HTTPS kullanın.

Alan adları ve güvenilir origin

Tarayıcı, durum değiştiren (POST, PUT, PATCH, DELETE) isteklere Origin başlığı ekler. Sunucu bu origin’in ilgili ortama bağlı bir alan adı olup olmadığını denetler:

• Ortama bağlı alan adı: panelde Oyun ayarları › Ortamlar ve alan adları › Alan adları alanına yazdığınız adlardır. Her satır tam bir alan adıdır (örneğin oyun.example.com); joker karakter, IP ve port yoktur; ortam başına en çok 10 alan adı bağlanabilir. Aynı alan adı iki ortama bağlanamaz (409).
• Genel izinli liste: operatörün sunucu ayarıdır (CRX_AUTH_TRUSTED_ORIGINS: tam alan adı ya da *.alan). Ortamın kendi alan adı yoksa bu liste geçerlidir.
• Bir alan adı başka bir ortama bağlıysa o alan adından gelen tarayıcı, bu ortama yazamaz ve bu ortamı okuyamaz (403).
• Origin göndermeyen istemciler (oyun sunucunuz, curl gibi tarayıcı dışı istemciler) origin denetimine takılmaz; onları çerez kullanıyorlarsa CSRF çift gönderim koruması denetler.
• Sec-Fetch-Site: cross-site ile Sec-Fetch-Mode: navigate birlikte geliyorsa durum değiştiren istek reddedilir.

Gerçek zamanlı bilet de aynı origin kuralına bağlıdır: bilet tek kullanımlıktır ve alındığı origin’e bağlıdır.

Not

Unity yerel derlemeleri, bilet ve WebSocket isteklerinde yapılandırmadan türetilen sabit bir Origin gönderir (BaseUrl’in şeması, alan adı ve varsayılan olmayan portu; NativeOrigin ile değiştirilebilir). Bu origin’in ortamın alan adlarında ya da genel izinli listede bulunması gerekir. Bkz. Unity SDK.

Alan adı bağlama adımları: Ortamlar ve alan adları.

Oyun sunucunuzdan çağrı

Oyun sunucunuz sunucu anahtarıyla Open Play’e doğrudan (HTTPS) bağlanır. Ters vekil, CORS ya da alan adı bağlaması gerekmez (CORS yalnız tarayıcıyı ilgilendirir); ortam anahtardan çıkar. Anahtarı yalnız sunucu ortamında (ortam değişkeni ya da gizli yönetimi) tutun.

Oyuncunun kimliğini sunucunuzda doğrulamak için erişim JWT’sini çevrimdışı doğrulayabilirsiniz: Sunucuda doğrulama.

Webhook’lar (Open Play → sizin sunucunuz)

Worker, olayları imzalı HTTPS isteği olarak sizin adresinize gönderir. Adresiniz genel erişilebilir olmalı ve imzayı doğrulamalıdır. Bkz. Webhook’lar ve Güvenlik.

Yayın öncesi kontrol

Üretim kontrol listesi alan adı bağlama, anahtar yönetimi, TLS ve izleme maddelerini toplar.

Yapay zekâ araçlarıyla kullanım (MCP)

Open Play’in MCP (Model Context Protocol) sunucusu, yapay zekâ yardımcınızın (“misafir girişi nasıl yapılır”, “oyuncu verisi nasıl kaydedilir”, “eklenti nasıl çağrılır” gibi sorulara) tahmin yürütmek yerine bu sitedeki resmî belgelerden ve SDK API’sinden cevap vermesini sağlar. Sunucu yalnızca okur: Open Play sunucunuza, anahtarlarınıza dokunmaz; belgeler ve SDK dizini yalnızca herkese açık belge sitesinden okunur.

Kurulum

Barındırılan sunucu (önerilen)

Hiçbir şey kurmadan https://open-play.b4klabs.dev/mcp adresine bağlanın (Streamable HTTP, yalnız okur, kimlik doğrulama yok):

claude mcp add --transport http open-play https://open-play.b4klabs.dev/mcp

Cursor için .cursor/mcp.json, VS Code için .vscode/mcp.json (mcpServers yerine servers anahtarıyla) dosyasına şunu ekleyin:

{
  "mcpServers": {
    "open-play": {
      "url": "https://open-play.b4klabs.dev/mcp"
    }
  }
}

Sunucu belge ve SDK dizinini https://open-play.b4klabs.dev/docs/mcp/index.json adresinden alır; dizin belge sitesiyle birlikte yenilenir, yani yeni bir belge yayımlandığında sunucuyu güncellemeniz gerekmez.

Yerel paket

Ağ yerine yerel süreç istiyorsanız paket @ferdiunal/open-play-mcp GitHub Packages üzerinden yayımlanır (kaynak: ferdiunal/open-play-mcp). Kullanıcı .npmrc dosyanıza @ferdiunal:registry=https://npm.pkg.github.com satırını ve read:packages izinli bir GitHub belirtecini ekleyin (belirteci belgeye ya da depoya yazmayın), sonra:

claude mcp add open-play -- npx -y @ferdiunal/open-play-mcp

Cursor ve VS Code için "command": "npx" ve "args": ["-y", "@ferdiunal/open-play-mcp"] kullanın. Yerel paket de aynı dizini canlı adresten alır; ağ yoksa son önbelleği, o da yoksa pakete gömülü anlık görüntüyü kullanır.

Araçlar

Araç adları ve açıklamaları İngilizcedir; belge içeriğini Türkçe istemek için lang: "tr" verin (varsayılan en).

Her belge sayfası ayrıca open-play-docs://<dil>/<sayfa> adresli bir kaynaktır (ör. open-play-docs://en/auth/guest) ve integrate_open_play adlı bir istem (platform: web, unity ya da server) entegrasyon adımlarını ve doğru sayfa bağlantılarını verir.

Sınır: Unity API dizini C# kaynağından hafif bir ayrıştırıcıyla çıkarılır; kalıtım ve genel tür parametreleri gibi ayrıntılar eksik olabilir. Kesin başvuru için Unity SDK sayfasındaki üretilmiş başvuruya bakın. SDK özetleri şimdilik Türkçedir, çünkü kaynak koddaki Türkçe yorumlardan gelir.

llms.txt ve llms-full.txt

MCP kullanamayan araçlar (ya da bir sohbete belge yapıştırmak istediğinizde) için belgeler llmstxt.org biçiminde düz metin olarak da yayımlanır:

İngilizce dosyalar https://open-play.b4klabs.dev/docs/llms.txt ve https://open-play.b4klabs.dev/docs/llms-full.txt adreslerinde de durur. Her sayfanın markdown kopyası, HTML adresinin .html yerine .md ile bittiği adrestedir (ör. https://open-play.b4klabs.dev/docs/en/auth/guest.md). Dosyalar belge sitesiyle birlikte yenilenir.

Örnek sorular

• “Bir oyuncuyu misafir olarak nasıl girdiririm?” → search_docs + read_doc (auth/guest).
• “Oyuncu verisini nasıl kaydederim?” → guides/player-data.
• “Bir eklentiyi nasıl çağırırım?” → plugins/calling-plugins.
• “Unity’de PlayerSession hangi yöntemlere sahip?” → get_sdk_symbol.

İlk bakış için Hızlı başlangıç sayfasından başlayın. Ajanınızın oyununuzda Open Play’i doğru kullanması için deponuza koyacağınız hazır kural dosyası: Oyununuz için AGENTS.md.

Oyununuz için AGENTS.md

AGENTS.md, yapay zekâ kodlama ajanlarının (Claude Code, Cursor, Codex ve benzerleri) deponuzun kökünde otomatik okuduğu kural dosyasıdır. Open Play’i oyununuza bağlarken ajanların en sık yaptığı hatalar şunlardır: bir endpoint’i ya da header’ı tahmin etmek, sunucu anahtarını istemciye koymak, CSRF ve oturum kurallarını atlamak, eklenti şemasını sabitlememek, domain’i erken silmek ve eski önbellekteki JavaScript’i canlıda bırakmak. Bu sayfadaki şablon bu hataları önleyen kuralları tek dosyada toplar. Kurallar gerçek oyun entegrasyonlarında (ArenaRace ve LanternTide örnek oyunları) yaşanan sorunlardan çıkarılmıştır ve her kural ilgili belge sayfasına bağlanır.

Nasıl kullanılır

1. Şablonu indirin: https://open-play.b4klabs.dev/docs/AGENTS.md (ya da aşağıdaki bloğu kopyalayın) ve oyun deponuzun köküne AGENTS.md olarak koyun. Zaten bir AGENTS.md dosyanız varsa şablonu “Open Play entegrasyonu” başlığı altına ekleyin.
2. “Project facts” bölümündeki <YOUR_DEV_ENV_ID>, <YOUR_PROD_ENV_ID>, <OPEN_PLAY_BASE_URL>, <DEV_GAME_ORIGIN>, <PROD_GAME_ORIGIN> ve <SDK_VERSION> yer tutucularını kendi değerlerinizle değiştirin. Ortam kimlikleri gizli değildir; anahtarları ve sırları dosyaya yazmayın.
3. Ajanınıza Open Play MCP sunucusunu ekleyin (Yapay zekâ araçlarıyla kullanım): claude mcp add --transport http open-play https://open-play.b4klabs.dev/mcp. Şablon ajana önce search_docs, read_doc, search_sdk ve get_sdk_symbol araçlarını kullanmasını söyler; böylece ajan davranışı hafızasından değil güncel belgeden alır.
4. Oyununuzda kullanmadığınız bölümleri silin (örneğin eklenti kullanmıyorsanız 6. bölüm). Kendi kurallarınızı (kod stili, test komutları, dal düzeni) şablonun üstüne ya da altına ekleyin.

Şablonun kapsamı

Şablonun dili İngilizcedir: yapay zekâ araçları ve belge sitesinin MCP dizini İngilizce metinle en iyi çalışır. Şablon ayrıca https://open-play.b4klabs.dev/docs/llms.txt dizininde “Optional” bölümünde listelenir.

Not

Şablon bir kural dosyasıdır, Open Play’in garantisi değildir. Davranışın tek kaynağı belge sayfalarıdır; şablon ile bir sayfa ayrışırsa sayfa doğrudur. Şablonu gerçek bir ajan oturumunda deneyip kendi oyununuza göre sıkılaştırmanızı öneririz.

Şablonun tamamı

# AGENTS.md — integrating this game with Open Play

> Drop this file in the root of your game repository. Replace every `<PLACEHOLDER>` and delete rules that do not apply.
> Source and updates: https://open-play.b4klabs.dev/docs/AGENTS.md

This game uses **Open Play**, a game backend platform: player identity and sessions, player data (cloud save), characters, economy, store, rewards, social features, leaderboards, notifications, plugins and realtime connections. The game talks to Open Play over HTTP and WebSocket, through the TypeScript SDK (`@ferdiunal/open-play-ts`) or the Unity SDK. The game does **not** run its own account or save server for anything Open Play provides.

Docs root: https://open-play.b4klabs.dev/docs/en/ — every rule below links to its page.

## 0. Project facts (fill in)

- Environment ids (the `x-crx-env` value): dev `<YOUR_DEV_ENV_ID>`, prod `<YOUR_PROD_ENV_ID>`. One environment per stage; data is never shared between them.
- Open Play base URL: `<OPEN_PLAY_BASE_URL>` (the API address the browser calls).
- Game origins registered per environment: `<DEV_GAME_ORIGIN>`, `<PROD_GAME_ORIGIN>`.
- SDK version (exact, no `^`, no `latest`): `<SDK_VERSION>`.

## 1. Use the Open Play MCP server first

Before you write any call to Open Play, **look it up**. Never guess an endpoint, header, field or error code.

```bash
claude mcp add --transport http open-play https://open-play.b4klabs.dev/mcp
```

Cursor (`.cursor/mcp.json`) and VS Code (`.vscode/mcp.json`, key `servers`): `{"mcpServers":{"open-play":{"url":"https://open-play.b4klabs.dev/mcp"}}}`.

- `search_docs` then `read_doc` (for example `auth/oauth`) for behavior and HTTP contracts.
- `search_sdk` then `get_sdk_symbol` (for example `PlayerSession`, `sdk: "typescript"` or `"unity"`) for exact SDK signatures.
- The server is read-only and public; it never needs or sees a key. If the docs and your memory disagree, the docs win.
- No MCP available: read https://open-play.b4klabs.dev/docs/llms.txt (index) or `llms-full.txt` (everything).

Docs: [Using AI tools (MCP)](https://open-play.b4klabs.dev/docs/en/getting-started/ai-tools.html).

## 2. Keys and environments

- **Client** code (browser, WebGL, mobile) knows only the environment id and the player session. It carries **no secret**.
- A **server key** (`crx_live_<prefix>_<secret>`) lives only on your own server or backend-for-frontend (BFF): in its secret store, never in the client bundle, the repository, logs, or `.env` files that are committed. Use a separate key per environment and service, with an expiry.
- A client key is not a server key; calling a server endpoint with it is rejected. Player operations use the player session, not a key.
- Never point a dev build at the prod environment or the reverse. Read the environment id from per-stage configuration.
- Do not hard-code or print secrets, tokens, cookies or `x-csrf-token` values in code, tests, logs or analytics.

Docs: [Security](https://open-play.b4klabs.dev/docs/en/operations/security.html), [API keys](https://open-play.b4klabs.dev/docs/en/panel/game-settings-api-keys.html), [Production checklist](https://open-play.b4klabs.dev/docs/en/operations/production-checklist.html).

## 3. Sign-in and sessions

- **Guest first.** Open a guest session on first launch so the player plays at once; offer Google (or email) later and **link** it to the same player. Linking a guest upgrades the same player id; progress is kept.
- **Google OAuth:** try a popup window and fall back to a full-page redirect when the popup is blocked. Open the popup synchronously inside the click handler, before any `await`. Let the callback page hand the result back (for example through `BroadcastChannel`) and close itself.
- The server builds the Google `redirect_uri` from the configured **redirect base + `/google`**. The base must end at `/auth/callback` (not `/google`); the redirect URI registered with Google must be exactly `<base>/google`, and that path must be a page of your game that finishes the sign-in.
- The OAuth `code` and `state` are single-use: finish exactly once, then remove them from the address bar (`history.replaceState`). Use the SDK helpers; they bind `state` to the browser tab.
- A cookie session sends `x-crx-env` on every call and a CSRF token on every state-changing request. The token is **single-use and rotates**: never send two mutations at once with the same token, and keep the new token from each response. The SDKs serialize this for you; share the token between tabs with the SDK `csrf.channel` option. Retry a CSRF `403` once with a fresh token.
- Session lifetime is 30 days sliding, 180 days absolute. On `401` refresh or sign in again; do not loop.
- If the environment allows a **single active session**, a newer sign-in revokes the older one. Handle `reauthRequired` with a clear "signed in on another device" screen and a sign-in button, not a silent retry.
- Show the sign-in methods you actually enabled; hide the rest. Do not use SDK methods the docs mark as unsupported.
- **Account deletion** is a store requirement (Apple, Google Play): provide an in-game "Delete my account" action (`POST /v1/auth/account/delete`, `confirm: "delete_my_account"`). A linked account must have signed in within the last 10 minutes (`recent_sign_in_required`): ask the player to sign in again, then repeat.
- Verify identity on your own game server with the access JWT and the JWKS, never by trusting a client-sent player id.

Docs: [Auth overview](https://open-play.b4klabs.dev/docs/en/auth/overview.html), [Guest](https://open-play.b4klabs.dev/docs/en/auth/guest.html), [Google sign-in](https://open-play.b4klabs.dev/docs/en/auth/oauth.html), [Sessions and CSRF](https://open-play.b4klabs.dev/docs/en/auth/sessions-and-csrf.html), [Account linking](https://open-play.b4klabs.dev/docs/en/auth/account-linking.html), [Account deletion](https://open-play.b4klabs.dev/docs/en/auth/account-deletion.html), [Server-side verification](https://open-play.b4klabs.dev/docs/en/auth/server-verification.html).

## 4. Domains and calling from the browser

- Register **every origin your game runs on** in each environment's domain list (Game settings, Environments and domains): one full domain per line, no wildcards, no ports, at most 10, and a domain belongs to one environment only. An unregistered origin gets `403` on writes.
- Call Open Play either directly (your game domain is in the list; the server sends CORS headers with credentials) or through a same-origin reverse proxy that forwards `Cookie`, `Origin`, `x-crx-env`, `x-csrf-token`, `Idempotency-Key`, `If-Match` and the WebSocket upgrade, and that forwards the real client IP.
- **Moving to a new domain:** add the new domain and the new OAuth redirect first, test it, and only then retire the old one. **Removing a domain from an environment locks that live host out immediately.** Guest identities are per-origin: a new domain starts new guests.
- Send `Origin` only as the browser sets it. Never fake it in game code.

Docs: [Architecture and hosting](https://open-play.b4klabs.dev/docs/en/getting-started/architecture-and-hosting.html), [Environments and domains](https://open-play.b4klabs.dev/docs/en/panel/game-settings-environments.html).

## 5. Player data (cloud save)

- Use the generic per-player key-value store; **do not build a game-specific save server**. The value is an opaque JSON object the server never interprets; your game owns the format and its version field.
- Limits: key `^[a-z0-9][a-z0-9._-]{0,63}$`, at most 16 keys per player, 64 KiB per value, 60 writes per minute per player. Store large integers as strings.
- **There is no blind write.** Every `PUT` sends exactly one of `If-None-Match: *` (create) or `If-Match: "<version>"` (update). On `409 version_conflict` read the remote record, merge it with your own rule, retry. `428` means a precondition header is missing.
- Batch saves (on level end, on pause, on a timer), not every frame. Keep a local copy and reconcile on sign-in; a guest-to-Google link keeps the same player.
- Never write personal data you do not need. Player data is erased with the account.

Docs: [Player data](https://open-play.b4klabs.dev/docs/en/guides/player-data.html), [Idempotency and concurrency](https://open-play.b4klabs.dev/docs/en/reference/idempotency-and-concurrency.html).

## 6. Plugins (game-specific server logic)

- Call plugins only through **generated bindings**, never hand-written DTOs or copied field names. Get the schema document from `GET /v1/plugins/<PLUGIN_ID>/schema` and generate bindings from it.
- **Pin** `pluginId`, `schemaSha256`, `protocolVersion`, `codecProfile` and the plugin version in your release manifest. A mismatch must **fail closed**: show an "update the game" screen, never talk to the server with the wrong fields. After every server update compare the live digest with the pin (at startup or in CI).
- Every command carries an `Idempotency-Key`, generated **once** per logical action and reused on retries. If the outcome is uncertain (timeout, drop), resend with the **same key and body** or ask the result query; never generate a new key for the same action.
- Retry only when it is safe: idempotent calls on network errors, `429`, `503`, with exponential backoff and jitter, and honor `Retry-After`. Never retry business rejections (`422`).
- `int64` values travel as decimal strings. Send `If-Match` / `expectedVersion` when writing a shared resource; on `409` re-read first.
- If a plugin call suddenly returns `403`, check that the plugin is **enabled for that environment** and that the enabled version matches the server version. A server version bump needs its grant switched too.

Docs: [Plugins overview](https://open-play.b4klabs.dev/docs/en/plugins/overview.html), [Bindings and pinning](https://open-play.b4klabs.dev/docs/en/plugins/bindings.html), [Calling plugins](https://open-play.b4klabs.dev/docs/en/plugins/calling-plugins.html).

## 7. Realtime

- Use the SDK realtime client; if you implement the protocol yourself follow it exactly (single-use ticket, `Origin`, subprotocol).
- Ask for a **new ticket on every connection**. On a drop reconnect with exponential backoff, `Join` again with the last cursor (durable streams) or without one (ephemeral state), and on `ResyncRequired` drop the cursor and join fresh.
- Unacknowledged inputs are **not replayed**; continue from the latest snapshot. Pipeline inputs inside the SDK window (default 4 in flight); one input per round trip makes fast games feel laggy on real networks.
- Keep the frame rate below 40 per second; at most 4 sockets per player. Handle idle close (`4100`) with a "Continue" screen. An open socket does not keep the session alive.
- Notification and chat sockets cannot be opened straight from a browser; use inbox polling or REST.

Docs: [Realtime overview](https://open-play.b4klabs.dev/docs/en/realtime/overview.html), [Protocol](https://open-play.b4klabs.dev/docs/en/realtime/protocol.html), [Reconnect and limits](https://open-play.b4klabs.dev/docs/en/realtime/reconnect-and-limits.html).

## 8. Caching and deploys

- Serve your game's JavaScript modules and config (including the file that holds the environment id) with `Cache-Control: no-cache`, or content-hash the filenames. A stale config file after a deploy silently runs the old integration.
- If a CDN sits in front, set it to **respect existing headers** for HTML, JS and CSS. A CDN default browser TTL can override your `no-cache` and keep old code for hours.
- Never put a CDN cache in front of API responses that carry a cookie or `Authorization`.
- Deploy order when Open Play changes a plugin: new server and grant, then client with regenerated bindings. Pin the SDK version exactly and upgrade from the changelog.

Docs: [Production checklist](https://open-play.b4klabs.dev/docs/en/operations/production-checklist.html), [Versioning](https://open-play.b4klabs.dev/docs/en/reference/versioning.html).

## 9. Errors and rate limits

- Core endpoints return **plain-text** errors; plugin endpoints return a JSON envelope (`code`, `message`, `retryable`, `requestId`). Decide by status code and JSON `code`, **never by parsing message text**. Log `requestId` / `x-request-id`.
- There is no general per-key quota, but identity endpoints are limited per client IP (for example 30 guest sign-ins per minute). Behind a proxy or a shared network (NAT, a hosting platform's shared egress) many players share one IP: forward the real client IP.
- Back off on `429`, `503` and network errors; wait `Retry-After` when present. Never loop on `401`, `403` or `422`.

Docs: [Errors](https://open-play.b4klabs.dev/docs/en/reference/errors.html), [Rate limits](https://open-play.b4klabs.dev/docs/en/reference/rate-limits.html).

## 10. Testing checklist (before you call it done)

1. Fresh browser profile: guest sign-in, play, reload, same player and progress.
2. Guest upgraded to Google keeps progress; a second browser signs in to the same account and loads the save.
3. Two tabs open: no CSRF `403` storm; sign-out in one tab is handled in the other.
4. Same command sent twice with the same `Idempotency-Key` gives one effect.
5. Two devices write the same player-data key: the `409` is merged, nothing is lost.
6. Kill the network mid-command and mid-socket: the game recovers without duplicate effects.
7. Prod build points at the prod environment id and prod origin; dev at dev. No secrets in the bundle (search it).
8. Run these in a **headless browser or test harness** you control; do not test against another team's environment or real player data.

## Do

- Look up docs through MCP first; link the page you used in the PR description.
- Keep Open Play calls in one module/service layer, one writer per feature (never write the same state both locally and through Open Play).
- Handle every SDK session state, including `reauthRequired`, `banned` and `logoutUncertain`.
- Add a test with each integration change; report failing checks, never skip them.

## Don't

- Do not guess endpoints, headers, field names or error codes.
- Do not put a server key, token or cookie in client code, tests, logs or commits.
- Do not use `latest` or git/vendored copies of the SDK; do not hand-copy DTOs.
- Do not bypass CSRF, `Origin` or idempotency checks "just for testing".
- Do not remove a domain, redirect URI or environment that a live host still uses.
- Do not store save data in browser storage alone once the player can sign in.
- Do not write retry loops without backoff, or retry non-idempotent calls with new keys.
- Do not run production deploys or destructive operations unless the user explicitly asks.

Sonraki adım: Hızlı başlangıç ve Üretim kontrol listesi.

Kimlik doğrulamaya genel bakış

Bu sayfa oyuncunun Open Play’e nasıl giriş yaptığını özetler: hangi yöntemler var, hepsinin paylaştığı kurallar neler ve ayrıntı için hangi sayfaya gidilir. Oyuncu girişini bağlıyorsanız önce buradan başlayın.

Giriş yöntemleri

Hangi yöntemlerin oyuncuya sunulacağı oyunun tercihidir; Google’ın çalışması için ortamda yapılandırılmış olması gerekir (Oyun ayarları › Giriş yöntemleri).

Giriş sonrası konular: Oturumlar ve CSRF, Hesap bağlama, Sunucuda doğrulama.

Hangi yöntemi seçmeliyim?

• Hesap zorunlu değilse misafirle başlayın; oyuncu ilerledikçe misafir terfisi ile e-postaya ya da Google’a bağlayın. Oyuncu kimliği (playerId) değişmez.
• Çoklu cihaz istiyorsanız e-posta/parola ya da Google gerekir; misafir kimliği cihazın sakladığı sırra bağlıdır.
• Mobil yerel giriş (Apple, Game Center, Play Games) için HTTP uçları vardır, ancak SDK’larda yardımcı yoktur.

Her çağrıda geçerli kurallar

Aşağıdaki kurallar /v1/auth/* altındaki tüm uçlar için geçerlidir.

1. Ortam başlığı. Her istek x-crx-env: <ortam-kimliği> taşır. Yoksa ya da UUID değilse 401.

2. İçerik türü. Gövdeli istekler Content-Type: application/json ile gönderilir.

3. CSRF. GET dışındaki her istek, çift gönderim (double-submit) CSRF koruması ister: __Secure-crx.csrf çerezi ve eşleşen x-csrf-token başlığı. Her başarılı kullanımda belirteç döner ve değişir. Önce GET /v1/auth/csrf ile bir belirteç alırsınız. Ayrıntı: Oturumlar ve CSRF.

4. Origin denetimi. Tarayıcıdan gelen durum değiştiren isteklerin Origin alan adı ortama bağlı olmalıdır. Bkz. Mimari ve barındırma.

5. Alan adları snake_case. İstek ve yanıt gövdeleri snake_case kullanır (display_name, bootstrap_token, old_password). İki istisna: GET /v1/auth/session yanıtında displayName ve POST /v1/auth/session/display-name gövdesi/yanıtı (displayName). SDK’lar bu farkı sizden saklar ve camelCase sunar.

6. Hata gövdeleri. Hatalar çoğunlukla düz metindir (permission denied, rate limited…). JSON gövdeli tek anlamlı hata, banlı hesap için 403 {"code":"account_banned","message":"account banned"} yanıtıdır. Durum kodları: 400 geçersiz girdi, 401 ortam ya da oturum yok/geçersiz, 403 reddedildi (yanlış parola, CSRF, süresi dolmuş token — ayrım bilerek sızdırılmaz), 409 çakışma, 422 işlenemez, 429 oran sınırı. Ayrıntı: Hatalar.

Başarılı giriş yanıtı

Giriş, kayıt, yenileme ve OAuth callback uçları aynı zarfı döndürür ve iki çerez yazar (__Secure-crx.session, __Secure-crx.refresh; HttpOnly; Secure; SameSite=Lax; Path=/, Max-Age=15552000 = 180 gün üst sınır):

{
  "player": {
    "id": "0192…",
    "display_name": "Guest",
    "email": null,
    "email_verified": false,
    "is_guest": true,
    "image": null,
    "created_at": "2026-11-03T10:00:00+00:00"
  },
  "tokens": {
    "session_token": "<64 hex>",
    "refresh_token": "<64 hex>",
    "access_token": "<jwt>",
    "expires_in_secs": 900
  },
  "is_new_player": true
}

Uyarı

Tarayıcı oyunlarında oturum ve yenileme belirteçlerini JavaScript’te saklamayın; çerezler HttpOnly’dir ve bunun için vardır. SDK’lar belirteç gövdelerini durumuna, günlüğe ve hatalara koymaz.

Oran sınırları

Kimlik uçları, sabit pencereli oran sınırlarına tabidir. Aşımda 429 ve düz metin rate limited döner; Retry-After başlığı yoktur: pencere süresini kendiniz beklemelisiniz. Başarısız denemeyi hemen yeniden göndermeyin.

Sunucu önünde fazladan bir vekil varsa ve güvenilen vekil adresleri tanıtılmamışsa bütün oyuncular tek IP kovasına düşer. Bkz. Mimari ve barındırma.

Uç nokta özeti

/v1/auth/organization/* uçları (oyuncu organizasyonları) kullanımdan kalkmaktadır: çalışır, ancak her yanıtı Deprecation başlığı taşır ve bu belgede anlatılmaz. /v1/auth/admin/* uçları sunucu anahtarıyla oyuncu yönetimi içindir (liste, ban, yeniden adlandırma, oturum iptali) ve uç nokta başvurusunda listelenir.

Banlı hesaplar

Operatör bir oyuncuyu banladığında oyuncunun tüm oturumları iptal edilir ve açık gerçek zamanlı bağlantısı kapanır. Oyuncu girişte nasıl görünür:

• Parolası doğru banlı e-posta hesabı: 403 ve {"code":"account_banned","message":"account banned"}. Yanlış parola ya da bilinmeyen adres ayrımsız 403 düz metindir; ban durumu sızmaz.
• Banlı misafir: aynı bootstrap sırrıyla ya da banlı oyuncunun eski oturumunu sunarak misafir girişi yapılırsa yine 403 account_banned döner ve yeni oyuncu açılmaz.
• GET /v1/auth/session banlı hesapta 401 döndürür (ban kodu sızmaz); refresh, OAuth callback ve misafir terfisi banlı sahibe ayrımsız reddedilir.
• Yanıtta ban gerekçesi ya da bitişi yoktur.
• SDK davranışı: TypeScript’te oturum durumu banned olur; Unity’de SessionStatus.Banned. İkisi de yeni misafir açmaz ve kayıtlı misafir sırrını silmez (banlı oyuncu yeni misafir açarak kaçamasın). Oyuncuya hesabın askıya alındığını gösterin; yeniden deneme döngüsü kurmayın.

Misafir girişi

Misafir girişi, oyuncuya e-posta ya da parola sormadan kalıcı bir oyuncu kimliği verir. Oyuncu, cihazında saklanan bir sır sayesinde aynı hesaba geri döner; sonra isterse e-posta ya da Google ile kalıcı hesaba geçer. Bu sayfa HTTP ucunu, sırrın yaşam döngüsünü ve SDK davranışını anlatır.

Nasıl çalışır?

1. İstemci 32 baytlık rastgele bir sır üretir ve 64 küçük harfli onaltılık karakter olarak yazar (bootstrap_token). Bu sır, oyuncunun hesabının anahtarıdır.
2. İstemci sırrı POST /v1/auth/sign-in/guest ile gönderir. Sunucu sırrın yalnız SHA-256 özetini saklar; ham sır kaydedilmez, günlüğe yazılmaz.
3. Sır ilk kez geliyorsa yeni bir misafir oyuncu (display_name Guest) ve yeni bir oturum açılır (is_new_player: true). Aynı sır tekrar gelirse aynı oyuncu için yeni bir oturum açılır (is_new_player: false).
4. Sır, kullandıkça kayan 180 günlük bir ömre sahiptir. Süresi dolmuş ya da emekliye ayrılmış (örneğin hesap kalıcıya terfi etmiş) bir sır 403 ile reddedilir.

Uyarı

Misafir sırrı bir yetkidir: sırrı bilen oyuncu hesabına girer. Başka oyunculara, günlüğe ya da analitiğe taşımayın.

İstek

Önce bir CSRF belirteci alın (Oturumlar ve CSRF); sonra:

POST /v1/auth/sign-in/guest
content-type: application/json
x-crx-env: <ortam-kimliği>
x-csrf-token: <csrf-belirteci>
cookie: __Secure-crx.csrf=<csrf-çerezi>

{"bootstrap_token":"<64 küçük harfli onaltılık karakter>"}

Gövde yalnız bootstrap_token alanını taşır.

Yanıt

200 ve ortak giriş zarfı:

{
  "player": { "id": "0192…", "display_name": "Guest", "email": null, "email_verified": false, "is_guest": true, "image": null, "created_at": "2026-11-03T10:00:00+00:00" },
  "tokens": { "session_token": "<64 hex>", "refresh_token": "<64 hex>", "access_token": "<jwt>", "expires_in_secs": 900 },
  "is_new_player": false
}

Ayrıca iki Set-Cookie (__Secure-crx.session, __Secure-crx.refresh) ve yeni CSRF belirteci (x-csrf-token başlığı) döner.

Banlı misafir: istek, banlı bir oyuncuya ait eski bir oturum çerezi/Bearer taşıyorsa ya da sır banlı oyuncuya aitse yeni misafir açılmaz ve 403 account_banned döner; bu yanıt çerezleri silmez. Bkz. Banlı hesaplar.

Görünen ad

Misafirin adı Guest’tir. Oyuncu kendi adını POST /v1/auth/session/display-name ile değiştirebilir (gövde {"displayName":"…"}): ad NFC’ye çevrilir, kırpılır, iç boşluklar teklenir; kontrol/yön/sıfır genişlikli karakterler reddedilir; sonuç 2–24 karakter olmalıdır; oyuncu başına saatte 10 değişiklik. Unity’de Session.RenameAsync; TypeScript SDK’sında bu işlem için yöntem yoktur, ham REST kullanın.

TypeScript SDK

session.signInGuest() sırrı sizin yerinize üretir, istekten önce saklar ve CSRF belirtecini yönetir; böylece yanıt kaybolsa ya da çerez silinse aynı sır aynı misafire döner. session.restore() yalnızca mevcut oturumu geri yükler, misafir yaratmaz.

Sır saklama seçenekleri (createPlayerClient’ın guestBootstrap ayarı):

Davranış kuralları:

• Sır; logout, başarılı e-posta girişi/kaydı, upgradeGuest ve isGuest: false görülen oturumdan sonra silinir. Banlı durumdan yapılan logout sırrı silmez (banlı oyuncu yeni misafir açarak kaçamasın).
• Sunucu sırrı reddederse (uç işleyicisinin 403’ü; CSRF/origin 403’ü ve 401 sayılmaz) SDK sırrı bir kez siler ve yeni sırla tek yeniden deneme yapar.
• banned durumunda yeniden deneme yapılmaz; yeni misafir açılmaz.

Uyarı

Varsayılan localStorage deposu aynı origin’deki her betiğe okunabilir; bir XSS açığı sırrı çalıp misafir hesabını devralabilir. Yüksek değerli hesaplarda guestBootstrap: false kullanın ya da platformun güvenli deposunu verin.

import {
  ACCOUNT_BANNED_CODE,
  CrxError,
  createMemoryGuestBootstrapStore,
  createPlayerClient,
  type PlayerClient,
} from "@ferdiunal/open-play-ts";

/** Varsayılan davranış: misafir kimliği tarayıcıda `localStorage`'da saklanır ve aynı oyuncuya döner. */
export function createDefaultClient(environmentId: string): PlayerClient {
  return createPlayerClient({ baseUrl: window.location.origin, environmentId });
}

/** Kalıcı kimlik istemeyen oyun: her `signInGuest` yeni bir misafir oyuncu açar. */
export function createEphemeralGuestClient(environmentId: string): PlayerClient {
  return createPlayerClient({ baseUrl: window.location.origin, environmentId, guestBootstrap: false });
}

/** Sunucu tarafında çalışan kod için (SSR/Node) isteğe özel bellek deposu; sır sunucu belleğinden çıkmaz. */
export function createRequestScopedClient(baseUrl: string, environmentId: string): PlayerClient {
  return createPlayerClient({ baseUrl, environmentId, guestBootstrap: createMemoryGuestBootstrapStore() });
}

/** Misafir girişi; banlı hesabı ayrı bir ekranla karşılar. */
export async function signInGuestOrShowBan(client: PlayerClient, showBanned: () => void): Promise<void> {
  try {
    await client.session.signInGuest();
  } catch (error) {
    if (error instanceof CrxError && error.code === ACCOUNT_BANNED_CODE) {
      showBanned(); // client.session.state.status === "banned"; yeniden deneme döngüsü kurmayın.
      return;
    }
    throw error;
  }
}

SSR’da (sunucuda çizim) SDK ortam localStorage’ını kullanmaz ve sır belleğe yazılır. Kalıcı misafir kimliği isteyen bir SSR uygulaması, istek başına kendi deposunu guestBootstrap ile vermelidir; yukarıdaki createRequestScopedClient örneği yalnızca süreçlik bellek deposu kullanır.

Unity SDK

Session.SignInGuestAsync() aynı akışı uygular; sır OpenPlayOptions.SecretStore içinde saklanır. Varsayılan PlayerPrefs deposu düz metindir ve güvenli depo değildir; üretimde Keychain/Keystore destekli kendi ISecretStore uygulamanızı verin (Unity SDK). Session.RestoreAsync() misafir yaratmaz. Banlı hesapta durum SessionStatus.Banned olur.

Misafiri kalıcı hesaba çevirme

Oyuncu ilerlemesini kaybetmeden kalıcı hesaba geçebilir; player.id değişmez:

• E-posta ve parola: upgradeGuest
• Google: linkOAuth

Terfiden sonra misafir sırrı emekliye ayrılır; cihazdaki sır artık işe yaramaz.

E-posta ve parola

E-posta ve parola, oyuncuya cihazlar arası kalıcı bir hesap verir. Bu sayfada kayıt, giriş, misafirden kalıcı hesaba terfi, parola değiştirme ve sıfırlama akışlarını, istek ve yanıt örnekleriyle ve SDK çağrılarıyla bulacaksınız. Tüm çağrılar ortak kuralları (ortam başlığı, CSRF) izler.

Kurallar

• E-posta kırpılır ve küçük harfe çevrilir; tam bir @ içermeli ve alan kısmında nokta bulunmalıdır. Aynı ortamda bir adres yalnız bir hesapta olabilir.
• Parola 8–128 karakter (Unicode karakter sayılır, bayt değil). Parola Argon2id ile saklanır.
• Görünen ad zorunludur; 1–100 karakter kullanın (sunucu bu sınırı misafir terfisinde uygular). Oyuncu sonradan adını 2–24 karakter kuralıyla değiştirebilir (Misafir girişi › Görünen ad).
• Bugün e-posta doğrulama ucu yoktur; kayıtta email_verified false döner.
• SDK’lar istek göndermeden önce yalın sınır denetimi yapar (e-posta 3–320, parola en çok 1024, görünen ad en çok 256 birim; kontrol karakteri yok). Asıl politika sunucudadır.

Kayıt

POST /v1/auth/sign-up/email
content-type: application/json
x-crx-env: <ortam-kimliği>
x-csrf-token: <csrf-belirteci>

{"email":"[email protected]","password":"<en az 8 karakter>","display_name":"Ayşe"}

201 ve ortak giriş zarfı (is_new_player: true, player.is_guest: false, player.email dolu) + oturum çerezleri.

Giriş

POST /v1/auth/sign-in/email
content-type: application/json
x-crx-env: <ortam-kimliği>
x-csrf-token: <csrf-belirteci>

{"email":"[email protected]","password":"<parola>"}

200 ve giriş zarfı (is_new_player: false).

• Yanlış parola ile bilinmeyen adres aynı yanıtı alır (403 düz metin); hangisi olduğu sızmaz.
• Parolası doğru ama banlı hesap 403 ve {"code":"account_banned","message":"account banned"} alır; çerez silinmez.
• Aynı adres + IP için 15 dakikada 10 başarısız giriş hesabı kilitler; kilitliyken doğru parola da 429 alır. Başarılı giriş hakkı iade eder. IP başına ayrıca 5 / 60 sn sınırı vardır.
• İstekte başka bir oyuncunun (örneğin aynı tarayıcıdaki eski misafirin) kullanılabilir oturumu varsa, giriş başarılı olduktan sonra o oturum ailesi iptal edilir. Aynı oyuncunun oturumuna dokunulmaz.

Misafir terfisi

Misafir oyuncuyu aynı player.id ile kalıcı hesaba çevirir; ilerleme korunur. Misafir oturumu gerekir (çerez ya da Authorization: Bearer <oturum-belirteci>).

POST /v1/auth/guest/upgrade/email
content-type: application/json
x-crx-env: <ortam-kimliği>
x-csrf-token: <csrf-belirteci>

{"email":"[email protected]","password":"<parola>","display_name":"Ayşe"}

200; aynı player.id, is_guest: false, yalnız yeni oturum çifti. Terfi tek bir veritabanı işlemidir: kimlik eklenir, misafir sırrı emekliye ayrılır, eski oturumlar iptal edilir ve yeni oturum açılır.

Yanıt kaybolursa (bağlantı koptu) eski misafir oturumları iptal edilmiş olabilir; kurtarma yolu normal e-posta girişidir.

Parola değiştirme

Oturum gerekir. Eski parola doğrulanır; başarıda tüm oturumlar (bu dahil) iptal edilir ve çerezler silinir; oyuncu yeniden giriş yapar.

POST /v1/auth/change-password
content-type: application/json
x-crx-env: <ortam-kimliği>
x-csrf-token: <csrf-belirteci>

{"old_password":"<mevcut>","new_password":"<yeni>"}

204. Hatalar: 400 yeni parola politikası ihlali, 403 oturum ya da eski parola reddi, 429 IP 10 / 60 sn ya da hesap 6 / 60 sn. Yanlış mevcut parola, giriş kilidinin sayacına da sayılır.

Parola sıfırlama

1. POST /v1/auth/forgot-password ile sıfırlama e-postası istenir. Hesap olsa da olmasa da yanıt aynı 200’dür (hesap varlığı sızmaz).
2. E-postadaki token ile POST /v1/auth/reset-password çağrılır. Token tek kullanımlıktır ve 1 saat geçerlidir. Başarıda tüm oturumlar iptal edilir.

POST /v1/auth/forgot-password
content-type: application/json
x-crx-env: <ortam-kimliği>
x-csrf-token: <csrf-belirteci>

{"email":"[email protected]"}

POST /v1/auth/reset-password
content-type: application/json
x-crx-env: <ortam-kimliği>
x-csrf-token: <csrf-belirteci>

{"token":"<64 hex>","new_password":"<yeni>"}

reset-password hataları: 400 yeni parola politikası ihlali (token yanmaz, aynı bağlantıyla yeniden denenebilir), 403 token geçersiz/kullanılmış/süresi dolmuş ya da CSRF (ayrım sızmaz), 429 sınır aşımı (5 / 60 sn, forgot ve magic link ile ortak IP kovası).

Uyarı

Bilinen kısıt: Sıfırlama e-postasındaki bağlantı oyununuzun sayfasına değil, sunucunun API kökündeki /v1/auth/reset-password?token=… adresine gider. Bu yolda GET ucu yoktur; yani bağlantıya tıklamak bir sayfa göstermez. Oyununuzda sıfırlamayı sunmak için oyuncunun e-postadaki token değerini kendi sıfırlama ekranınıza taşıması gerekir (örneğin kendi ters vekilinizde bu yolu bir oyun sayfasına yönlendirmek; bu yönlendirme bu repoda doğrulanmadı). E-posta gönderimi operatörün SMTP ayarına bağlıdır.

SDK

import { CrxError, ErrorKind, type PlayerClient } from "@ferdiunal/open-play-ts";

/** Yeni hesap açar ve oturumu başlatır. Adres kayıtlıysa sunucu 409 döner (`ErrorKind.Http`, status 409). */
export async function register(client: PlayerClient, email: string, password: string, displayName: string): Promise<void> {
  await client.session.signUpEmail({ email, password, displayName });
}

/** Mevcut hesapla girer. Yanlış parola ile bilinmeyen adres aynı yanıtı alır; hangisi olduğu sızmaz. */
export async function login(client: PlayerClient, email: string, password: string): Promise<void> {
  await client.session.signInEmail({ email, password });
}

/**
 * Misafir ilerlemesini koruyarak kalıcı hesaba geçer: aynı `playerId`, yeni oturum.
 * Önce misafir olarak girilmiş olmalıdır; adres başka bir hesapta kayıtlıysa 409 döner ve misafir oturumu bozulmaz.
 */
export async function upgradeGuestToEmail(client: PlayerClient, email: string, password: string, displayName: string): Promise<void> {
  if (client.session.state.status !== "authenticated") await client.session.signInGuest();
  try {
    await client.session.upgradeGuest({ email, password, displayName });
  } catch (error) {
    if (error instanceof CrxError && error.kind === ErrorKind.Http && error.status === 409) {
      throw new Error("Bu e-posta adresi başka bir hesapta kayıtlı.");
    }
    throw error;
  }
}

/** Parola sıfırlama isteği: hesap olsa da olmasa da yanıt aynıdır. */
export async function requestReset(client: PlayerClient, email: string): Promise<void> {
  await client.session.requestPasswordReset({ email });
}

/** E-postadaki token ile yeni parola belirler; başarıda tüm oturumlar kapanır, oyuncu yeniden giriş yapar. */
export async function finishReset(client: PlayerClient, token: string, newPassword: string): Promise<void> {
  await client.session.resetPassword({ token, newPassword });
}

/** Oturum açıkken parola değiştirir; başarıda tüm oturumlar (bu dahil) kapanır. */
export async function changePassword(client: PlayerClient, currentPassword: string, newPassword: string): Promise<void> {
  await client.session.changePassword({ currentPassword, newPassword });
}

SDK’ların ortak davranışı:

• Parola ve token yalnız istek gövdesine yazılır; oturum durumuna, olay dinleyicilerine, hata nesnelerine ve günlüğe girmez.
• Kimlik uçlarında 403 yalnızca CSRF katmanı reddettiyse (yanıtta yeni bir x-csrf-token yoksa) SDK bir kez taze belirteçle yeniden dener.
• İstek gönderildikten sonra bağlantı kaybolursa giriş uçları en çok bir oturum yoklaması yapar; sonuç belirsizse UnknownOutcome hatası alırsınız. Parola değiştirme ve sıfırlama gibi sonuç döndürmeyen çağrılarda da kör yeniden deneme yapılmaz.
• upgradeGuest oturum yokken ağ isteği göndermez; sunucunun kesin ret yanıtları (4xx) misafir oturumunu düşürmez.
• changePassword başarıda logout ile aynı geçişi uygular (durum signedOut).

Unity örneği:

using System.Threading.Tasks;
using OpenPlay;
using OpenPlay.Session;
using OpenPlay.Support;

/// <summary>E-posta ve parola akışları. Parola SecretText ile taşınır; günlüğe ve ToString()'e girmez.</summary>
public static class EmailAuth
{
    public static Task<SessionState> Register(OpenPlayClient client, string email, string password, string displayName) =>
        client.Session.SignUpEmailAsync(new SignUpEmailInput { Email = email, Password = new SecretText(password), DisplayName = displayName });

    public static Task<SessionState> Login(OpenPlayClient client, string email, string password) =>
        client.Session.SignInEmailAsync(new SignInEmailInput { Email = email, Password = new SecretText(password) });

    /// <summary>Misafir ilerlemesini korur: aynı oyuncu, yeni oturum. Adres kayıtlıysa HTTP 409 gelir.</summary>
    public static async Task<SessionState> UpgradeGuest(OpenPlayClient client, string email, string password, string displayName)
    {
        try
        {
            return await client.Session.UpgradeGuestAsync(new UpgradeGuestInput { Email = email, Password = new SecretText(password), DisplayName = displayName });
        }
        catch (OpenPlayException ex) when (ex.Kind == ErrorKind.Http && ex.Status == 409)
        {
            throw new System.InvalidOperationException("Bu e-posta adresi başka bir hesapta kayıtlı.");
        }
    }

    public static Task RequestReset(OpenPlayClient client, string email) =>
        client.Session.RequestPasswordResetAsync(new PasswordResetRequestInput { Email = email });

    /// <summary>E-postadaki token ile yeni parola; başarıda tüm oturumlar kapanır.</summary>
    public static Task FinishReset(OpenPlayClient client, string token, string newPassword) =>
        client.Session.ResetPasswordAsync(new ResetPasswordInput { Token = new SecretText(token), NewPassword = new SecretText(newPassword) });

    /// <summary>Görünen ad kuralı: normalize sonrası 2..24 karakter, saatte 10 değişiklik.</summary>
    public static Task<SessionState> Rename(OpenPlayClient client, string displayName) =>
        client.Session.RenameAsync(displayName);
}

Magic link

Magic link, e-postaya tek kullanımlık bir bağlantı gönderir. Sunucu uçları vardır, SDK yardımcısı henüz yoktur ve oyun içi bir akış olarak belgelenmemiştir.

POST /v1/auth/sign-in/magic-link
content-type: application/json
x-crx-env: <ortam-kimliği>
x-csrf-token: <csrf-belirteci>

{"email":"[email protected]","name":"Ayşe"}

200 (e-posta varlığı sızmaz); token yalnız e-postadadır, 5 dakika geçerlidir ve tek kullanımlıktır. Sınır: IP 5 / 60 sn, adres 5 / 15 dk. Token GET /v1/auth/magic-link/verify?token=<token> ile tüketilir; başarıda 200, giriş zarfı ve oturum çerezleri döner, geçersiz token 403 verir.

Uyarı

verify ucu da x-crx-env başlığı ister. Tarayıcıda e-postadaki bağlantıya doğrudan tıklamak bu başlığı göndermez ve 401 alır. Bir magic link akışı kurmak istiyorsanız token’ı oyun sayfanızın alıp başlıklı bir istekle doğrulaması gerekir; bu akış SDK’larda ve bu belgede kapsanmaz.

Google ile giriş

Google ile giriş, oyuncunun tek tıkla web üzerinden girmesini sağlar. Bu sayfa akışın iki adımını (başlatma ve tamamlama), callback sayfanızın ne yapması gerektiğini, mevcut e-posta hesabına otomatik bağlanma kuralını ve SDK’sı olmayan yerel platform kanıtlarının HTTP sözleşmesini anlatır.

Not

Web için SDK yardımcıları bugün yalnız Google içindir. Sunucuda Apple form callback’i ve genel bir sağlayıcı kaydı da bulunur, ancak onlar için SDK yardımcısı ve bu belgede ayrıntı yoktur.

Ön koşul: sağlayıcıyı yapılandırın

Google yalnız yapılandırılmış ortamlarda çalışır. Operatör (panelde süper yönetici) Oyun ayarları › Giriş yöntemleri › Google › OAuth bilgilerini düzenle ekranına Google istemci kimliğini, istemci sırrını ve yönlendirme tabanını girer; sır yalnız yazılır, bir daha okunamaz. Yapılandırılmamışsa GET /v1/auth/oauth/providers boş liste döner ve başlatma isteği 403 alır.

Google Cloud konsolundaki Authorized redirect URI, sunucunun kullandığı redirect_uri ile birebir aynı olmalıdır: <yönlendirme tabanı>/google. Örneğin taban https://oyun.example.com/auth/callback ise Google’a https://oyun.example.com/auth/callback/google kaydedilir. Bu adres, sizin oyun sayfanızdır (aşağıdaki callback sayfası). Oyuncu Google’dan oraya code ve state ile döner. Tabanın kendisi /google ile bitmemelidir: https://oyun.example.com/auth/callback/google yazılırsa sunucu …/google/google üretir (Google redirect_uri_mismatch verir); panel ve API bu değeri düzeltilmiş örnekle reddeder. Yapılandırma ayrıntıları operatöre aittir; panel yardımı: Giriş yöntemleri.

Akış

1. Oyun sayfası POST /v1/auth/sign-in/oauth/google ile {url, state} alır ve oyuncuyu url’ye yönlendirir.
2. Oyuncu Google’da onay verir; Google oyuncuyu <yönlendirme tabanı>/google?code=…&state=… adresine döndürür.
3. Callback sayfası GET /v1/auth/callback/google?code=…&state=… çağrısıyla oturumu tamamlar. Yanıt ortak giriş zarfıdır ve oturum çerezlerini yazar.

1. Başlatma

POST /v1/auth/sign-in/oauth/google
content-type: application/json
x-crx-env: <ortam-kimliği>
x-csrf-token: <csrf-belirteci>

{"callback_url":"https://oyun.example.com/auth/callback/google"}

{"url":"https://accounts.google.com/o/oauth2/v2/auth?client_id=…&state=…&code_challenge=…","state":"<64 hex>"}

• url PKCE (code_challenge), state ve OIDC nonce taşır; state 10 dakika geçerlidir.
• callback_url zorunludur (boşsa 400), ancak yönlendirmeyi belirlemez: Google’a giden redirect_uri sunucuda yapılandırılan tabandan gelir. Adresi oyun sayfanızla tutarlı verin.
• 403: sağlayıcı bilinmiyor, yapılandırılmamış ya da devre dışı. 429: IP başına 30 / 60 sn.

2. Tamamlama

GET /v1/auth/callback/google?code=<code>&state=<state>
x-crx-env: <ortam-kimliği>
cookie: <varsa oturum çerezi>

Yanıt 200 ve giriş zarfı + çerezler. Tarayıcıda fetch(..., { credentials: "include" }) kullanın; çağrı ya API ile aynı origin’e gider ya da oyunun alan adı ortamın alan adı listesindeyse doğrudan Open Play adresine (CORS; bkz. Mimari ve barındırma). GET olduğu için CSRF belirteci istemez.

code ve state tek kullanımlıktır; callback’i ikinci kez çağırmayın.

TypeScript SDK

SDK state’i sizin yerinize tarayıcıya bağlar: başlatmada sessionStorage’a (crx-oauth-pending:v1) {state, provider, intent, startedAt} yazar, tamamlamada aynı sekmede denetler. Kayıt yoksa, 10 dakikadan eskiyse, bozuksa ya da sağlayıcı/state uyuşmuyorsa ağ isteği hiç gönderilmez ve oturum durumu değişmez; CrxError kodu OAuthBindingCode.Missing (yok/süresi dolmuş/bozuk) ya da OAuthBindingCode.Mismatch (başka tarayıcı/sekme) olur. Bu, başkasının callback bağlantısıyla oturum devralmayı engeller.

import { CrxError, OAuthBindingCode, type PlayerClient } from "@ferdiunal/open-play-ts";

// Google'ın kullanıcıyı döndürdüğü sayfa: sunucuda yapılandırılan yönlendirme tabanı + "/google" ile aynı yol olmalıdır
// (örn. taban https://oyun.example.com/auth/callback ise sayfa https://oyun.example.com/auth/callback/google).
const CALLBACK_PATH = "/auth/callback/google";

/** 1. adım: Google'a yönlendirin. State'i saklamanız gerekmez; SDK onu bu sekmeye bağlar (sessionStorage). */
export async function beginGoogleSignIn(client: PlayerClient): Promise<void> {
  const callbackUrl = `${window.location.origin}${CALLBACK_PATH}`;
  const { url } = await client.session.startGoogleOAuth(callbackUrl);
  window.location.assign(url);
}

/** Misafir (ya da kayıtlı) oyuncunun hesabına Google kimliğini bağlar; tamamlama aynı callback sayfasında yapılır. */
export async function beginGoogleLink(client: PlayerClient): Promise<void> {
  const callbackUrl = `${window.location.origin}${CALLBACK_PATH}`;
  const { url } = await client.session.linkOAuth("google", callbackUrl);
  window.location.assign(url);
}

/** 2. adım: Google'ın döndüğü sayfada (`/auth/callback/google`) code ve state ile oturumu tamamlayın. */
export async function finishGoogleSignIn(client: PlayerClient): Promise<string> {
  const params = new URL(window.location.href).searchParams;
  const code = params.get("code");
  const state = params.get("state");
  history.replaceState(null, "", window.location.pathname); // code ve state adres çubuğunda kalmasın
  if (code === null || state === null) throw new Error("Callback adresinde code ya da state yok.");
  try {
    const session = await client.session.completeGoogleOAuth(code, state);
    return session.playerId;
  } catch (error) {
    if (error instanceof CrxError && error.code === OAuthBindingCode.Mismatch) throw new Error("Giriş başka bir tarayıcıda başlatılmış.");
    if (error instanceof CrxError && error.code === OAuthBindingCode.Missing) throw new Error("Giriş süresi dolmuş; yeniden başlatın.");
    throw error;
  }
}

/** Hesabıma bağlı sağlayıcı kimlikleri (sağlayıcı hesap kimliği ve e-posta dönmez). */
export async function linkedProviders(client: PlayerClient): Promise<string[]> {
  const result = await client.session.listIdentities();
  return result.identities.map((identity) => identity.provider);
}

• startGoogleOAuth(callbackUrl) = startOAuth('google', callbackUrl); completeGoogleOAuth(code, state) = completeOAuth({ provider, code, state }).
• linkOAuth(provider, callbackUrl) bağlama akışını başlatır (aşağıya bakın); tamamlama yine completeOAuth iledir.
• listIdentities() bağlı kimlikleri verir.
• Callback sayfasında code ve state’i hemen adres çubuğundan kaldırın (history.replaceState).
• Unity SDK’sında OAuth yardımcısı yoktur.

Uyarı

TypeScript SDK’sında startIdentityTransfer adlı bir yöntem görünür; sunucuda karşılığı yoktur (operatör destekli kimlik devri iptal edilmiştir). Kullanmayın.

Misafir ilerlemesini Google’a bağlama

Oturum açık bir oyuncu (misafir ya da kayıtlı) için linkOAuth kullanılır: POST /v1/auth/link/{provider} oturum ister ve {url, state} döner; tamamlama aynı callback ucudur, ancak callback isteği başlatan oyuncunun oturumuyla gelmelidir (çerez ya da Bearer), aksi halde 403.

• Oyuncu misafirse bağlama bir terfidir: aynı player.id, is_guest: false, misafir sırrı emekliye ayrılır ve yeni oturum açılır. Misafirin kendi koyduğu ad korunur; ad hâlâ varsayılan Guest ise Google adı uygulanır.
• Oyuncu kayıtlıysa yalnızca yeni kimlik eklenir; adına dokunulmaz.
• Sağlayıcı başına tek kimlik vardır (422 provider_already_linked).
• Google kimliği başka bir oyuncuya bağlıysa 409 account_already_linked döner; ilerlemeler birleştirilmez.

Ayrıntılar: Hesap bağlama.

E-postayla otomatik bağlanma

Google ile yeni bir kimlikle giren oyuncunun e-postası, mevcut bir e-posta/parola hesabıyla eşleşiyorsa Google kimliği o hesaba otomatik bağlanır ve oyuncu o hesaba girer. Kuralın koşulları:

• E-posta Google tarafından doğrulanmış olmalıdır ve Google bu e-postanın güncel sahipliğine kefil olmalıdır: alan adı gmail.com/googlemail.com ya da imzalı ID token’ın hd talebi e-postanın alan adına eşit (Google Workspace). Üçüncü taraf bir adreste email_verified tek başına yetmez.
• Eşleşme oyuncunun profil e-postasıyla (players.email) yapılır; parolaya, mevcut oturumlara ya da profil e-postasına dokunulmaz.
• Eşleşen hesap banlıysa bağ yazılmaz ve giriş reddedilir.
• Eşleşen hesapta zaten başka bir Google kimliği varsa otomatik bağlanma yapılmaz; yeni bir oyuncu açılır.
• Kayıt kapalı olsa da çalışır (yeni kayıt değildir).
• Bu davranışı kapatan bir ayar yoktur; yerel (native) ID-token yolunda bu bağlama uygulanmaz.
• Misafirin Google’a bağlanmasında (terfi) Google e-postası başka bir oyuncunun e-postasıyla eşleşiyorsa birleştirme yapılmaz; 409 account_already_linked döner.

Hesapta saklananlar: Google kimliği yalnız (ortam, sağlayıcı, sub) ile tanınır. Google’ın ad, doğrulanmış e-posta, dil ve profil görseli adresi kimliğe yazılabilir; sağlayıcının erişim ve yenileme belirteçleri saklanmaz. Bu bilgiler yalnız operatör panelinde görünür.

Yerel platform kanıtları

Mobil yerel girişler için tek bir uç vardır; SDK yardımcısı henüz yoktur (TypeScript’te ve Unity’de yok). Uç, ortak CSRF kurallarına tabidir ve çerez yazmaz: yanıtı Bearer olarak kullanın.

POST /v1/auth/native/{provider}
content-type: application/json
x-crx-env: <ortam-kimliği>
x-csrf-token: <csrf-belirteci>

200 ve {player, tokens, is_new_player} (çerez yok). 400: sağlayıcı yerel girişe uygun değil ya da ortamda kayıtlı değil, zarf biçimi bozuk. 403: kanıt reddedildi (imza, sertifika zinciri, paket kimliği, zaman aşımı, nonce gibi hiçbir ayrım sızdırılmaz). Kullanım için ortamda ilgili platformun yapılandırılmış olması gerekir.

Not

Yerel kanıt yolu e-postayla otomatik bağlanma uygulamaz; aynı kişi yerel ve web yoluyla ayrı oyunculara bölünebilir.

Oturumlar ve CSRF

Giriş yapan oyuncuya bir oturum verilir. Bu sayfa oturumun nasıl taşındığını, ne kadar yaşadığını, nasıl yenilenip kapatıldığını ve durum değiştiren isteklerde zorunlu olan CSRF (çapraz site istek sahteciliği) korumasını anlatır. SDK kullanıyorsanız çoğunu sizin yerinize yönetir; ham REST yazıyorsanız bu sayfa sözleşmedir.

Oturum nasıl taşınır?

Sunucu oturumu iki yerden birinden okur; önce çerez, yoksa Authorization başlığı:

Her oyuncu isteği ayrıca x-crx-env: <ortam-kimliği> taşır. Bearer yolunda taşınan opak oturum belirtecidir; erişim JWT’si değildir (o, oyun sunucunuzun çevrimdışı doğrulaması içindir: Sunucuda doğrulama).

Oturumu okuma

GET /v1/auth/session
x-crx-env: <ortam-kimliği>

{
  "environment_id": "0192…",
  "player_id": "0192…",
  "session_id": "0192…",
  "is_guest": false,
  "active_organization_id": null,
  "displayName": "Ayşe",
  "email": "[email protected]"
}

email misafir ve e-postasız (yalnız Google) hesaplarda null’dır. Yanıt kişisel veri taşır ve Cache-Control: private, no-store ile gelir. Oturum yoksa, iptal edilmişse, süresi dolmuşsa ya da hesap banlıysa 401 döner (ayrım sızmaz).

Süreler

• Kayma: oyuncu oturumla günde en az bir kez istek yaptığında oturum bitişi 30 gün ileri alınır (üst sınırı aşmadan). Her yenileme (refresh) de süreyi 30 güne çeker.
• 30 gün hiç istek yapmayan oturum ölür. 180. günde aktif oturum bile biter; oyuncu yeniden giriş yapar (misafir, aynı sırla aynı hesaba döner).
• Gerçek zamanlı bağlantıyı açık tutmak oturumu uzatmaz.

Yenileme (refresh)

POST /v1/auth/refresh
content-type: application/json
x-crx-env: <ortam-kimliği>
x-csrf-token: <csrf-belirteci>

{}

Yenileme belirteci gövdede ({"refresh_token":"…"}) ya da __Secure-crx.refresh çerezinde taşınır (gövde öncelikli; çerez varsa gövde boş olabilir). Yanıt 200 ve yeni oturum ve yenileme çifti (çerezler de yenilenir; ortak giriş zarfı). Eski yenileme belirteci kullanılmış sayılır.

• Yeniden kullanım tespiti: kullanılmış bir yenileme belirtecinin tekrar sunulması tüm oturum ailesini iptal eder (çalıntı belirteç savunması).
• Hata: 403 (belirteç geçersiz, süresi dolmuş, yeniden kullanılmış ya da CSRF reddi).
• SDK’lar yenilemeyi gerektiğinde kendisi yapar; siz çağırmazsınız.

Çıkış

POST /v1/auth/logout
content-type: application/json
x-crx-env: <ortam-kimliği>
x-csrf-token: <csrf-belirteci>

{}

204; oturum iptal edilir ve çerezler silinir (Max-Age=0). Çağrı idempotenttir: bilinmeyen belirteç sessizce başarılı olur. Yenileme belirteci hiç yoksa (çerez ve gövde boşsa) 400 döner.

Parola değiştirme, parola sıfırlama ve operatör banı da oturumları iptal eder; ilgili sayfalara bakın.

Tek aktif oturum (isteğe bağlı)

Panelde Oyun ayarları › Giriş yöntemleri › Giriş ayarları › Tek aktif oturum anahtarı (yalnız süper yönetici), ortam başına açılır. Açıkken oyuncuya yeni oturum veren her giriş yolu, yeni oturum yazıldıktan sonra oyuncunun diğer oturumlarını iptal eder (“en son giriş kazanır”).

• Anahtar açıldığı anda açık oturumları kapatmaz; yalnız bir sonraki girişten itibaren uygulanır.
• Yenileme (refresh) bu politikayı tetiklemez.
• Diğer cihazdaki oturum bir sonraki istekte 401 alır; SDK durumu reauthRequired olur. Oyununuz bu durumda “başka bir cihazdan giriş yapıldı” gibi bir ekran gösterebilir.

CSRF çift gönderim

Çerezle taşınan oturum, tarayıcı tarafından başka sitelerin isteklerine de otomatik eklenir. Bunu önlemek için durum değiştiren isteklerde çift gönderim (double-submit) CSRF koruması uygulanır: aynı belirteç hem çerezde hem başlıkta gelmelidir.

Kapsam. Aşağıdaki isteklerde zorunludur: /v1/auth/* altındaki tüm GET dışı istekler (giriş uçları dahil); oyuncu oturumuyla çağrılan eklenti komutları (ve POST ile çağrılan sorgular); oyuncu mağaza satın alma (yalnız çerez oturumunda; Authorization: Bearer oturumunda yalnız Origin ve Fetch Metadata denetimi uygulanır); gerçek zamanlı bilet isteği. GET istekleri muaftır. Sunucu anahtarıyla yapılan çağrılar CSRF’ye tabi değildir.

Akış.

1. GET /v1/auth/csrf çağrılır. Yanıt: gövde {"token":"<hex>"}, başlık x-csrf-token: <aynı belirteç> ve Set-Cookie: __Secure-crx.csrf=<mühürlü grant>.
2. Her durum değiştiren istek, çerezi (__Secure-crx.csrf) ve başlığı (x-csrf-token) birlikte gönderir. Tarayıcı çerezi kendisi ekler; başlığı kodunuz ekler.
3. Başarılı her istekte belirteç döner (rotate): yanıt, yeni x-csrf-token başlığı ve yeni Set-Cookie taşır. Bir sonraki istekte yenisini kullanın.
4. Belirteç tek kullanımlıktır. Eski belirteçle tekrar gönderilen istek 403 alır (yeniden oynatma koruması).

# Belirteç al
TOKEN="$(curl -sS -c "$JAR" "$OPEN_PLAY_URL/v1/auth/csrf" | jq -r .token)"

# Kullan; yanıt başlığındaki yeni belirteci bir sonraki istek için sakla
curl -sS -D headers.txt -b "$JAR" -c "$JAR" -X POST "$OPEN_PLAY_URL/v1/auth/logout" \
  -H "content-type: application/json" -H "x-crx-env: $OPEN_PLAY_ENV" -H "x-csrf-token: $TOKEN" -d '{}'
TOKEN="$(grep -i '^x-csrf-token:' headers.txt | awk '{print $2}' | tr -d '\r')"

Dikkat edilecekler:

• Eşzamanlı iki mutasyonu aynı belirteçle göndermeyin; biri başarılı olunca diğeri 403 alır. İstekleri sıraya koyun. SDK’lar bunu tek bir kilitle yapar.
• CSRF çerezi 15 dakika yaşar; süresi dolunca 403 alırsınız. Taze belirteç alıp bir kez yeniden deneyin. 403 düz metindir ve CSRF ile yetki reddi arasında ayrım yapmaz; yanıtta yeni bir x-csrf-token başlığı gelmediyse bunun CSRF katmanı reddi olduğunu anlarsınız.
• Origin denetimi CSRF’nin ilk katmanıdır: tarayıcı isteğinin Origin alan adı ortama bağlı olmalıdır. Bkz. Mimari ve barındırma.
• Çerezsiz (Bearer) istemciler de /v1/auth/* ve eklenti uçlarında CSRF çerezini ve başlığını taşımalıdır (mağaza satın almadaki Bearer kolu istisnadır). Unity SDK’sı bunu yerel derlemede çerezleri kendisi yöneterek, WebGL’de tarayıcı çerezleriyle yapar.

SDK ve oturum durumları

TypeScript session.state.status değerleri:

Unity’de karşılığı SessionStatus (SignedOut, Authenticating, Authenticated, Refreshing, ReauthRequired, SigningOut, LogoutUncertain, Banned, Disposed) değerleridir; durum değişimleri Session.StateChanged olayıyla gelir.

import { CrxError, ErrorKind, createPlayerClient, type PlayerClient, type SessionState } from "@ferdiunal/open-play-ts";

/** Oturum durumunu arayüze bağlar; `state.status` değerleri kapalı bir kümedir. */
export function watchSession(client: PlayerClient, render: (label: string) => void): () => void {
  const label = (state: SessionState): string => {
    switch (state.status) {
      case "authenticated": return state.isGuest === true ? "Misafir" : (state.displayName ?? "Oyuncu");
      case "banned": return "Hesap askıya alındı";
      case "reauthRequired": return "Yeniden giriş gerekiyor";
      case "signedOut": return "Giriş yapılmadı";
      default: return "…"; // authenticating, refreshing, signingOut, logoutUncertain
    }
  };
  render(label(client.session.state));
  return client.session.subscribe((state) => render(label(state))); // dönen işlev aboneliği kapatır
}

/** Sayfa kapanırken: sunucu oturumunu kapatmak için `logout`, yalnız yerel kaynakları bırakmak için `dispose`. */
export async function leave(client: PlayerClient, signOut: boolean): Promise<void> {
  try {
    if (signOut) await client.session.logout();
  } catch (error) {
    if (!(error instanceof CrxError && error.kind === ErrorKind.UnknownOutcome)) throw error;
    // Yanıt kaybolduysa sunucu oturumu kapanmamış olabilir (durum `logoutUncertain`); gerekirse logout'u yeniden deneyin.
  } finally {
    await client.dispose();
  }
}

export function createClient(environmentId: string): PlayerClient {
  return createPlayerClient({ baseUrl: window.location.origin, environmentId });
}

dispose() yalnızca yerel kaynakları bırakır; sunucu oturumunu kapatmak için önce logout() çağırın. AuthenticatedSession.email yalnız oyuncunun kendi ekranı içindir; günlüğe ve analitiğe yazmayın.

Hesap bağlama

Bir oyuncunun kimliği player.id ile tanınır; giriş yöntemleri bu kimliğe bağlanan yollardır. Bu sayfa misafirin kalıcı hesaba geçişini, Google kimliğinin bağlanmasını ve çözülmesini, bağlı kimliklerin listelenmesini ve çakışma durumlarında ne olduğunu anlatır.

Not

Open Play hesapları birleştirmez. Bir kimlik başka bir oyuncuya bağlıysa istek reddedilir; iki oyuncunun ilerlemesi hiçbir yolla tek hesaba katılmaz. Tek istisna, Google’ın e-postayla otomatik bağlanma kuralıdır; o da yeni bir oyuncu açılmasını önleyip kimliği mevcut hesaba ekler.

Misafirden kalıcı hesaba (terfi)

Misafir oyuncu iki yoldan kalıcı hesaba geçer; ikisinde de player.id değişmez, misafir sırrı emekliye ayrılır ve yeni oturum açılır:

Terfi yalnız misafir oyuncular içindir: misafir olmayan bir oyuncu için e-posta terfisi 422 verir. Google ile açılmış ya da zaten kayıtlı bir hesaba sonradan e-posta/parola eklenemez.

Bağlı kimlikleri listeleme

GET /v1/auth/identities
x-crx-env: <ortam-kimliği>

{
  "player_id": "0192…",
  "identities": [ { "provider": "google", "linked_at": "2026-11-03T10:00:00+00:00" } ]
}

• Oturum gerekir (yoksa 401). Yanıt Cache-Control: private, no-store taşır.
• Yalnız sağlayıcı kimlikleri listelenir (google, …); e-posta/parola girişi listelenmez. Sağlayıcının hesap kimliği (sub), e-postası ve belirteçleri yanıtta yoktur.
• TypeScript: session.listIdentities() { playerId, identities: [{ provider, linkedAt }] } döndürür (camelCase); yanıt sıkı doğrulanır, beklenmeyen biçim CrxError(Contract) olur ve oturumu düşürmez.

“Hesabım” ekranınızda “Google bağla” ya da “Google bağlı” göstermek için bu uç yeterlidir.

Kimlik bağlama

POST /v1/auth/link/{provider} oturumdaki oyuncu için OAuth akışı başlatır ve {url, state} döner; oyuncu url’ye yönlendirilir, dönüşte callback tamamlanır. Kurallar:

• Sağlayıcı başına tek kimlik: oyuncuda bu sağlayıcı zaten bağlıysa başlatma 422 (unprocessable: provider_already_linked) verir.
• Oturum bağı: callback, bağlamayı başlatan oyuncunun oturumuyla gelmelidir; oturumsuz ya da başka oyuncunun oturumuyla gelen callback 403 alır.
• Kimlik başka oyuncuda: Google kimliği başka bir oyuncuya bağlıysa callback 409 (already exists: account_already_linked) verir; misafir ilerlemesi dokunulmadan kalır.
• Doğrulanmış e-posta gerekmez; e-postasız hesaplar da bağlayabilir.
• Başlatma ve callback oranları: IP başına 30 / 60 sn ve 60 / 60 sn.

Kimlik çözme

POST /v1/auth/unlink/google
x-crx-env: <ortam-kimliği>
x-csrf-token: <csrf-belirteci>

204. Oturum gerekir. Hatalar:

Not

Bugün bir oyuncunun genellikle tek sağlayıcı kimliği olduğundan, çözme çağrısı pratikte çoğunlukla 400 alır. Uç, ikinci bir sağlayıcı eklendiğinde kullanılmak üzere yerindedir. Unlink için SDK yardımcısı yoktur; ham REST kullanın.

Çakışma tablosu

Hesabı silme

Oyuncu, hesabını oyunun içinden kendisi silebilir. Apple App Store ve Google Play, hesap oluşturmaya izin veren uygulamaların uygulama içinden hesap silmeyi de sunmasını bekler; bu uç o beklentiyi karşılar. Silme geri alınamaz: ne oyuncu ne de operatör silinmiş hesabı geri getirebilir.

İstek

Önce bir CSRF belirteci alın (Oturumlar ve CSRF); sonra:

POST /v1/auth/account/delete
content-type: application/json
x-crx-env: <ortam-kimliği>
x-csrf-token: <csrf-belirteci>

{ "confirm": "delete_my_account" }

Oyuncu kimliği gövdeden gelmez, oturumdan gelir. confirm açık bir onaydır; eksik ya da başka bir değer 422 ile reddedilir. Başarılı istek 204 döner ve oturum ile yenileme çerezlerini siler.

Not

Bu uç yalnız oyuncu oturumuyla çalışır. Sunucu anahtarı (Bearer crx_…) ile bir oyuncuyu bu uçtan silemezsiniz; 401 alırsınız. Bir oyuncuyu operatör olarak silmek için panelin oyuncu sayfasını kullanın.

Yakın giriş kuralı

• Misafir hesap doğrudan silinir.
• Bağlı kimliği olan hesap (e-posta/parola, Google ya da başka sağlayıcı) için oturumun giriş anı en çok 10 dakika önce olmalıdır. Aksi hâlde sunucu hiçbir şeyi silmeden 403 ve şu gövdeyi döner:

{ "code": "recent_sign_in_required" }

Uygulama bu durumda oyuncuyu yeniden giriş yaptırır ve isteği tekrarlar. Süre, oturum yenilemesinden (refresh) değil girişin kendisinden sayılır; oyuncu gün boyu açık bir oturumda olsa bile yeniden giriş gerekir. Giriş anı kanıtlanamıyorsa sunucu güvenli tarafta kalır ve aynı 403’ü verir.

Neler silinir, neler kalır?

Silme tek bir veritabanı işleminde yapılır; ya hepsi olur ya hiçbiri:

Uyarı

Eklentilerin kendi tablolarında tuttuğu serbest kişisel veri bu uçla silinmez. Eklentiniz kişisel veri saklıyorsa kendi silme akışınızı ayrıca bağlamanız gerekir.

Hata ve sınır tablosu

SDK

TypeScript SDK’sında:

try {
  await client.session.deleteAccount({ confirm: "delete_my_account" });
  // state artık signedOut; oyuncuyu giriş ekranına götürün.
} catch (error) {
  if (error instanceof CrxError && error.reason === "recent_sign_in_required") {
    // oyuncuyu yeniden giriş yaptırın, sonra çağrıyı tekrarlayın
  } else {
    throw error;
  }
}

Başarıda SDK, parola değişikliğindeki gibi oturumu sonlandırır ve { status: "signedOut" } döner. recent_sign_in_required durumunda oturum ve hesap değişmez. İstek gönderildikten sonra yanıt kaybolursa sonuç belirsizdir (UnknownOutcome): SDK kör tekrar yapmaz, gerçek durumu uygulamanın restore() çağrısı belirler. Unity SDK’da bu yöntem henüz yoktur.

Mağaza gizlilik notu

Uygulama içinden erişilebilir bir “Hesabımı sil” düğmesi koyun, tıklamadan önce açık bir onay isteyin ve düğmeyi deleteAccount çağrısına bağlayın. Hesap silinince oyuncuya hangi verinin kalacağını (cüzdan defteri anonimleşmiş olarak kalır) gizlilik metninizde belirtin. Silinen hesabın e-postası ve sağlayıcı kimliği serbest kalır; aynı kişi yeniden kayıt olursa sıfırdan başlar.

İlgili sayfalar

• Oturumlar ve CSRF
• Misafir girişi
• Oran sınırları

Oyuncuyu oyun sunucunuzda doğrulama

Oyun sunucunuz, kendisine gelen bir istek ya da bağlantının hangi oyuncuya ait olduğunu bilmek ister. Bu sayfa iki yolu anlatır: Open Play’in imzaladığı erişim JWT’sini çevrimdışı doğrulamak (JWKS ile) ve oturumu Open Play’e sorarak doğrulamak. Hangi yolun sizin için uygun olduğunu sayfanın sonundaki karşılaştırma tablosu söyler.

Uyarı

Bugünkü SDK sınırı: TypeScript ve Unity SDK’ları erişim JWT’sini uygulamaya açmaz; belirteç yalnızca ham REST giriş yanıtının gövdesinde (tokens.access_token) bulunur. SDK kullanan bir istemci JWT’yi sunucunuza veremez. SDK’lı istemciler için aşağıdaki Yol B (oturum doğrulama) kullanılabilir. Bu eksiklik kayıtlıdır.

Yol A: erişim JWT’sini çevrimdışı doğrulama

Belirteç

Giriş, kayıt, yenileme ve OAuth callback yanıtları tokens.access_token döndürür: EdDSA (Ed25519) ile imzalı, 15 dakikalık compact JWT. Belirteç yalnız gövdededir; çerezde taşınmaz. Süresi dolunca POST /v1/auth/refresh yenisini verir.

Başlık: {"alg":"EdDSA","typ":"JWT","kid":"<anahtar-kimliği>"}. Yük:

Uyarı

iat ve exp milisaniyedir ve belirteçte iss/aud yoktur. Standart JWT kütüphaneleri exp’i saniye sayar; milisaniye değerini uzak gelecekte bir tarih sanıp süresi dolmuş belirteci kabul eder. Kütüphane kullanırsanız imzayı ona doğrulatın ama exp denetimini kendiniz yapın (exp > Date.now()).

Anahtarlar (JWKS)

curl -sS "$OPEN_PLAY_URL/v1/auth/jwks"

{"keys":[{"kty":"OKP","crv":"Ed25519","kid":"<anahtar-kimliği>","use":"sig","alg":"EdDSA","x":"<base64url genel anahtar>"}]}

Kimlik gerekmez. Sunucu imzalayıcıyı yayınlamadıysa 404 döner. Yanıtı önbelleğe alın ve yalnızca belirteçteki kid listede yoksa yenileyin; her istekte çekmeyin.

Doğrulama adımları

1. Belirteci üç parçaya ayırın; başlıktaki alg değeri EdDSA olmalı, aksi halde reddedin.
2. kid ile JWKS’ten anahtarı bulun; yoksa JWKS’i bir kez yenileyin.
3. İmzayı header.payload metni üzerinde Ed25519 ile doğrulayın.
4. exp > şimdi (ms) olduğunu denetleyin.
5. env değerini kendi ortam kimliğinizle karşılaştırın.

Uyarı

Aynı Open Play sunucusundaki bütün oyunların belirteçleri aynı JWKS ile doğrulanır. env karşılaştırmasını atlarsanız, başka bir oyunun oyuncusu sizin sunucunuzda geçerli görünür. Bu adım zorunludur.

Node.js (yalnız yerleşik node:crypto, bağımlılık yok):

import { createPublicKey, verify, type JsonWebKey } from "node:crypto";

/** Open Play erişim JWT'sinin (EdDSA) yük alanları. `iat` ve `exp` saniye değil, Unix MİLİSANİYEDİR. */
export interface AccessClaims {
  readonly sub: string; // oyuncu kimliği
  readonly env: string; // ortam kimliği
  readonly sid: string; // oturum kimliği
  readonly org?: string;
  readonly iat: number;
  readonly exp: number;
}

interface Jwks {
  readonly keys: ReadonlyArray<JsonWebKey & { readonly kid?: string }>;
}

function decode(part: string): Buffer {
  return Buffer.from(part, "base64url");
}

/**
 * Oyuncunun erişim JWT'sini çevrimdışı doğrular: imza, süre ve ortam eşleşmesi.
 * JWKS'i her istekte çekmeyin; `jwks` parametresini önbellekten verin (anahtar döndürülürse bilinmeyen `kid` gelince yenileyin).
 */
export function verifyAccessToken(token: string, jwks: Jwks, expectedEnvironmentId: string, nowMs: number = Date.now()): AccessClaims {
  const parts = token.split(".");
  const [header, payload, signature] = parts;
  if (parts.length !== 3 || header === undefined || payload === undefined || signature === undefined) {
    throw new Error("Biçimi bozuk JWT.");
  }
  const head = JSON.parse(decode(header).toString("utf8")) as { alg?: string; kid?: string };
  if (head.alg !== "EdDSA") throw new Error("Beklenmeyen algoritma.");
  const jwk = jwks.keys.find((key) => key.kid === head.kid);
  if (jwk === undefined) throw new Error("Bilinmeyen anahtar kimliği; JWKS'i yenileyin.");
  const publicKey = createPublicKey({ key: jwk, format: "jwk" });
  const signed = Buffer.from(`${header}.${payload}`, "utf8");
  if (!verify(null, signed, publicKey, decode(signature))) throw new Error("İmza doğrulanamadı.");

  const claims = JSON.parse(decode(payload).toString("utf8")) as AccessClaims;
  if (claims.exp <= nowMs) throw new Error("Belirtecin süresi dolmuş.");
  // JWKS tüm oyunlar için ortaktır: başka bir ortamın oyuncusunu kabul etmemek için `env` mutlaka karşılaştırılır.
  if (claims.env !== expectedEnvironmentId) throw new Error("Belirteç başka bir ortama ait.");
  return claims;
}

/** JWKS'i çeker (kimlik gerekmez). */
export async function fetchJwks(baseUrl: string): Promise<Jwks> {
  const response = await fetch(`${baseUrl}/v1/auth/jwks`);
  if (!response.ok) throw new Error(`JWKS okunamadı: ${response.status}`);
  return (await response.json()) as Jwks;
}

Sınırlar

• İptal görmez. Çevrimdışı doğrulama oturumun kapatıldığını, iptal edildiğini ya da oyuncunun banlandığını bilemez; belirteç exp’ine kadar (en çok 15 dakika) geçerli görünür. İptal duyarlı olması gereken işlemlerde Yol B’yi kullanın ya da bu 15 dakikalık pencereyi kabul edin.
• Anahtar döndürme. Anahtar değişimi sunucuyu yeniden başlatır; yeni kid JWKS’te görünür. Önbelleğiniz bilinmeyen kid görünce yenilenmelidir.

Yol B: oturumu Open Play’e sorma

Oyuncunun oturum belirtecini (çerez değeri ya da Authorization: Bearer belirteci) ve ortam kimliğini Open Play’e ileterek oyuncuyu çözersiniz. Tarayıcı oyununda oyunun origin’ine giden isteklerde oturum çerezi (__Secure-crx.session) zaten gelir; sunucunuz bu değeri okuyup Open Play’e Bearer olarak iletebilir.

curl -sS "$OPEN_PLAY_URL/v1/auth/session" \
  -H "Authorization: Bearer $PLAYER_SESSION_TOKEN" \
  -H "x-crx-env: $OPEN_PLAY_ENV"

200 ve {"environment_id","player_id","session_id","is_guest","displayName","email",…}. İptal edilmiş, süresi dolmuş ya da banlı oturum 401 verir. GET olduğu için CSRF belirteci gerekmez.

Uyarı

Oturum belirteci bir yetkidir. Açık metin günlüğe yazmayın, başka servislere yaymayın ve yalnızca TLS üzerinden iletin.

Hangi yolu seçmeliyim?

Sunucu-sunucu çağrılarında oyuncu yerine sunucu anahtarı kullanılır (Kavramlar).

TypeScript SDK

TypeScript SDK’sı Open Play’e tarayıcıdan, Node.js’ten ve oyun motorlarının JavaScript katmanından bağlanmanın tipli yoludur: oyuncu girişi, eklenti komutları, gerçek zamanlı bağlantı ve sunucu anahtarıyla yönetim çağrıları. Bu sayfa kurulumu, giriş noktalarını, temel istemcileri ve hangi modüllerin tipli istemcisi olduğunu anlatır.

Not

Bu belge @ferdiunal/open-play-ts 0.1.15 sürümüyle doğrulanmıştır. Paket GitHub Packages’ta yayımlıdır; depo bugün özeldir, bu yüzden kurulum için yetkili bir GitHub belirteci gerekir.

API başvurusu: tüm tür ve işlevlerin üretilmiş başvurusu https://open-play.b4klabs.dev/docs/sdk/typescript/ adresindedir (@open-play/sdk ve @open-play/panel-kit).

Kurulum

Gereksinimler: Node.js 22 ya da üstü; paket yalnız ESM’dir (require ile yüklenmez). Tarayıcıda Fetch, AbortController ve BigInt destekli modern bir tarayıcı gerekir.

1. Kayıt defterini tanıtın. Projenizin kökündeki .npmrc dosyasına kapsamı (scope) ve belirteç değişkenini yazın. Belirteç read:packages yetkili bir GitHub klasik belirtecidir (ince ayarlı belirteç denenmedi); dosyaya değer yazmayın, ortam değişkeni kullanın:

   @ferdiunal:registry=https://npm.pkg.github.com
   //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
   

2. Paketi kurun:

   export GITHUB_TOKEN="<read:packages yetkili belirteç>"
   npm install @ferdiunal/[email protected]
   

   pnpm aynı .npmrc ile çalışır. Belirteci depoya, imaja ya da CI günlüğüne koymayın.

3. İçe aktarın:

   import { CrxClient, createPlayerClient } from "@ferdiunal/open-play-ts";
   

Uyarı

Paket adı @ferdiunal/open-play-ts’tir. SDK deposundaki bazı dosyalarda ve örneklerde geçen @open-play/sdk adı yalnızca kaynak deposundaki iç addır; yayımlanan pakette kullanmayın.

Giriş noktaları

CLI: crx (npx crx --help). Kod üretimi bölümüne bakın.

İstemciler

CrxClient: sunucu anahtarıyla REST

CrxClient, API anahtarıyla çalışan tipli REST istemcisidir. Sunucu anahtarını yalnız güvenilen arka uçta kullanın; tarayıcıya ya da oyun paketine koymayın.

const client = new CrxClient({ baseUrl: "https://oyun.example.com/open-play", apiKey: serverKey });

ClientOptions: baseUrl, apiKey, isteğe bağlı fetch, timeoutMs (1–120 000 ms, varsayılan 15 sn), maxRetries (0–5, varsayılan 2), maxResponseBytes (varsayılan 2 MiB, en çok 16 MiB). Her çağrı { path, query, body, headers } girdisi ve isteğe bağlı { signal, timeoutMs, maxRetries } alır.

import { CrxClient, CrxError, ErrorKind } from "@ferdiunal/open-play-ts";

/**
 * Sunucu anahtarıyla bir karaktere XP verir. Aynı `requestKey` ile yapılan tekrar aynı sonucu döndürür;
 * `If-Match`, okuduğunuz sürümle yazdığınız sürümün çakışmasını yakalar.
 */
export async function grantXp(
  baseUrl: string,
  serverKey: string,
  characterId: string,
  amount: bigint,
  requestKey: string,
): Promise<bigint> {
  const client = new CrxClient({ baseUrl, apiKey: serverKey });
  const current = await client.getCharacter({ path: { id: characterId } });
  try {
    const result = await client.executeCommand({
      path: { id: characterId },
      body: { type: "add_xp", amount },
      headers: { "Idempotency-Key": requestKey, "If-Match": current.version.toString() },
    });
    return result.version;
  } catch (error) {
    if (error instanceof CrxError && error.kind === ErrorKind.Http && (error.status === 409 || error.status === 422)) {
      // 409: sürüm çakışması; yeniden okuyup karar verin. 422: aynı anahtar başka bir gövdeyle kullanılmış.
      // Yeni bir anahtarla kör yeniden deneme yapmayın.
      throw error;
    }
    throw error;
  }
}

/** Sayfalamayı SDK yürütür: imleç (cursor) opaktır, `break` yeni sayfa istemez. */
export async function countCharacters(baseUrl: string, serverKey: string, definitionKey: string): Promise<number> {
  const client = new CrxClient({ baseUrl, apiKey: serverKey });
  let total = 0;
  for await (const _character of client.iterateListCharacters({ query: { definition: definitionKey, limit: 100 } })) {
    total += 1;
  }
  return total;
}

Çağrı kuralları

• baseUrl HTTPS olmak zorundadır; yalnızca loopback (localhost, 127.0.0.1, [::1]) düz HTTP kabul eder. Adres kullanıcı bilgisi, sorgu ya da parça içeremez. Yönlendirmeler (redirect) izlenmez.
• Anahtar yalnız Authorization başlığındadır; hata nesnelerinde ve hata ayıklama çıktısında görünmez.
• Yeniden deneme yalnızca okuma GET’lerinde ve gerçekten verilmiş aynı Idempotency-Key taşıyan komutlarda yapılır. Geçici 408, 429, 500, 502, 503, 504 ve güvenli işlemde ağ hatası, sınırlı üstel geri çekilmeyle denenir; Retry-After toplam süre sınırı içindedir. 409 ve 422 yeniden denenmez. Oluşturma ve silme çağrıları otomatik tekrarlanmaz.
• Komutlarda If-Match (kaynağın okuduğunuz sürümü) ve Idempotency-Key başlıklarını siz verirsiniz (Idempotency ve eşzamanlılık).
• Sayfalama imleçleri opaktır; iterate… yöntemleri (iterateListCharacters, iterateListCharacterEvents, iterateGetCharacterTimeline, iterateListRules, iterateListWebhooks) sayfaları sizin yerinize yürütür.

PlayerClient: oyuncu oturumu

createPlayerClient({ baseUrl, environmentId }) oyuncu tarafı istemcisidir (yalnız çerez kipi; sunucu anahtarı bu istemciye girmez). İçerdikleri:

İlk kullanım için Hızlı başlangıç. Oturum durumları için Oturumlar ve CSRF.

createPlayerClient ağ isteğini kurucuda başlatmaz; baseUrl oyun sayfanızla aynı origin’dir (ters vekil) ya da oyunun alan adı ortama bağlıysa Open Play adresidir (CORS; aynı site gerekir) (Mimari ve barındırma).

GameClient: oyuncu + eklenti + realtime tek yaşam döngüsü

createGameClient, bir oyuncu istemcisini, eklenti bağlamalarını ve tek gerçek zamanlı soketi aynı yaşam döngüsünde tutar. dispose() çocuk bağlamaları ve kendi yarattığı oyuncu istemcisini kapatır; sunucu çıkışı için ayrıca game.session.logout() çağırın. Dışarıdan verdiğiniz PlayerClient GameClient tarafından sahiplenilmez.

import { createGameClient, type GameClient } from "@ferdiunal/open-play-ts";
import { createBrowserAdapter } from "@ferdiunal/open-play-ts/browser";

/**
 * Bir oyunun oyuncu istemcisi, eklenti bağlamaları ve tek realtime soketi aynı yaşam döngüsünde tutulur.
 * IndexedDB günlüğü (journal) yarım kalan eklenti komutlarının sayfa yenilendikten sonra kurtarılmasını sağlar.
 */
export function startGame(environmentId: string): { game: GameClient; stop: () => Promise<void> } {
  const browser = createBrowserAdapter({ journal: "indexeddb", allowMemoryFallback: false });
  const game = createGameClient({
    playerOptions: { baseUrl: window.location.origin, environmentId, browser },
  });
  return {
    game,
    stop: async () => {
      await game.dispose();
      await browser.dispose();
    },
  };
}

journal: "indexeddb" yarım kalan eklenti komutlarının sayfa yenilendikten sonra kurtarılmasını sağlar. SSR/Node’da journal: "memory" seçin ve istemciyi istekler arasında paylaşmayın.

Gerçek zamanlı soket

client.realtime.connect() tek kullanımlık bilet alır, soketi açar ve kimlik doğrular; kopmada bileti yenileyip imleç/epoch ile kaldığı yerden sürdürür. Sunucu etkinlik göstermeyen soketi 4100 koduyla kapatır; onIdleClose verirseniz SDK otomatik yeniden bağlanmaz ve “Devam et” kararı sizindir. Protokol ayrıntıları Gerçek zamanlı bölümündedir.

import { createPlayerClient, isIdleClose, type PlayerClient } from "@ferdiunal/open-play-ts";

/**
 * Realtime soketini açar. Sunucu, etkinlik göstermeyen soketi 4100 koduyla kapatır; `onIdleClose` verirseniz
 * SDK otomatik yeniden bağlanmaz ve "Devam et" kararını size bırakır.
 */
export function createRealtimeClient(environmentId: string, showContinue: (resume: () => Promise<unknown>) => void): PlayerClient {
  const client: PlayerClient = createPlayerClient({
    baseUrl: window.location.origin,
    environmentId,
    realtime: {
      onIdleClose: () => showContinue(() => client.realtime.connect()),
    },
  });
  return client;
}

/** Durumu yoklayan uygulama aynı bilgiyi `lastClose` üzerinden okuyabilir. */
export function wasIdleClosed(client: PlayerClient): boolean {
  return isIdleClose(client.realtime.lastClose);
}

/** Oturum açıldıktan sonra soketi kurar; bilet yenileme ve yeniden bağlanma SDK'dadır. */
export async function connect(client: PlayerClient): Promise<void> {
  const connection = await client.realtime.connect();
  console.log("realtime durumu:", connection.state);
}

Kapsam: hangi modülün tipli istemcisi var?

SDK, REST yüzeyinin tamamını sarmaz. Aşağıdaki tablo bugünkü durumu gösterir; “ham REST” olan modüller için uçları uç nokta başvurusunda bulur, HTTP çağrısını kendiniz yaparsınız (anahtar ve başlık kuralları aynıdır).

CrxClient’ta tipli işlem sayısı 45’tir (25 çekirdek + 20 klan) ve katalog ile ödül tablosu işlemleri bunlara eklenir. Tipli istemcisi olmayan bir modülü kullanmak sorun değildir; yalnızca tipleri elle yazarsınız.

Hatalar

Tüm hatalar CrxError olarak gelir: kind, status, attempts ve güvenli metadata (code, operation, deliveryState, reference, reason). HTTP gövdesi, istek URL’si ve anahtar hata nesnesine girmez.

Banlı hesap error.code === ACCOUNT_BANNED_CODE ile ayırt edilir (Kimlik doğrulamaya genel bakış).

Sayılar ve JSON

• i64/u64 alanlar bigint’tir; 32 bit alanlar sınır denetimli number’dır. 9007199254740993n kayıpsız taşınır.
• SDK yükünü JSON.parse/JSON.stringify ile yeniden dolaştırmayın; parseJson, stringifyJson, encodeModel, decodeModel kullanın. Ondalık sayılar LosslessNumber olur.
• Varsayılan sınırlar: JSON 2 MiB, derinlik 96, düğüm sayısı 200 000.
• Eklenti protokolünde i64 değerler ondalık dizgedir (plugin-v1-decimal-int64). Bkz. Sayılar ve kodlama.

Kod üretimi (crx)

Eklenti şemasından tipli bağlama ve karakter tanımından tip üretmek için CLI kullanılır (yalnız Node; ağ erişimi yoktur, girdi dosyadır, çıktı yalnız yeni dosyaya yazılır, --check bayt karşılaştırır):

# Eklenti bağlaması: şema özeti (sha256) sabitlenir; değişirse üretim reddedilir
npx crx plugins generate --input plugin.schema.json --schema-sha256 "$SCHEMA_SHA256" --output binding.ts
npx crx plugins generate --input plugin.schema.json --schema-sha256 "$SCHEMA_SHA256" --output binding.ts --check

# Karakter tanımı tipleri
npx crx types generate --input definition.json --version 1 --schema-sha256 "$SCHEMA_SHA256" --output hero.ts

Eklenti şemasını nereden alacağınızı ve schemaSha256 sabitlemenin anlamını Eklenti bağlamaları sayfası anlatır.

Bilinen sınırlar

• Yalnız çerez kipi vardır; oyuncu istemcisinde Bearer ya da sunucu anahtarı kipi yoktur.
• Erişim JWT’si uygulamaya açılmaz (Sunucuda doğrulama).
• Magic link, unlink ve yerel platform girişleri için yardımcı yoktur.
• Görünen ad değiştirme (POST /v1/auth/session/display-name) için yöntem yoktur.
• Sunucu CORS’u yalnız ortam alan adı listesindeki origin’lere verir; oturum çerezi SameSite=Lax olduğundan oyun ile Open Play aynı sitede olmalıdır, değilse ters vekil kullanın.

Unity SDK

com.openplay.sdk, Unity’den Open Play’e bağlanan C# istemcisidir: misafir ve e-posta/parola oturumu, oturumun yeniden başlatmalar arasında geri yüklenmesi, eklenti komutları ve sorguları ve gerçek zamanlı soket. Bu sayfa kurulumu, kullanımı ve neyin doğrulandığını dürüstçe anlatır.

Uyarı

Paket yalnız Unity 6000.6.7f1 ile doğrulanmıştır; başka editör sürümleri ve çoğu platform doğrulanmadı (Doğrulanan platformlar). Bu belge paket sürümü 0.1.0 içindir.

API başvurusu: C# tiplerinin üretilmiş başvurusu https://open-play.b4klabs.dev/docs/sdk/unity/ adresindedir.

Kurulum

Paket, https://npm.pkg.github.com/@ferdiunal adresindeki GitHub Packages npm kayıt defterinden gelir. Paket adı kapsamsızdır (com.openplay.sdk); kapsam kayıt defteri adresindedir.

1. Kimlik. GitHub herkese açık paketlerde bile belirteç ister. Kullanıcı klasörünüzde ~/.upmconfig.toml oluşturun. Belirteç read:packages yetkili bir klasik belirteçtir (ince ayarlı belirteç denenmedi) ve bir sırdır: depoya koymayın, günlüğe yazmayın.

   [npmAuth."https://npm.pkg.github.com/@ferdiunal"]
   token = "<read:packages yetkili belirteç>"
   alwaysAuth = true
   

2. Manifest. Oyun projenizin Packages/manifest.json dosyasına kapsamlı kayıt defterini ve bağımlılığı ekleyin:

   {
     "dependencies": { "com.openplay.sdk": "0.1.0" },
     "scopedRegistries": [
       { "name": "Open Play", "url": "https://npm.pkg.github.com/@ferdiunal", "scopes": ["com.openplay"] }
     ]
   }
   

3. Unity’yi açın. İki bilinen davranış: Package Manager’ın arama ekranında paket görünmez (GitHub’ın arama uç noktası 405 döner; paketi manifest.json’a elle yazarsınız) ve günlükte Package 'com.openplay.sdk' has been installed without a signature uyarısı çıkar (zararsızdır).

com.unity.nuget.newtonsoft-json 3.2.1 ve com.unity.modules.unitywebrequest bağımlılıkları kendiliğinden çözülür. Yedek yol olarak yerel yol ("com.openplay.sdk": "file:<yol>/sdks/unity") kullanılabilir; bu yalnız kaynak deposuna erişimi olanlar içindir.

Paket bir Basic Login örneği içerir (Package Manager › Open Play SDK › Samples).

Temel kullanım

OpenPlayClient.Create(OpenPlayUnity.Options(baseUrl, environmentId)) istemciyi kurar; Options ana iş parçacığı pompasını, PlayerPrefs deposunu ve platforma uygun taşımayı seçer. Hızlı başlangıçtaki bileşen kayıtlı oturumu geri yükler, yoksa misafir açar.

OpenPlayOptions ayarları:

Yanlış ayar OpenPlayException ile ErrorKind.Configuration ve kodlu bir neden verir (örneğin base_url_scheme_invalid, insecure_transport_not_loopback, environment_id_required).

Oturum

client.Session:

SessionStatus: SignedOut, Authenticating, Authenticated, Refreshing, ReauthRequired, SigningOut, LogoutUncertain, Banned (terminal; yalnız LogoutAsync ile çıkılır), Disposed. Parola ve belirteçler SecretText ile taşınır; ToString() ve günlüklere girmez.

E-posta ve parola örnekleri için E-posta ve parola sayfasına bakın.

Sır depolama

Misafir sırrı ve yenileme belirteci ISecretStore ile saklanır. Varsayılan PlayerPrefs deposu düz metindir ve güvenli depo değildir (iOS Keychain, Android Keystore yok). Üretimde platformun güvenli deposuna yazan kendi ISecretStore uygulamanızı verin:

using System.Threading;
using System.Threading.Tasks;
using OpenPlay.Support;

/// <summary>Platformunuzun güvenli deposunu (iOS Keychain, Android Keystore, masaüstü kimlik deposu) temsil eden kendi arayüzünüz.</summary>
public interface IPlatformKeystore
{
    string Read(string key);
    void Write(string key, string value);
    void Delete(string key);
}

/// <summary>
/// ISecretStore sözleşmesi: misafir bootstrap sırrı ve yenileme belirteci burada saklanır.
/// Varsayılan PlayerPrefs deposu düz metindir ve güvenli depo DEĞİLDİR; üretimde bunun gibi kendi deponuzu verin:
///   options.SecretStore = new KeystoreSecretStore(myKeystore);
/// </summary>
public sealed class KeystoreSecretStore : ISecretStore
{
    private readonly IPlatformKeystore _keystore;

    public KeystoreSecretStore(IPlatformKeystore keystore) { _keystore = keystore; }

    public Task<string> GetAsync(string key, CancellationToken cancellationToken) => Task.FromResult(_keystore.Read(key));

    public Task SetAsync(string key, string value, CancellationToken cancellationToken)
    {
        _keystore.Write(key, value);
        return Task.CompletedTask;
    }

    public Task ClearAsync(string key, CancellationToken cancellationToken)
    {
        _keystore.Delete(key);
        return Task.CompletedTask;
    }
}

Sözleşme: değer günlüğe, istisna iletisine ve ToString()’e girmez; olmayan anahtar için GetAsync null döner; her işlem başarısız olabilir ya da geç dönebilir (SDK 3 sn sonra vazgeçer).

Eklenti komutları ve sorguları

client.Plugin(binding, pin) eklenti istemcisi verir (PrepareCommand, QueryAsync, PublicQueryAsync, VerifyServerSchemaAsync). Komut hazırlanırken tek bir Idempotency-Key üretilir ve gövde dondurulur; belirsiz sonuçta (ErrorKind.UnknownOutcome) aynı anahtarla LookupAsync ile sorgulanır, kaybolduysa ResumeAsync ile tam aynı komut yeniden gönderilir. Kör yeni komut üretilmez.

Not

Yayımlanan pakette yalnız package-ride eklentisinin üretilmiş tipli bağlaması vardır (OpenPlay.PackageRide). Başka bir eklenti için bugün üretilmiş Unity bağlaması yoktur; ham PluginBinding ile çalışırsınız. Bağlama, sunucudaki şema özetine (schemaSha256) sabitlenir: uyuşmazlıkta UpgradeRequired alırsınız.

using System.Threading.Tasks;
using OpenPlay;
using OpenPlay.PackageRide;
using OpenPlay.Plugins;

/// <summary>
/// Eklenti komutu: yayımlı pakette yalnız package-ride için üretilmiş tipli bağlama vardır.
/// Komut hazırlanırken tek Idempotency-Key üretilir; belirsiz sonuçta AYNI anahtarla sorgulanır.
/// </summary>
public static class PluginCall
{
    public static async Task ClaimLoginBonus(OpenPlayClient client, long expectedVersion)
    {
        var rides = PackageRideClient.Create(client); // bağlama sürümü ve şema özeti sunucuyla eşleşmezse UpgradeRequired
        var command = rides.Commands.ClaimLoginBonus.Prepare(new LoginBonusInput { ExpectedVersion = expectedVersion });
        try
        {
            var receipt = await command.SendAsync();
            LoginBonusOutput output = rides.Commands.ClaimLoginBonus.ParseOutput(receipt); // tipli çıktı
            UnityEngine.Debug.Log("giriş bonusu işlendi, HTTP durumu: " + receipt.Status + ", çıktı: " + output.GetType().Name);
        }
        catch (OpenPlayException ex) when (ex.Kind == ErrorKind.UnknownOutcome)
        {
            // Yanıt kayboldu; komut uygulanmış olabilir. Yeni komut üretmeyin, aynı anahtarla sorgulayın.
            var lookup = await command.LookupAsync();
            if (lookup.Status == CommandLookupStatus.NotFound) await command.ResumeAsync(); // tam aynı anahtar ve gövde
        }
    }
}

Gerçek zamanlı

client.Realtime.ConnectAsync() bileti alır, soketi açar ve kimlik doğrular; kopmada artan gecikmeyle yeniden bağlanır. Yerel derlemede bilet Authorization: Bearer + x-crx-env + sabit Origin ile alınır; çerez kullanılmaz. Abonelik açmak için RealtimeConnection.JoinAsync(modül, JoinTarget.PlayerSelf() / Room / Scene / InterestSet) kullanılır. Protokol ayrıntıları: Gerçek zamanlı.

using System;
using System.Threading.Tasks;
using OpenPlay;
using OpenPlay.Realtime;
using OpenPlay.Unity;

/// <summary>
/// Realtime soketi: bilet alma, bağlanma ve yeniden bağlanma SDK'dadır.
/// Sunucu etkinlik göstermeyen soketi 4100 koduyla kapatır; OnIdleClose verirseniz otomatik yeniden bağlanma olmaz.
/// </summary>
public static class RealtimeConnect
{
    public static OpenPlayClient Create(Uri baseUrl, Guid environmentId, Action showContinue)
    {
        var options = OpenPlayUnity.Options(baseUrl, environmentId);
        options.Realtime = new RealtimeOptions { OnIdleClose = _ => showContinue() }; // "Devam et" düğmesini gösterin
        return OpenPlayClient.Create(options);
    }

    /// <summary>Oturum açıldıktan sonra çağrılır; "Devam et" onayında da aynı çağrı yeni bilet alıp sürdürür.</summary>
    public static Task<RealtimeConnection> Connect(OpenPlayClient client) => client.Realtime.ConnectAsync();
}

WebGL

WebGL oynatıcısında SDK tarayıcı kipine geçer (OpenPlayUnity.Options bunu kendisi seçer): HTTP UnityWebRequest ile, gerçek zamanlı tarayıcının WebSocket’iyle (küçük bir jslib köprüsü) gider ve oturum çerezlerini tarayıcı yönetir. SDK Cookie, Origin, Authorization ya da User-Agent başlığı koymaz; her mutasyon x-csrf-token taşır.

• Yalnız aynı origin (SDK kısıtı). Unity WebGL SDK’sı bugün oyun sayfası ile Open Play API’sinin aynı kökten sunulmasını şart koşar; sunucu artık ortam alan adı listesindeki origin’lere CORS verir ama Unity SDK’sı bunu henüz kullanmaz (Mimari ve barındırma). Farklı origin OpenPlayException ile Configuration ve webgl_cross_origin_unsupported kodunu verir; sessizce başarısız olmaz.
• Gizli sekme. Kalp atışı tarayıcı zamanlayıcısıyla sürer, sekme arka plana alınınca bağlantı açık kalır. Gizliyken gelen mesajlar ve HTTP tamamlanmaları Unity karesini bekler ve sekme görünür olunca işlenir. Application.runInBackground kapalıyken oyun döngüsü gizli sekmede durur; oyununuz gizliyken de ilerlemeliyse Application.runInBackground = true yapın.
• Çok sekme. Aynı origin’deki sekmeler tek çerez kavanozunu paylaşır; ikinci sekmedeki giriş birincinin oturum çerezini değiştirir.

Doğrulanan platformlar

Düzey: R = Unity’de ölçüldü, B = yalnız belge ya da dotnet göstergesi, — = yok.

package.json içindeki unity: 2022.3 alanı yalnız alt sınırdır; Unity 2022.3 doğrulanmadı.

Hatalar

Tüm hatalar OpenPlayException olarak gelir: Kind (ErrorKind), Status, Attempts, Code, Operation, DeliveryState, Reference, Reason. ErrorKind değerleri: Http, Network, Timeout, Cancelled, Contract, Configuration, Pagination, Codegen, Auth, UnknownOutcome, Storage, Realtime, Backpressure, UpgradeRequired, CapabilityUnavailable, Disposed, ScopeChanged. Anlamları TypeScript SDK’sındakilerle aynıdır (TypeScript SDK › Hatalar).

Kapsam dışı ve bilinen sınırlar

• Unity SDK’sında yoktur: OAuth (Google), katalog, mağaza, skor tablosu, bildirimler ve sunucu anahtarıyla yönetim işlemleri. Bunlar için ham REST kullanın; sunucu anahtarını oyun istemcisine koymayın.
• Yanıt sıkıştırması (permessage-deflate) yoktur.
• Erişim JWT’si uygulamaya açılmaz (Sunucuda doğrulama).
• Android, iOS ve macOS oynatıcı koşuları yapılmadı; WebGL yalnız aynı origin’de çalışır.
• PlayerPrefs deposu güvenli değildir; üretimde kendi deponuzu verin.

Karakterler

Bu sayfa, oyuncunun oynadığı karakterin Open Play’de nasıl tanımlandığını, oluşturulduğunu ve değiştirildiğini anlatır. Karakter durumunu (özellikler, kaynaklar, XP, seviye, yetenekler, bayraklar) sunucuda tutmak ve hile yapılamayan komutlarla değiştirmek istiyorsanız okuyun.

Ne işe yarar

Karakter modülü (characters), oyuncuya bağlı karakter durumunu tek bir güvenilir yerde tutar. Durum yalnız komutlarla değişir ve her değişiklik değiştirilemez bir olay (event) olarak kaydedilir. Böylece bir karakterin herhangi bir andaki durumunu geri okuyabilir, hatalı bir değişikliği yeni bir olayla geri alabilirsiniz.

Modül kapalıysa bu sayfadaki uçların hepsi 404 ve {"code":"module_disabled","module":"characters"} döner. Modülü Oyun ayarları › Modüller sayfasından açın.

Panelde nerede

Veri modeli (düz dille)

• Özellik (trait): Yeniden kullanılabilir alan paketi. Örneğin “savaşçı” özelliği güç ve can alanlarını getirir. Bir şablon birden çok özelliği birleştirir.
• Şablon (definition): Anahtarla (warrior) tanımlanan karakter türü. Hangi özellikleri kullandığını, alanların varsayılanlarını, karakterin nasıl yaratılacağını (defaults, point_buy, roll) ve hangi seviye eğrisini izlediğini söyler. Şablon her yayında yeni bir sürüm olur; var olan karakterler doğdukları sürüme bağlı kalır.
• Seviye eğrisi (level curve): Seviyenin kaç XP’ye karşılık geldiğini tarif eder. Seviye saklanmaz, kümülatif XP’den türetilir; eğriyi değiştirmek karakter verisinde dönüşüm gerektirmez. Üç tür vardır: table (eşik listesi), piecewise (seviye aralığı başına XP) ve formula (kuadratik formül, max_level ile).
• Karakter: Bir şablondan doğan örnek. external_id alanına oyunun kendi oyuncu kimliğini yazabilirsiniz; aynı ortamda iki karaktere aynı external_id verilemez.
• Durum (state): attributes (özellik değerleri), resources (can/mana gibi tüketilen kaynaklar), progression (level, xp, highest_level), abilities, flags (evet/hayır bayrakları) ve serbest custom alanı.
• Sürüm (version): Karakterin her komutla artan sayısı. Eşzamanlı yazmayı engellemek için kullanılır (aşağıda).

Sayılar tam sayıdır (i64); ondalık sayı yoktur. Yüzdeler baz puan (basis point) olarak yazılır, 10000 = %100. Ayrıntı: Sayılar ve kodlama.

Oyunun yaptığı çağrılar

Karakter uçları API anahtarıyla çağrılır; oyuncu oturumu (çerez ya da oturum belirteci) bu uçlarda geçerli değildir. İstek başlığı:

Authorization: Bearer crx_live_<önek>_<gizli>

Anahtarın türü önemlidir (bkz. Kavramlar): sunucu anahtarı her komutu çalıştırır, istemci anahtarı yalnız set_flag komutunu çalıştırabilir. Sunucu anahtarını oyuna gömmeyin.

Kimlik ve modül kuralları ile hata gövdeleri: Hatalar. Sayfalama: Sayfalama (limit 1–200, varsayılan 50; next_cursor null ise son sayfadır).

Not

Hata gövdeleri bu uçlarda düz metindir (text/plain). Yalnız module_disabled ve account_banned JSON döner.

Uyarı

Bilinen kısıt: Şablon, özellik, seviye eğrisi ve kural yazan uçlar ile karakter okuma/silme uçları anahtar türüne bakmaz; geçerli bir istemci anahtarı da çağırabilir. İstemci anahtarı ortam kapsamlıdır, oyuncu kapsamlı değildir: oyuna gömülen anahtarla o ortamdaki herhangi bir karakter okunabilir ya da silinebilir. Bu yüzden yönetim çağrılarını ve karakter silmeyi yalnız kendi sunucunuzdan yapın; oyuncudan gelen karakter kimliğine sunucunuzda sahiplik denetimi uygulayın. Anahtar türüne göre kapı henüz yok.

Karakter oluşturmak

POST /v1/characters
Authorization: Bearer crx_live_<önek>_<gizli>
Content-Type: application/json

{ "definition": "warrior", "external_id": "oyuncu-1234" }

{
  "id": "0192f0f2-5b1a-7c3e-9d11-4a5b6c7d8e9f",
  "definition": "warrior",
  "definition_version": 3,
  "external_id": "oyuncu-1234",
  "version": 1,
  "level": 1,
  "state": {
    "attributes": { "strength": 10 },
    "resources": { "hp": 100 },
    "progression": { "level": 1, "xp": 0, "highest_level": 1, "granted_rewards": [] },
    "abilities": [],
    "flags": {},
    "custom": {}
  },
  "created_at": "2026-11-03T09:00:00Z"
}

Gövdede ayrıca allocation (puan dağıtımlı yaratımda alan → harcanan puan), seed (zarlı yaratımda zorunlu, belirleyici tohum) ve custom (en çok 64 KB serbest JSON) bulunabilir. Mod şablonda tanımlıdır; istek yalnız modun istediği girdiyi taşır.

Uyarı

Oluşturma ve silme uçları idempotency anahtarı almaz ve otomatik tekrar denenmez. Aynı external_id ile ikinci bir oluşturma 409 döner; bu, kopya karakter oluşmasını da engeller. Ağ hatasında önce external_id ile aramadan körlemesine tekrar göndermeyin.

Komut çalıştırmak

POST /v1/characters/{id}/commands
Authorization: Bearer crx_live_<önek>_<gizli>
Content-Type: application/json
Idempotency-Key: gorev-17-oyuncu-1234
If-Match: 1

{ "type": "add_xp", "amount": 250 }

{
  "id": "0192f0f2-5b1a-7c3e-9d11-4a5b6c7d8e9f",
  "version": 2,
  "state": { "...": "güncel durum" },
  "events": [
    { "id": "…", "seq": 2, "type": "xp_added", "payload": { "...": "…" }, "created_at": "2026-11-03T09:01:00Z" }
  ],
  "replayed": false
}

Komut türleri type alanıyla seçilir:

İstemci anahtarıyla set_flag dışında bir komut gönderirseniz 403 alırsınız ve idempotency anahtarınız yanmaz.

Bir komut birden çok olay üretebilir: örneğin add_xp bir seviye atlatırsa yanıtta xp_added ve level_up birlikte gelir; tanımlı kurallar da ek olay üretir.

Eşzamanlılık ve tekrar güvenliği

• Idempotency-Key (isteğe bağlı, 1–200 karakter): Aynı anahtar ve aynı gövde ikinci kez gelirse komut tekrar çalışmaz, ilk yanıt replayed: true ile döner. Aynı anahtarla farklı gövde 422’dir. Anahtar yalnız komut başarılı olunca “yanar”; reddedilen komut anahtarı tüketmez. Aynı anda uçuşta olan aynı anahtar 409 alır.
• If-Match (isteğe bağlı): Okuduğunuz version değeri, 3 ya da "3" biçiminde. Karakter bu sürümde değilse komut 409 ile reddedilir ve hiçbir şey değişmez. * ve zayıf W/ biçimleri kabul edilmez (400). rollback komutunda If-Match işlenmez.

Genel kurallar: Idempotency ve eşzamanlılık.

Geri alma

rollback komutu geçmişi silmez. Karakteri to_version sürümündeki duruma döndüren yeni bir olay (character_rolled_back) yazar; olay günlüğü yalnızca eklenir.

Olaylar ve webhook’lar

Karakter olayları (flag_set, attribute_set, resource_changed, modifier_added, modifiers_removed, xp_added, level_up, ability_unlocked, event_emitted, character_rolled_back) webhook olarak da gönderilebilir. Zarfta event_id, type, character_id, environment_id, seq ve data bulunur. Kayıt ve doğrulama: Webhook’lar.

Sınırlar

• custom alanı en çok 64 KB; içinde ondalık sayı olamaz.
• Liste uçlarında limit 1–200.
• Seviye 1’den küçük olamaz; en çok 65535.
• GET …/state?at= geleceğe ya da eksi bir zamana 400 döner. at, Unix milisaniyesi veya RFC 3339 zamanıdır.

Sık görülen hatalar

Çalışan örnek

Aşağıdaki örnek bir karakter oluşturur ve güvenle XP verir. Şablonun (warrior) panelden ya da POST /v1/definitions ile önceden tanımlı olması gerekir.

/** Güvenilir backend örneği: karakter oluşturur, XP verir. Server anahtarı yalnız sunucu ortamından gelir. */
import { CrxClient, CrxError } from "@ferdiunal/open-play-ts";

/** Oyuncunun karakterini açar ve ilk XP'yi güvenle (idempotent) verir. */
export async function createAndReward(baseUrl: string, serverApiKey: string, playerId: string): Promise<bigint> {
  const crx = new CrxClient({ baseUrl, apiKey: serverApiKey });

  // 1) Karakteri tanımdan oluştur. `external_id` oyunun kendi oyuncu kimliğidir.
  const character = await crx.createCharacter({
    body: { definition: "warrior", external_id: playerId },
  });

  // 2) XP ver: aynı Idempotency-Key ile tekrar denemek ikinci XP vermez.
  //    If-Match, karakterin okuduğunuz sürümüdür; araya başka komut girdiyse 409 döner.
  try {
    const result = await crx.executeCommand({
      path: { id: character.id },
      body: { type: "add_xp", amount: 250n },
      headers: {
        "Idempotency-Key": `quest-1-${playerId}`,
        "If-Match": character.version.toString(),
      },
    });
    return result.version;
  } catch (error) {
    if (error instanceof CrxError && error.status === 409) {
      // Sürüm çakışması: karakteri yeniden okuyup komutu yeni sürümle gönderin.
      throw new Error("Karakter bu arada değişti; yeniden okuyup tekrar deneyin.");
    }
    throw error;
  }
}

İlgili sayfalar

• Kavramlar: anahtar türleri ve oturumlar
• Oyun kuralları ve otomasyonlar
• Envanter ve eşyalar
• Hatalar, Idempotency ve eşzamanlılık

Envanter ve eşyalar

Bu sayfa, oyunun eşyalarını (iksir, silah, kozmetik…) tanımlamayı, oyuncuya vermeyi, tüketmeyi, devretmeyi ve envanterde yerleştirmeyi anlatır. Envanter durumunun sunucuda güvenle tutulmasını istiyorsanız okuyun.

Ne işe yarar

Eşya modülü (items) iki ayrı şeyi yönetir:

• Eşya tanımı (item definition): “Küçük can iksiri” gibi bir tür. Anahtarı, türü, yığılabilir (stackable) olup olmadığı, takas edilebilirliği ve NPC alış/satış fiyatı burada durur.
• Eşya örneği (item instance): Bir oyuncunun elindeki gerçek eşya. Hangi tanım sürümünde doğduğunu, sahibini, adedini ve özelleştirme verisini (metadata) taşır.

Envanter, bir sahibin eşyalarının yerleşimidir. Envanter yalnız hangi eşyanın hangi yuvada olduğunu tutar; adet ve özelleştirme eşya örneğindedir.

Modül kapalıysa uçlar 404 ve {"code":"module_disabled","module":"items"} döner. Modülü Oyun ayarları › Modüller sayfasından açın.

Panelde nerede

Veri modeli (düz dille)

• Tür (kind): consumable, equipment, material, cosmetic, vip_card.
• Yığılabilir (stackable) ve max_stack: Yığılabilir eşyada aynı tanım sürümünden ve boş metadata’lı örnekler tek satırda birleşir. stackable: true ise max_stack zorunludur (1 ile 2147483647 arası).
• tradeable: false ise eşya başka sahibe devredilemez (422). Varsayılan true.
• npc_buy_price, npc_sell_price: En küçük birimde tam sayı. null ise tüccarla alım/satım kapalıdır.
• Sürüm sabitleme (pin): Her örnek, doğduğu tanım sürümünü (definition_version) taşır. Tanımı sonradan değiştirmek eski örneklerin kurallarını değiştirmez.
• Sahip (owner): <tür>:<uuid> biçimi; tür player, character, clan ya da system olabilir. Örnek: player:0192f0f2-5b1a-7c3e-9d11-4a5b6c7d8e9f.
• Envanter: İlk komutta kendiliğinden açılır (varsayılan kapasite 32). Kapasite, dolu yuva sayısının üst sınırıdır; yuva numarası 0 veya daha büyük herhangi bir sayı olabilir. Hiç açılmamış envanteri okumak 404 döner ve envanteri açmaz.
• version: Hem eşya örneğinin hem envanterin kendi sürümü vardır; her değişiklikte artar ve If-Match ile kullanılır.

Oyunun yaptığı çağrılar

Eşya ve envanter uçları API anahtarıyla çağrılır:

Authorization: Bearer crx_live_<önek>_<gizli>

Oyuncu tarafı iki okuma ucu sunar; bunlar oyuncu oturumuyla çağrılır (çerez ya da oturum belirteci, x-crx-env: <ortam uuid> başlığıyla):

Not

TypeScript SDK’sında eşya ve envanter için tipli istemci yoktur; bu uçlar ham REST ile çağrılır. Oyuncu oturumuyla okuma (/v1/player/*) için de SDK yardımcısı henüz yok. Kapsam tablosu: TypeScript SDK.

Uyarı

Bilinen kısıt: consume, transfer, move, split, stack, equip ve unequip uçları anahtar türüne bakmaz; geçerli bir istemci anahtarı da çağırabilir ve owner ya da eşya kimliği istekte serbestçe verilir. İstemci anahtarı ortam kapsamlıdır, oyuncu kapsamlı değildir. Oyuncunun yalnız kendi eşyasına dokunduğunu kendi sunucunuzda doğrulayın; hile riskine karşı bu çağrıları oyun sunucusundan yapın. mint ve destroy yalnız sunucu anahtarıyla çalışır.

Eşya üretmek (mint)

POST /v1/items
Authorization: Bearer crx_live_<önek>_<gizli>
Content-Type: application/json
Idempotency-Key: quest-17-potion-oyuncu-1234

{
  "definition_key": "health_potion",
  "owner": "player:0192f0f2-5b1a-7c3e-9d11-4a5b6c7d8e9f",
  "quantity": 3,
  "source": "quest"
}

{
  "instance": {
    "id": "0192f1aa-1111-7222-8333-944455556666",
    "definition_id": "0192f0aa-0000-7000-8000-000000000001",
    "definition_version": 2,
    "owner_type": "player",
    "owner_id": "0192f0f2-5b1a-7c3e-9d11-4a5b6c7d8e9f",
    "quantity": 3,
    "metadata": {},
    "version": 1,
    "created_event_id": "0192f1aa-2222-7333-8444-955566667777",
    "created_at": "2026-11-03T09:00:00Z",
    "updated_at": "2026-11-03T09:00:00Z"
  },
  "event": { "type": "item_instance_created" },
  "replayed": false
}

• quantity 1 ile 2147483647 arasındadır.
• source mint, craft, purchase, quest ya da grant olabilir; verilmezse mint.
• metadata doluysa eşya yığılmaz, her zaman tek satır olur.
• Yığılabilir tanımda, sahibin elinde aynı sürümde boş metadata’lı bir yığın varsa yeni satır açılmaz, adet o yığına eklenir. max_stack aşılırsa 422.

Tüketmek, yok etmek, devretmek

Bu uçların üçünde de Idempotency-Key zorunludur (yoksa 400). If-Match isteğe bağlıdır ve eşya örneğinin version değeridir.

Envanter yerleşimi

Yerleştirme komutları aynı şekli taşır:

POST /v1/inventories/player:0192f0f2-5b1a-7c3e-9d11-4a5b6c7d8e9f/move
Authorization: Bearer crx_live_<önek>_<gizli>
Content-Type: application/json
Idempotency-Key: move-1
If-Match: 4

{ "item_instance_id": "0192f1aa-1111-7222-8333-944455556666", "to_slot": 5 }

Yanıt { "inventory": {…}, "slots": [{ "slot_idx": 5, "item_instance_id": "…", "created_at": "…" }], "event": {…}, "replayed": false } biçimindedir.

Kurallar:

• Dolu yuvaya yerleştirme 422’dir. Yeni bir eşya yerleştirirken kapasite aşımı da 422’dir; yerleşik bir eşyayı taşımak kapasite tüketmez.
• If-Match, envanterin sürümüdür. İlk açılışta (envanter henüz yokken) If-Match gönderirseniz 400 alırsınız.
• Aynı eşya başka bir envanterde yerleşikse 409 (çift yerleşim kilidi).
• split: amount 1 ile kaynak adedinin bir eksiği arasındadır; eşya yığılabilir olmalıdır. Yeni örneğin kimliği yanıttaki olayda (new_instance_id) döner.
• stack: iki yığın da yerleşik olmalı; aynı tanım sürümünde ve boş metadata’lı olmalıdır.
• equip: tanımın metadata’sında equip_condition (CEL ifadesi) varsa kuşanma bu koşula bağlıdır. Koşul ya da değerlendirmesi hata verirse kuşanma reddedilir (422). Koşulda character bağlamı şimdilik boştur, now ve seed sabit 0’dır.

Eşya kataloğu

Oyunun istemcisi eşya tanımını, tipli veri satırlarını ve model adresini katalogdan okur. İki kitle vardır: oyuncu yalnız player görünürlüklü satırları görür; sunucu anahtarı bütün satırları, her satırın görünürlüğüyle ve content_revision ile görür. Yanıtlar ETag taşır; If-None-Match ile değişmediyse 304 döner. Ayrıntı ve izleme örneği: İçerik grupları ve Scene, görsel ve 3B modeller.

Sürümleme ve tekrar güvenliği

• Mint, consume, destroy, transfer ve bütün envanter komutlarında Idempotency-Key zorunludur. Aynı anahtar ve aynı gövde ikinci kez gelirse işlem tekrar çalışmaz; yanıt replayed: true ile döner. Aynı anahtar, farklı gövde 422’dir. Anahtar yalnız başarıda yanar.
• If-Match eşzamanlı yazmayı engeller (uyuşmazlık 409).
• Genel kurallar: Idempotency ve eşzamanlılık.

Olaylar

Eşya olayları (item_instance_created, item_ownership_changed, item_consumed, item_stacks_merged, item_stack_split) kural otomasyonunda ve görev hedeflerinde kullanılabilir. Webhook uç noktasına filtre olarak seçilebilen olay türleri arasında eşya olayı yoktur. Filtresiz (event_types boş) kaydedilmiş bir uç nokta bütün olayları aldığı için eşya olaylarını da alır; bu olayların zarf biçimi belgelenmiş bir sözleşme değildir, ona güvenmeyin. Eşya değişikliğini dışarıya bildirmeniz gerekiyorsa kendi sunucunuzdan okuyun. Seçilebilir türler: Webhook olayları.

Sınırlar

• Liste uçlarında limit 1–200; sayfalama imleçlidir.
• Varsayılan envanter kapasitesi 32 dolu yuvadır.
• quantity, amount ve fiyatlar tam sayıdır; ondalık yoktur.

Sık görülen hatalar

Çalışan örnek

Ham REST ile iksir verip tüketen örnek (SDK’da tipli istemci olmadığı için fetch kullanır):

/** Envanter ve eşya uçları için SDK'da tipli istemci yoktur; ham REST ile çağrılır (sunucu anahtarı). */

/** Küçük yardımcı: Bearer + Idempotency-Key ile JSON POST. */
async function post(baseUrl: string, key: string, path: string, idempotencyKey: string, body: unknown, ifMatch?: number): Promise<unknown> {
  const headers: Record<string, string> = {
    Authorization: `Bearer ${key}`,
    "Content-Type": "application/json",
    "Idempotency-Key": idempotencyKey,
  };
  if (ifMatch !== undefined) headers["If-Match"] = String(ifMatch);
  const response = await fetch(`${baseUrl}${path}`, { method: "POST", headers, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(`${path}: HTTP ${response.status} ${await response.text()}`);
  return response.json();
}

/** Oyuncuya bir iksir verir (mint, yalnız server anahtarı) ve 1 adedini tüketir. */
export async function grantAndDrink(baseUrl: string, serverKey: string, playerId: string): Promise<void> {
  const minted = (await post(baseUrl, serverKey, "/v1/items", `mint-${playerId}-potion-1`, {
    definition_key: "health_potion",
    owner: `player:${playerId}`,
    quantity: 3,
  })) as { instance: { id: string; version: number } };

  await post(
    baseUrl,
    serverKey,
    `/v1/items/${minted.instance.id}/consume`,
    `drink-${minted.instance.id}-1`,
    { amount: 1 },
    minted.instance.version, // If-Match: okuduğunuz sürüm; uyuşmazlık 409
  );
}

İlgili sayfalar

• Ekonomi: cüzdanlar, para birimleri, tüccar ve takas
• Mağaza ve uygulama içi satın alma
• İçerik grupları
• Hatalar

Ekonomi

Bu sayfa oyun içi paranın Open Play’de nasıl tutulduğunu ve hareket ettiğini anlatır: para birimi tanımı, cüzdan, defter (ledger), oyuncular arası transfer, NPC tüccar ve oyuncu takası. Oyuncuya para vermenin, harcatmanın ve ekonomiyi izlemenin güvenli yolunu arıyorsanız okuyun.

Ne işe yarar

Ekonomi iki modüle yayılır:

• economy: para birimleri, cüzdanlar, defter, transfer ve raporlar.
• trading: NPC tüccar (merchants) ve oyuncular arası takas (trades).

Her para hareketi çift kayıtlıdır (double-entry): bir cüzdandan çıkan tutar başka bir cüzdana ya da bir sistem hesabına girer ve ikisi aynı işlem kimliğiyle (tx_id) defterde durur. Defter yalnızca eklenir; hiçbir satır güncellenmez ya da silinmez. Hata düzeltmek için ters kayıt yazılır.

Modül kapalıysa uçlar 404 ve {"code":"module_disabled","module":"economy"} (ya da trading) döner.

Panelde nerede

Veri modeli (düz dille)

• Para birimi (currency): Anahtarı (gold), adı, transferable (oyuncular arası transfer serbest mi), max_supply (toplam arz tavanı; yoksa sınırsız) ve ikonu vardır. Aynı anahtarla yeniden kayıt yeni sürüm üretir; eski sürümler değişmez. Kuruş hanesi (display_decimals) ve ikon görseli panelden ayarlanır; REST kaydı onları 0/boş bırakır.
• Cüzdan (wallet): Bir sahibin bir para birimindeki bakiyesi. Sahip <tür>:<uuid> biçimindedir (player, character, clan, system). Cüzdan yazma ucu yoktur; cüzdan ilk hareketle kendiliğinden doğar ve doğduğu para birimi sürümüne bağlanır.
• Bakiye: En küçük birimde tam sayı (i64). Ondalık sayı yoktur: “12,50 altın” gösterimi için panelde ayarlanan kuruş hanesini istemcide uygulayın.
• Defter satırı: direction (giriş/çıkış), amount, reason (transfer, grant, burn, merchant_purchase, merchant_sale, iap, iap_revoke, party_reward, clan_treasury, quest, login, npc_reward, reward_table, trade_lock, trade_refund, trade_settle …) ve reference (bağlam).
• Tüccar (merchant): Anahtarı, adı ve eşya başına alış/satış fiyat geçersiz kılmaları (price_overrides) olan NPC. Eşyanın kendi npc_buy_price/npc_sell_price değeri varsayılandır.
• Takas (trade): İki oyuncu arasında durum makinesi: draft → offered → locked → completed ya da cancelled/expired.

Oyuncuya para nasıl verilir

Doğrudan “cüzdana şu kadar ekle” REST ucu yoktur. Para şu yollarla oyuncuya girer:

Her biri defterde kendi reason değeriyle görünür.

Oyunun yaptığı çağrılar

Uçlar Authorization: Bearer crx_live_<önek>_<gizli> ile çağrılır. Para birimi ve tüccar yönetimi sunucu anahtarı ister (403); okuma ve oyuncu işlemleri herhangi bir API anahtarıyla yapılabilir.

Not

TypeScript SDK’sında bu modüller için tipli istemci yoktur; ham REST ile çağrılır. Bkz. TypeScript SDK.

Uyarı

Bilinen kısıt: Transfer, tüccar alım/satımı ve takas uçları anahtar türüne bakmaz; geçerli bir istemci anahtarı da çağırabilir ve cüzdan/oyuncu kimliği istekte serbestçe verilir. İstemci anahtarı ortam kapsamlıdır, oyuncu kapsamlı değildir. Para hareketlerini yalnız kendi oyun sunucunuzdan yapın ve oyuncudan gelen kimliği orada doğrulayın.

Para birimi kaydı

POST /v1/currencies
Authorization: Bearer crx_live_<önek>_<gizli>
Content-Type: application/json

{ "key": "gold", "name": "Altın", "transferable": true, "max_supply": 1000000000 }

{ "id": "0192f0aa-1000-7000-8000-000000000001", "key": "gold", "version": 1, "name": "Altın", "transferable": true, "max_supply": 1000000000, "icon": null }

key ve name boş olamaz; max_supply verilirse 0’dan büyük olmalıdır (400). transferable: false olan para birimi oyuncular arası transferde 422 döner (oyun içi harcamalar yine çalışır).

Transfer

POST /v1/transfers
Authorization: Bearer crx_live_<önek>_<gizli>
Content-Type: application/json
Idempotency-Key: transfer-2026-11-03-0001

{ "from_wallet": "0192f1…", "to_wallet": "0192f2…", "amount": 500, "reference": { "neden": "hediye" } }

{ "tx_id": "0192f3…", "from": { "id": "0192f1…", "balance": 1500, "version": 7 }, "to": { "id": "0192f2…", "balance": 500, "version": 3 }, "replayed": false }

(Yanıttaki from ve to cüzdan kayıtlarının tam alanları yer alır; yukarıda kısaltılmıştır.) Reddedilen durumlar: tutar 0 ya da eksi 400; para birimleri farklı 400; cüzdan yok 404; yetersiz bakiye, transferable: false ya da aynı anahtar farklı gövde 422; aynı anahtar uçuşta 409.

Tüccar alım ve satımı

POST /v1/merchants/blacksmith/buy
Authorization: Bearer crx_live_<önek>_<gizli>
Content-Type: application/json
Idempotency-Key: buy-oyuncu-1234-17

{ "player_id": "0192f0f2-…", "item_key": "iron_sword", "currency_key": "gold", "quantity": 1 }

Yanıt: { "event": {…}, "wallet_balance": 900, "wallet_version": 8, "inventory_id": "…", "inventory_version": 5, "replayed": false }.

Alım tek işlemde cüzdandan düşer, eşyayı yeni örnek olarak üretir, ilk boş yuvaya yerleştirir ve stoğu azaltır. Fiyat tanımsızsa, bakiye yetersizse ya da envanter doluysa 422; stok yetersizse 409. Satışta (sell) gövde { "player_id", "item_instance_id", "currency_key" } taşır ve yığının tamamı satılır; kısmi satış için önce split uygulayın. Her ikisinde Idempotency-Key zorunludur.

Oyuncu takası

1. POST /v1/trades — { "initiator_player_id", "counterparty_player_id", "ttl_ms" } ile taslak açın (ttl_ms > 0; süre dolunca takas expired olur).
2. İki taraf da POST /v1/trades/{id}/offer ile bacaklarını kilitler: { "actor_id", "legs": [ {"type":"item","item_instance_id":"…"}, {"type":"currency","currency_id":"…","amount":100} ] }. Eşya yerleşik, takas edilebilir ve başka bir takasta kilitli olmamalıdır (kilitliyse 409); para escrow’ya (emanet hesabına) alınır.
3. Her iki taraf kilitleyince takas locked olur. POST /v1/trades/{id}/accept ({ "actor_id" }) yalnız başlatan oyuncuyla çalışır ve tek işlemde bütün bacakları takas eder. Alıcının envanterinde yer yoksa 422 döner ve takas kilitli kalır.
4. POST /v1/trades/{id}/cancel iki taraftan biriyle çağrılabilir; kilitler açılır ve para iade edilir.

Taraf olmayan biri GET /v1/trades/{id} çağırırsa 404 alır (takasın varlığı gizlenir); actor_id sorgu parametresi zorunludur.

Sürümleme ve tekrar güvenliği

• transfers, merchants/{key}/buy|sell, trades komutlarının hepsinde Idempotency-Key zorunludur (yoksa 400). Aynı anahtar ve aynı gövde işlemi tekrarlamaz, replayed: true döner; farklı gövde 422. Anahtar yalnız başarıda yanar.
• Para birimi ve tüccar kaydı her seferinde yeni sürüm yazar; eski sürümler dokunulmazdır.
• Defter okuması imleçlidir (limit 1–200, varsayılan 50).

Raporlar

Rapor uçları (faucet-sink, flags, merchant-gap, top-holders) UTC’de kapanmış günler üzerinden hesaplanır: from ve to dahildir ve en çok 366 gün aralık verilebilir. Eksik günler yanıtta missing_dates olarak listelenir; sıfır sayılmaz. iap_net gerçek para değil oyun parasıdır. flags bir inceleme sinyalidir; otomatik yaptırım uygulanmaz.

Olaylar

Para hareketleri outbox’a olay yazar. Webhook filtresi olarak seçilebilen türler arasında ekonomiye özel bir tür yoktur; filtresiz kayıtlı uç noktalar bütün olayları aldığı için para olaylarını da alır, ancak bu olayların zarf biçimi belgelenmiş bir sözleşme değildir. Mağaza ve ödül olayları seçilebilir türlerdir: Webhook’lar.

Sınırlar

• Bakiye ve tutarlar i64 en küçük birimdir; tutar 0’dan büyük olmalıdır.
• Para birimi max_supply tavanını aşan üretim (ödül, IAP, satış) 422 döner.
• Raporlarda en çok 366 gün.

Sık görülen hatalar

Çalışan örnek: para ver, sonra ürün satın al

Sunucu oyuncuya ödül tablosundan para verir; oyuncu kendi oturumuyla mağazadan ürün alır. İlk adım sunucuda, ikinci adım oyun istemcisinde çalışır. welcome_pack tablosu panelden (Ödül tabloları) ya da POST /v1/reward-tables ile önceden kurulmuş olmalıdır.

/** Ekonomi akışı: sunucu ödül tablosundan para verir, oyuncu kendi oturumuyla mağazadan ürün alır. */
import { CrxClient, StoreBuyErrorCode, storeBuyErrorCode, type PlayerClient } from "@ferdiunal/open-play-ts";

/** 1. adım (güvenilir sunucu): oyuncuya tablodan ödül verir. Aynı `requestKey` ile tekrar ödeme yapmaz. */
export async function grantWelcomeReward(baseUrl: string, serverApiKey: string, playerId: string, requestKey: string): Promise<void> {
  const crx = new CrxClient({ baseUrl, apiKey: serverApiKey });
  const grant = await crx.grantRewardTable("welcome_pack", {
    playerId,
    source: { type: "manual", operatorId: "game-server" },
    idempotencyKey: requestKey,
  });
  // `rewards` verilen birleşik ödüllerdir; `replayed: true` ikinci çağrının aynı sonucu geri verdiği anlamına gelir.
  console.log(grant.rewards, grant.replayed);
}

/** 2. adım (oyun istemcisi): oyuncunun gördüğü ilk ürünü satın alır. */
export async function buyFirstListing(player: PlayerClient, pageKey: string, idempotencyKey: string): Promise<string> {
  const catalog = await player.store.catalog({ page: pageKey });
  const listing = catalog.pages[0]?.listings[0];
  if (listing === undefined || listing.version === null) return "Vitrinde ürün yok.";
  try {
    // Gördüğünüz sürümü geri gönderin: fiyat arada değiştiyse sunucu satmaz (409 listing_changed).
    const result = await player.store.buy(listing.id, { expectedVersion: listing.version, quantity: 1, idempotencyKey });
    return `Satın alındı. Kalan bakiye: ${result.balanceAfter}`;
  } catch (error: unknown) {
    switch (storeBuyErrorCode(error)) {
      case StoreBuyErrorCode.InsufficientFunds: return "Bakiye yetmiyor.";
      case StoreBuyErrorCode.OutOfStock: return "Stok tükendi.";
      case StoreBuyErrorCode.ListingChanged: return "Ürün değişti; mağazayı yenileyin.";
      default: throw error;
    }
  }
}

İlgili sayfalar

• Ödüller · Mağaza ve IAP · Envanter ve eşyalar · Sosyal
• Idempotency ve eşzamanlılık · Sayılar ve kodlama

Mağaza ve uygulama içi satın alma

Bu sayfa oyuncunun gördüğü mağaza vitrinini, oyun parasıyla satın alma akışını ve gerçek parayla yapılan uygulama içi satın almanın (IAP, in-app purchase) doğrulanmasını anlatır. Vitrin oluşturmak, ürün satmak ve ödemeyi sunucuda güvenle tamamlamak istiyorsanız okuyun.

Ne işe yarar

Mağaza modülü (store) üç şeyi birbirine bağlar:

• Vitrin (page) ve ürün (listing): Operatörün panelden kurduğu, oyuncuya gösterilen katalog.
• Ödeme: Ürün ya oyun parasıyla (currency: bir tüccar üzerinden, eşya karşılığı para) ya da gerçek parayla (iap: App Store ya da Google Play makbuzu) satılır.
• Rezervasyon: Satın alma önce bir hak ayırır (stok ve oyuncu limiti), sonra ödemeyi tek işlemde tamamlar. Ödeme ve teslimat birlikte ya olur ya hiç olmaz.

Modül kapalıysa uçlar 404 ve {"code":"module_disabled","module":"store"} döner. Modülü Oyun ayarları › Modüller sayfasından açın.

Panelde nerede

Panelde IAP ürünleri ve makbuzları yalnız listelenir. Mağazaya IAP ürünü bağlamak ve platform kimlik bilgileri (App Store / Google Play) için bkz. Sınırlar.

Veri modeli (düz dille)

• Vitrin (page): key (küçük harf, rakam, _, -; en çok 64), title, sort_order ve görünürlük. Açıklama, afiş görseli, ürün başlığı, rozet ve görsel gibi vitrin alanları panelden girilir; sunucu anahtarlı REST taslağı bunları taşımaz.
• Ürün (listing): Bir vitrine bağlıdır. Ödeme biçimi currency (tüccar + eşya tanımı + para birimi + price_amount) ya da iap (IAP ürün kimliği) olur. limit_per_player (en az 1) ömür boyu oyuncu başına adet sınırıdır.
• Görünürlük: active, tarih penceresi (starts_at/ends_at, Unix ms) ve isteğe bağlı bir CEL visibility_rule (oyuncuya özgü koşul; kayıtta derlenir, en çok 8192 bayt). Oyuncu vitrinini her okumada yeniden hesaplanır: koşul, saat ve kalan limit o anki duruma göre değerlendirilir.
• Katalog sürümü (version): Vitrinde yapılan her değişiklik katalog sürümünü artırır; yönetim komutlarında If-Match bu sürümdür.
• Ürün sürümü: Oyuncunun gördüğü ürünün version alanı; satın almada expected_version olarak geri gönderilir.
• Rezervasyon: Durumu reserved, processing, completed, cancelled. reserved ve processing ödeme sayılmaz.
• Fiyat: En küçük birimde tam sayı; vitrinde display_decimals (0–4) ile birlikte gelir. Gösterimi tamsayı/dize işlemiyle kurun, ondalık sayıya çevirmeyin.

Oyunun yaptığı çağrılar

İki kimlik türü vardır:

• Oyuncu oturumu (çerez ya da oturum belirteci + x-crx-env: <ortam uuid>): vitrini okur ve kendi adına satın alır. Çerezli oturumda mutasyonlar CSRF çift gönderimi (x-csrf-token) ve Origin denetimi ister; bkz. Oturumlar ve CSRF.
• Sunucu anahtarı (Authorization: Bearer crx_live_<önek>_<gizli>): katalog yönetimi, oyuncu önizlemesi, rezervasyon ve ödeme tamamlama.

Hata zarfları: yönetim ve rezervasyon uçlarının hataları text/plain’dir; oyuncu satın alma ucu tipli code taşıyan JSON döner (aşağıda). Genel liste: Hatalar.

Vitrini okumak

GET /v1/store/pages?page=garaj
x-crx-env: 0192f000-0000-7000-8000-00000000e001

{
  "version": 12,
  "pages": [
    {
      "id": "…", "key": "garaj", "title": "Garaj",
      "listings": [
        {
          "id": "0192f111-…", "version": 3,
          "title": "Hızlı Araba", "badge": "sale",
          "price": { "currency_key": "gold", "currency_name": "Altın", "amount": 1250, "display_decimals": 0, "icon_url": null },
          "item": { "key": "fast_car", "name": "Hızlı Araba" },
          "remaining": 40
        }
      ]
    }
  ]
}

Yanıt Cache-Control: private, no-store taşır. Görünmeyen ya da bilinmeyen page anahtarı 404 döner. Oyuncu kimliği, saat ve CEL sonucu istemciden alınmaz; sorguya player_id ya da başka bir alan eklemek 400 döner.

Oyuncunun satın alması

POST /v1/player/store/listings/0192f111-…/buy
x-crx-env: 0192f000-0000-7000-8000-00000000e001
x-csrf-token: <csrf>
Idempotency-Key: buy-oyuncu-1234-0001
Content-Type: application/json

{ "quantity": 1, "expected_version": 3 }

{
  "reservation_id": "…",
  "payment_reference": "…",
  "item_instance_ids": ["…"],
  "balance_after": 750,
  "replayed": false
}

Gövdede yalnız quantity (pozitif) ve expected_version bulunur; oyuncu kimliği, fiyat ya da ödeme iddiası kabul edilmez ve bilinmeyen alan 400 döner. Kimlik oturumdan gelir. Rezervasyon ve tahsilat tek işlemdedir. Idempotency-Key zorunludur: aynı anahtar ve aynı gövde kalıcı sonucu replayed: true ile tekrar eder ve ikinci tahsilat yapmaz; aynı anahtarla farklı gövde 422’dir. IAP ürünü bu uçta alınamaz (422).

Reddedilen satın almalar tipli JSON kod taşır, {"code": "...", "message": "..."}:

Diğer hatalar (401, 403 CSRF/Origin, 400, 429 bütçe, 500) genel kurallara tabidir.

Sunucu tarafı akış: rezervasyon ve ödeme

Ödemeyi oyun sunucusunun yönettiği durumlarda (örneğin gerçek para makbuzunu sizin sunucunuz alıyorsa) iki adım kullanın:

POST /v1/store/listings/{listing_id}/reserve
Authorization: Bearer crx_live_<önek>_<gizli>
Idempotency-Key: reserve-oyuncu-1234-0001
If-Match: 12
Content-Type: application/json

{ "player_id": "0192f0f2-…", "quantity": 1 }

Yanıt { catalog_version, entity_id, event_id, event, reservation, replayed } biçimindedir; reservation.status reserved’dır. Ardından:

POST /v1/store/reservations/{id}/checkout/currency
Authorization: Bearer crx_live_<önek>_<gizli>
Content-Type: application/json

{ "player_id": "0192f0f2-…" }

{ "reservation_id": "…", "payment_reference": "…", "kind": "currency", "replayed": false }

checkout uçlarında Idempotency-Key ve If-Match gönderilmez (gönderilirse 400); kalıcı rezervasyon kimliği tekrar güvenliğinin çapasıdır. Para birimiyle ödemede hata olursa işlem geri alınır ve rezervasyon reserved kalır; yeniden deneyebilir ya da iptal edebilirsiniz. IAP ödemesinde sonuç belirsizse rezervasyon processing olur ve oyuncu limiti korunur; aynı credential ile yeniden deneyin. IAP ödemesinde quantity 1’dir.

reserve ve katalog yönetim komutlarında Idempotency-Key zorunludur; If-Match katalog sürümüdür ve isteğe bağlıdır (uyuşmazlık 409). Başarısız komut anahtarı yakmaz.

IAP doğrulaması

POST /v1/iap/verify
Authorization: Bearer crx_live_<önek>_<gizli>
Idempotency-Key: iap-oyuncu-1234-tx-abc
Content-Type: application/json

{ "platform": "app_store", "product_sku": "gems_500", "credential": "<transactionId>", "player_id": "0192f0f2-…" }

{ "receipt_id": "…", "status": "granted", "product_sku": "gems_500", "transaction_id": "…", "grants": [ … ], "replayed": false }

• platform: app_store ya da google_play. credential: App Store için transactionId, Google Play için purchaseToken. Sunucu platformu kendisi sorgular; istemciye güvenilmez.
• Aynı işlemi iki kez doğrulamak ikinci ödül vermez (200, replayed: true).
• status verified, granted, revoked ya da failed olabilir; mutlu yol granted’dır.
• Hatalar: sahte makbuz 403; ürün katalogda yok ya da işlem platformda tanınmıyor 404; product_sku uyuşmazlığı, platform yapılandırılmamış ya da arz tavanı aşımı 422; aynı anahtarla uçuşta başka istek 409.
• İade bildirimi: App Store (ASN V2) ve Google Play (RTDN) bildirimleri POST /v1/webhooks/iap/{platform}/{environment_id} adresine gelir; uç anahtarsızdır, kimlik doğrulaması imzadır. Bilinen bir makbuzun iadesinde ödül ters kayıtlarla geri alınır ve makbuz revoked olur; kısmen geri alınabilen durumlar flagged olarak işaretlenir (varsayılan politika, tüketilmiş kısma dokunmaz). İade dışı bildirimler ve bilinmeyen işlemler 200 alır, yok sayılır.

Sürümleme ve tekrar güvenliği

• Oyuncu satın alma: expected_version (ürün sürümü) + Idempotency-Key.
• Katalog yönetimi ve rezervasyon: Idempotency-Key zorunlu, If-Match = katalog sürümü.
• Ödeme tamamlama: kalıcı rezervasyon kimliği; başlık yok.
• Genel kurallar: Idempotency ve eşzamanlılık.

Olaylar ve webhook’lar

Mağaza olayları webhook olarak gönderilebilir: store_page_created, store_page_updated, store_page_deleted, store_pages_reordered, store_listing_created, store_listing_updated, store_listing_deleted, store_listings_reordered, store_purchase_initiated, store_payment_started, store_purchase_completed, store_reservation_cancelled. Zarfta event_id, environment_id, type, seq, now_ms, actor_api_key_id ve data bulunur. Kayıt ve doğrulama: Webhook’lar.

Sınırlar ve bilinen kısıtlar

• Vitrin anahtarı ^[a-z0-9_-]{1,64}$; sıralama isteğinde en çok 2000 giriş.
• Oyuncu satın alma ucunda IAP ürünü desteklenmez; IAP ürünleri checkout/iap ya da iap/verify ile alınır.
• IAP ürün kaydı: Panelde IAP ürünleri ve makbuzları salt okunurdur ve ürün kaydetmek için herkese açık bir HTTP ucu henüz yoktur. IAP ürünü eklenmesi şimdilik Open Play operatörü üzerinden yapılır.
• Platform kimlik bilgileri: App Store ve Google Play doğrulama kimlik bilgileri dağıtımda operatör tarafından tanımlanır. Tanımlı değilse iap/verify ve checkout/iap 422 döner.
• Vitrini oyuncu açtığında ya da yenilediğinde okuyun; değişiklikler okuma anında yeniden hesaplanır.

Sık görülen hatalar

Çalışan örnek

Vitrini okuyup ilk ürünü satın alma örneği Ekonomi sayfasında; hata kodlarına göre ayrı mesaj gösterir (storeBuyErrorCode). TypeScript SDK’sı player.store.catalog() ve player.store.buy() yardımcılarını sağlar; Idempotency-Key verilmezse çağrı başına üretir, ağ kesintisinden sonra aynı anahtarı kendiniz vermelisiniz.

İlgili sayfalar

• Ekonomi · Envanter ve eşyalar · Ödüller · Webhook’lar
• TypeScript SDK · Oturumlar ve CSRF

Ödüller

Bu sayfa oyunun oyuncuya verdiği ödüllerin Open Play’de nasıl tanımlandığını ve verildiğini anlatır: şansa bağlı ödül tabloları, günlük giriş ödülü, görevler, NPC ödülleri ve VIP kartları. Ödülün sunucuda, hile yapılamadan ve tek seferlik verilmesini istiyorsanız okuyun.

Ne işe yarar

Ödül modülü (rewards) “oyuncuya para ya da eşya ver” işini tek bir güvenilir hat üzerinden yapar. Her ödül verme işlemi tek bir veritabanı işlemidir: para cüzdana yazılır, eşya envantere konur ve olay kaydedilir. Envanter doluysa ya da para birimi arz tavanını aşarsa hiçbir şey verilmez (422).

Tablolu ödüller belirlenimcidir (deterministic): aynı tohum aynı sonucu verir. Tohum sunucuda tutulur; yanıtta, webhook olayında ve defter kaydında görünmez.

Modül kapalıysa uçlar 404 ve {"code":"module_disabled","module":"rewards"} döner. Modülü Oyun ayarları › Modüller sayfasından açın.

Panelde nerede

Veri modeli (düz dille)

• Ödül tablosu: key, name, rolls (kaç kez çekiliş yapılacağı, 1–10), entries (satırlar) ve guaranteed (her seferinde verilen ödüller). Her kayıt yeni bir sürüm olur; grant sırasında güncel sürüm kullanılır ve sonuçta sürüm numarası döner.
• Satır (entry): chance_bp (baz puan, 1–10000) ve drop. Bir çekilişin satır şansları toplamı tam 10000 (%100) olmalıdır; “ödül yok” bir satır olabilir.
• Ödül (drop): currency (key, min, max), item (key, min, max) ya da nothing. Adet her zaman min ile max arasından eşit dağılımla seçilir; adetler 1 ile 1.000.000 arasındadır. Tabloda en çok 50 satır, 10 garanti ödül bulunur.
• Garanti ödül: Çekilişten bağımsız verilir; nothing olamaz.
• Kaynak (source): Ödülün neden verildiğini tipli olarak yazar: content_entry, tournament, leaderboard_season, quest, npc_reward, rule ya da manual.

Oyunun yaptığı çağrılar

Tüm ödül uçları sunucu anahtarıyla (ya da yönetici türünde bir anahtarla) çağrılır; istemci anahtarı ve oyuncu oturumu reddedilir. Oyuncu kimliği güvenilir sunucu bileşeninin gövdesinde taşınır:

Authorization: Bearer crx_live_<önek>_<gizli>

Not

TypeScript SDK’sında yalnız ödül tablosu için tipli istemci vardır (CrxClient.createRewardTable, getRewardTable, grantRewardTable). Giriş ödülü, görev, NPC ve VIP uçları ham REST ile çağrılır. Bkz. TypeScript SDK.

Ödül tablosu kaydetmek

POST /v1/reward-tables
Authorization: Bearer crx_live_<önek>_<gizli>
Content-Type: application/json

{
  "key": "welcome_pack",
  "name": "Hoş geldin paketi",
  "rolls": 1,
  "entries": [
    { "chance_bp": 7000, "drop": { "type": "currency", "key": "gold", "min": 100, "max": 300 } },
    { "chance_bp": 2500, "drop": { "type": "item", "key": "health_potion", "min": 1, "max": 3 } },
    { "chance_bp": 500,  "drop": { "type": "nothing" } }
  ],
  "guaranteed": [ { "type": "currency", "key": "gold", "min": 50, "max": 50 } ]
}

Yanıt 201 ve { id, version, key, name, rolls, entries, guaranteed, created_at_ms } döner; çekiliş tohumu hiçbir yanıtta bulunmaz. Şans toplamı 10000 değilse, tablo boşsa ya da sınırlar aşılıyorsa kayıt 422 ve düz metin iletiyle reddedilir. validate anahtarı ayrılmıştır, tablo anahtarı olarak kullanılamaz.

Tablodan ödül vermek

POST /v1/reward-tables/welcome_pack/grant
Authorization: Bearer crx_live_<önek>_<gizli>
Idempotency-Key: welcome-oyuncu-1234
Content-Type: application/json

{ "player_id": "0192f0f2-5b1a-7c3e-9d11-4a5b6c7d8e9f", "source": { "type": "manual", "operator_id": "game-server" } }

{
  "grant_id": "…", "tx_id": "…", "event_id": "…",
  "table_key": "welcome_pack", "table_version": 1,
  "rewards": [ { "drop": "currency", "key": "gold", "quantity": 250 }, { "drop": "item", "key": "health_potion", "quantity": 2 } ],
  "replayed": false
}

Idempotency-Key zorunludur. Aynı anahtar ve aynı gövde ödülü ikinci kez vermez; ilk sonuç replayed: true ile döner. Aynı anahtar farklı gövdeyle 422’dir. source değişkenleri:

Para ve eşya tek işlemde verilir: envanter doluysa ya da para birimi arz tavanı aşılırsa bütün verme geri alınır ve 422 döner. Oyuncuya bağlı olmayan bir karakter için NPC ödülü verilemez.

Günlük giriş ödülü

GET /v1/login-rewards/{player_id} bugünün durumunu verir: period_date, claimed, streak_day, current_streak, config_version. POST /v1/login-rewards/{player_id}/claim ödülü verir ve { period_date, streak_day, rewards, event_id, tx_id, replayed } döner; aynı gün ikinci çağrı aynı makbuzu replayed: true ile geri verir, ikinci ödül vermez.

Gün, ortamın saat dilimine (timezone, Ortamlar ve alan adları) göre hesaplanır. Ödül çizelgesi (gün sayısı, her günün para ödülü) ve kaçırılan gün politikası (reset_on_miss: seri 1’e döner; freeze: seri korunur) sürümlü bir yapılandırmadır.

Not

Giriş ödülü yapılandırmasını (çizelge ve seri politikası) yazan herkese açık bir uç ya da panel ekranı henüz yoktur; yapılandırma şimdilik Open Play operatörü tarafından kurulur.

Görevler

POST /v1/quests görev tanımını yeni sürüm olarak kaydeder:

{
  "key": "kill_10_wolves",
  "name": "On kurt avla",
  "objectives": [ { "key": "wolves", "event_type": "event_emitted", "count": 10, "filter_cel": "event.event_key == \"wolf_killed\"" } ],
  "rewards": [ { "type": "currency", "key": "gold", "amount": 500 }, { "type": "table", "key": "welcome_pack" } ],
  "recurrence": "daily"
}

• objectives[].event_type: görevi ilerleten olay türü (karakter olayları, score_submitted, login, eşya ve para olayları gibi); count kaç kez gerektiği; filter_cel isteğe bağlı koşul.
• rewards[].type: currency (key, amount) ya da table (ödül tablosu anahtarı).
• recurrence: none, daily, weekly. window ve prerequisite_cel (kayıt anında derlenir) isteğe bağlıdır.
• POST /v1/quests/{key}/claim gövdesi { "player_id": "…", "period_key": "…" }’dir (period_key en çok 160 karakter). Yanıt { status: "claimed" | "already_claimed", reward_count, event_id } — aynı dönemi ikinci kez almak already_claimed döner, ödül tekrarlanmaz.
• GET /v1/quests search, limit, offset ile listeler (sayfa içi total döner).

Not

Görev ilerlemesini (oyuncunun hangi görevde kaçta olduğunu) okuyan herkese açık bir REST ucu henüz yoktur. İlerleme olaylardan sunucuda hesaplanır; period_key değerini bu nedenle oyun sunucunuzun kendisi bilmelidir.

NPC ödülleri

GET /v1/npc-rewards/{key}/eligibility?character_id=…&period_key=… yazmadan uygunluğu söyler: { eligible, reason } (reason: cooldown, daily_limit, condition). POST /v1/npc-rewards/{key}/claim (Idempotency-Key zorunlu, gövde { "character_id", "period_key" }) ya ödülü verir ya da rejected döner: { status: "claimed" | "rejected", reward_count, claim_count, tx_id, reason }. NPC kuralını (bekleme, günlük sınır, CEL koşulu, ödül) kaydeden herkese açık bir uç henüz yoktur.

VIP

VIP katmanı kümülatif puandan türetilir. GET /v1/vip/{player_id} { player_id, cumulative_points, tier, config_version } verir. POST /v1/vip/{player_id}/cards/{item_instance_id}/use (Idempotency-Key zorunlu) bir vip_card eşyasını tüketir ve puan ekler; kart bir üst katman koşulunu (mevcut katman + 1) karşılamıyorsa 422 döner. İstemci ve sunucu anahtarı aynı VIP yüzeyini kullanabilir.

Sürümleme ve tekrar güvenliği

• Tablo grant, NPC claim ve VIP kart kullanımı: Idempotency-Key zorunlu.
• Giriş ödülü: aynı gün ikinci claim aynı makbuzu döner; başlık gerekmez.
• Görev claim: dönem anahtarı doğal tekrar güvenliğidir (already_claimed).
• Tablo ve görev kayıtları her seferinde yeni sürümdür; eski sürümler değişmez.
• Genel kurallar: Idempotency ve eşzamanlılık.

Olaylar ve webhook’lar

Tablodan veya sabit para ile verilen her ödül reward_granted olayı üretir ve webhook olarak gönderilebilir. Zarfta event_id, environment_id, player_id, type ve data (source_kind, table_key, table_version ve verilenler) bulunur; tohum yoktur. Kayıt ve doğrulama: Webhook’lar.

Sınırlar

• Tabloda en çok 50 satır, 10 garanti ödül, 10 çekiliş (rolls); adetler 1–1.000.000.
• chance_bp toplamı tam 10000.
• Görev period_key ve claim alanları en çok 160 karakter.

Sık görülen hatalar

Çalışan örnek

Hoş geldin tablosundan para verme ve ardından mağazadan alma akışı Ekonomi sayfasındadır. TypeScript’te crx.grantRewardTable("welcome_pack", { playerId, source, idempotencyKey }) çağrısı aynı uca gider; idempotencyKey verilmezse SDK çağrı başına üretir, ağ tekrarında aynı anahtarı kendiniz vermelisiniz.

İlgili sayfalar

• Ekonomi · Envanter ve eşyalar · Karakterler · Oyun kuralları
• Hatalar · Webhook’lar

Klanlar ve partiler

Bu sayfa kalıcı oyuncu topluluklarını (klan) ve geçici takımları (parti) Open Play’de nasıl kuracağınızı ve yöneteceğinizi anlatır. Üyelik, davet, klan hazinesi, klan XP’si ve parti ödül dağıtımını güvenilir bir sunucudan yönetmek istiyorsanız okuyun.

Ne işe yarar

Sosyal modül (social) iki yapıyı yönetir:

• Klan (clan): Kalıcı topluluk. Lider, subay ve üye rolleri, davet ve başvuru akışı, ortak hazine (para birimi) ve XP/seviye vardır.
• Parti (party): Geçici takım. Kapasitesi, ganimet kuralı ve ödül bölüştürmesi vardır; dağılınca sona erer.

Önemli: Bu uçların hepsi sunucu anahtarıyla çağrılır. Oyuncu istemcisi doğrudan klan ya da parti ucunu çağıramaz; oyuncunun kimliği isteğin gövdesinde (actor_player_id gibi) sizin güvenilir sunucunuz tarafından yazılır. Oyuncunun “kendi klanını yönetebildiğini” doğrulamak sizin sunucunuzun işidir; Open Play klan içindeki rol kurallarını (kimin kimi atabileceği, hazineden kimin çekebileceği) uygular.

Modül kapalıysa uçlar 404 ve {"code":"module_disabled","module":"social"} döner. Modülü Oyun ayarları › Modüller sayfasından açın.

Panelde nerede

Veri modeli (düz dille)

Klan

• name (3–64 karakter), tag (2–8 karakter), leader_player_id, xp, highest_level_reached, state (active ya da disbanded) ve members.
• Roller: leader, officer, member.
• Ortam ayarları (/v1/clan-settings): max_members (üye sınırı), request_ttl_seconds (davet ve başvuru ömrü), officer_can_withdraw (subay hazineden çekebilir mi) ve level_curve_key (klan seviyesi için seviye eğrisi).
• Davet (invite): Klanın oyuncuya gönderdiği çağrı. Durumları pending, accepted, declined, revoked, expired.
• Başvuru (application): Oyuncunun klana başvurusu. Durumları pending, accepted, rejected, cancelled, expired.
• Hazine: Klanın cüzdanı; deposit ve withdraw ile para birimi hareketi yapılır ve defterde clan_treasury olarak görünür.

Parti

• leader_player_id, capacity (pozitif), loot_rule (equal: eşit pay, weighted: baz puan payları), state (active, disbanded) ve members.
• Davet: share_bp (üyenin baz puan payı; weighted kuralda payların toplamı tam 10000 olmalıdır) taşır ve 24 saat geçerlidir. Durumları pending, accepted, expired.
• Ödül dağıtımı: Tek bir para birimi tutarını üyelere böler. Eşit dağıtımda artık kuruşlar player_id sırasına göre dağıtılır; sonuç her zaman belirlenimcidir. Dağıtım kaydı üye anlık görüntüsünü, bacakları, delivery_mode (inline ya da outbox) ve durumu (processing, queued, completed) taşır.

Oyunun yaptığı çağrılar

Hepsi sunucu (ya da yönetici) anahtarıyla:

Authorization: Bearer crx_live_<önek>_<gizli>

İstemci anahtarı ve oyuncu oturumu reddedilir (403).

Klan

Klan yazma komutlarının hepsinde Idempotency-Key zorunludur. Yanıt hep aynı zarftadır: { "type": "clan" | "invite" | "application" | "settings" | "treasury" | "xp", "<tür>": { … }, "replayed": false }. Örneğin klan kurma:

POST /v1/clans
Authorization: Bearer crx_live_<önek>_<gizli>
Idempotency-Key: clan-kur-oyuncu-1234
Content-Type: application/json

{ "leader_player_id": "0192f0f2-5b1a-7c3e-9d11-4a5b6c7d8e9f", "name": "Kurt Sürüsü", "tag": "KRT" }

201 döner ve type: "clan" zarfı içinde klan kaydı gelir. TypeScript SDK’sı bu uçları tipli olarak sunar (createClan, getClan, createClanInvite, respondClanInvite, depositClanTreasury, addClanXp …); bkz. TypeScript SDK.

Parti

Parti ödül dağıtımında Idempotency-Key zorunludur; aynı anahtarla tekrar aynı dağıtımı replayed: true ile döndürür, ikinci dağıtım yapmaz. Diğer parti komutları Idempotency-Key istemez.

Not

TypeScript SDK’sında parti uçları için tipli istemci yoktur; ham REST ile çağrılır.

Sürümleme ve tekrar güvenliği

• Klan komutları ve parti ödül dağıtımı Idempotency-Key ister: aynı anahtar ve aynı gövde tekrar çalışmaz (replayed: true); aynı anahtar farklı gövde 422; uçuşta aynı anahtar 409.
• If-Match bu modülde kullanılmaz.
• Genel kurallar: Idempotency ve eşzamanlılık.

Olaylar

Klan ve parti olayları (ClanMemberJoined, ClanXpAdded, PartyMemberJoined, RewardDistributed …) kural otomasyonunda ve görev hedeflerinde kullanılabilir. Webhook filtresi olarak seçilebilen türler arasında klan ya da parti olayı yoktur; filtresiz kayıtlı uç noktalar bütün olayları alır ve bunlara klan/parti olayları dahildir, ancak zarf biçimi belgelenmiş bir sözleşme değildir. Seçilebilir türler: Webhook olayları.

Sınırlar

• Klan adı 3–64, etiketi 2–8 karakter.
• Parti kapasitesi pozitif olmalı; kapasite aşımı reddedilir. Parti daveti 24 saat geçerlidir.
• Klan üye sınırı ve davet/başvuru ömrü ortam ayarlarındadır.
• Parti ödülünde weighted payların toplamı 10000 olmalıdır; amount pozitif olmalıdır.

Sık görülen hatalar

Çalışan örnek

TypeScript’te klan kurup davet gönderme (SDK’nın tipli klan istemcisiyle):

/** Güvenilir backend örneği: klan kurar ve bir oyuncuya davet gönderir. Server anahtarı yalnız sunucuda durur. */
import { CrxClient } from "@ferdiunal/open-play-ts";

/** Lider için klan kurar, ardından davet gönderir; her yazma kendi `Idempotency-Key`'iyle tekrar güvenlidir. */
export async function foundClanAndInvite(baseUrl: string, serverApiKey: string, leaderId: string, friendId: string): Promise<string> {
  const crx = new CrxClient({ baseUrl, apiKey: serverApiKey });
  const created = await crx.createClan({
    body: { leader_player_id: leaderId, name: "Kurt Sürüsü", tag: "KRT" },
    headers: { "Idempotency-Key": `clan-kur-${leaderId}` },
  });
  if (created.type !== "clan") throw new Error("Beklenmeyen yanıt zarfı");
  await crx.createClanInvite({
    path: { clan_id: created.clan.id },
    body: { inviter_player_id: leaderId, invitee_player_id: friendId },
    headers: { "Idempotency-Key": `davet-${created.clan.id}-${friendId}` },
  });
  return created.clan.id;
}

İlgili sayfalar

• Sohbet · Ekonomi · Karakterler · Oyun kuralları
• TypeScript SDK · Hatalar

Sohbet

Bu sayfa oyuncuların birbirine yazdığı kanal sohbetini (global, dünya, klan, parti ve birebir) anlatır. Oyuncu oturumuyla mesaj göndermek, geçmişi okumak ve canlı mesaj almak istiyorsanız okuyun.

Ne işe yarar

Sohbet modülü (chat) kanal tabanlı metin sohbeti sağlar. Mesajlar kalıcı arşive yazılır; canlı dağıtım ayrıca WebSocket ile yapılır. Aynı mesaj hem REST hem WebSocket üzerinden gönderilebilir ve ikisi de aynı kuralları (susturma, hız sınırı, küfür süzgeci, tekrar koruması) uygular.

Oyuncunun kendi oturumuyla çalışır. API anahtarıyla sohbet uçları çağrılamaz.

Modül kapalıysa uçlar 404 ve {"code":"module_disabled","module":"chat"} döner; sohbet soketi ise önce bir error çerçevesi (code: "module_disabled") gönderip kapanır. Modülü Oyun ayarları › Modüller sayfasından açın.

Panelde nerede

Not

Panelin “Şehir sohbeti” ekranı sahne eklentisinin sohbetini yönetir; bu sayfadaki kanal sohbeti için panelde mesaj okuma, silme ya da susturma ekranı henüz yoktur.

Veri modeli (düz dille)

• Kanal (channel): kind ile ayrılır:

  kind	reference_id	Kim girebilir
  global	yok	Ortamdaki herkes
  world	gerekli (dünya/harita UUID’si)	Referansı bilen oyuncular
  clan	gerekli (klan UUID’si)	Klanın üyeleri
  party	gerekli (parti UUID’si)	Partinin üyeleri
  direct	yok; direct_player_id gerekli	Yalnız iki oyuncu

  Aynı türde ve aynı referansta kanal bir kez kurulur; yeniden istemek var olan kanalı döndürür. direct kanalda diğer oyuncu kendiniz olamaz.

• Mesaj: id, channel_id, sender_player_id, client_message_id, body, sent_at_ms.

• client_message_id: İstemcinin ürettiği tekrar anahtarı (boş olamaz, en çok 200 karakter). Aynı kanalda aynı değerle ikinci gönderim yeni mesaj üretmez; var olan mesajı duplicate: true ile geri döner.

• Susturma: Oyuncunun all, global, world, clan, party ya da direct kapsamında susturulması. Susturulmuş oyuncunun gönderimi 403 döner.

Oyunun yaptığı çağrılar

Bütün sohbet uçları oyuncu oturumuyla çağrılır: oturum çerezi ya da opak oturum belirteci (Authorization: Bearer <oturum belirteci>) ve ortam başlığı:

x-crx-env: <ortam uuid>

Bu uçlarda x-csrf-token çift gönderimi ve Origin denetimi uygulanmaz; oturum çerezi ya da oturum belirteci yeterlidir (mağaza satın alma ucundan farklı olarak). Oturum kuralları: Oturumlar ve CSRF.

Not

TypeScript ve Unity SDK’larında sohbet için hazır istemci yoktur; uçlar ham REST ve WebSocket ile çağrılır. Bkz. TypeScript SDK.

Kanal kurmak

POST /v1/chat/channels
x-crx-env: <ortam uuid>
Content-Type: application/json

{ "kind": "clan", "reference_id": "0192f0aa-…" }

{ "channel": { "id": "0192f2bb-…", "environment_id": "…", "kind": "clan", "reference_id": "0192f0aa-…", "participant_a": null, "participant_b": null, "created_at_ms": 1790000000000 } }

Klan ya da parti üyesi olmayan oyuncunun o kanalı kurması ya da okuması reddedilir.

Mesaj göndermek

POST /v1/chat/channels/0192f2bb-…/messages
x-crx-env: <ortam uuid>
Content-Type: application/json

{ "client_message_id": "c-0001", "body": "Merhaba!" }

{ "message": { "id": "…", "channel_id": "0192f2bb-…", "sender_player_id": "…", "client_message_id": "c-0001", "body": "Merhaba!", "sent_at_ms": 1790000000123 }, "duplicate": false }

Kurallar, sırasıyla:

1. client_message_id boş ya da 200 karakterden uzunsa 400.
2. Gövde 1–2000 Unicode karakter olmalı ve en az bir boşluk dışı karakter içermelidir; aksi 400.
3. Oyuncu o kanal için susturulmuşsa 403.
4. Hız sınırı: oyuncu başına 10 saniyede en çok 20 mesaj; aşımı 429 döner.
5. Küfür süzgeci: mesajda yasaklı bir sözcük (boşlukla ayrılmış tam sözcük, büyük/küçük harf duyarsız) varsa 422 döner.
6. Mesaj arşive yazılır, ardından canlı abonelere dağıtılır. Dağıtım başarısız olsa bile arşivlenmiş mesaj silinmez.

Arşivi okumak

GET /v1/chat/channels/{channel_id}/messages?before_ms=1790000000000&limit=50 yanıtı { "messages": [ … ] } döner. before_ms, bu Unix milisaniyesinden eski mesajları ister; bir sonraki sayfa için en eski mesajın sent_at_ms değerini verin.

Canlı sohbet (WebSocket)

GET /v1/chat/ws adresine bağlanırken x-crx-env ve oturum kimliği (çerez ya da Authorization: Bearer) başlık olarak gönderilir. Kimlik doğrulanmadan yükseltme yapılmaz (401); modül kapalıysa 404.

Uyarı

Tarayıcıdaki WebSocket API’si özel başlık (x-crx-env) gönderemez; bu nedenle chat soketine tarayıcıdan doğrudan bağlanılamaz. Tarayıcı oyunları REST ile yoklayabilir; native istemciler (örneğin Unity masaüstü/mobil) başlık ekleyerek bağlanabilir. Başlık yerine sorgu parametresi ya da alt protokol henüz desteklenmez.

İstemci çerçeveleri (JSON; type alanı küçük camelCase, diğer alanlar snake_case):

Sunucu çerçeveleri:

Bir soket aynı anda tek kanala abonedir. Tanınmayan alan içeren çerçeve invalid_frame alır. Modül sonradan kapanırsa açık soket de kapatılır. Genel gerçek zamanlı yüzey için bkz. Gerçek zamanlı: genel bakış.

Sürümleme ve tekrar güvenliği

• Mesaj gönderiminde Idempotency-Key başlığı yoktur; tekrar güvenliği client_message_id ile sağlanır. Ağ hatasında aynı değerle yeniden gönderin: mesaj bir kez görünür (duplicate: true).
• If-Match kullanılmaz.

Olaylar

Sohbet olayı webhook olarak gönderilmez; webhook olay türleri arasında sohbet yoktur. Canlı akış için WebSocket kullanın.

Sınırlar

• Mesaj gövdesi 1–2000 karakter; client_message_id en çok 200 karakter.
• Gönderim hızı: oyuncu başına 10 saniyede 20 mesaj.
• Arşiv sayfası 1–100 mesaj.
• Bir WebSocket aynı anda tek kanala abone olabilir.

Sık görülen hatalar

Çalışan örnek

Oturum çerezi (cookies.txt) ile REST üzerinden bir kanala yazıp geçmişi okuma:

curl -X POST "$API/v1/chat/channels/$CHANNEL/messages" \
  -H "x-crx-env: $ENV" \
  -H "Content-Type: application/json" -b cookies.txt \
  -d '{"client_message_id":"c-0001","body":"Merhaba!"}'

curl "$API/v1/chat/channels/$CHANNEL/messages?limit=20" \
  -H "x-crx-env: $ENV" -b cookies.txt

İlgili sayfalar

• Klanlar ve partiler · Gerçek zamanlı: genel bakış
• Oturumlar ve CSRF · Hatalar

Skor tabloları ve turnuvalar

Bu sayfa oyuncuların puanla yarıştığı skor tablolarını (leaderboard) ve eleme usulü turnuvaları anlatır. Puanı güvenilir sunucudan yazıp oyun içinde sıralamayı göstermek istiyorsanız okuyun.

Ne işe yarar

Rekabet modülü (competition) iki şey sağlar:

• Skor tablosu: Oyuncu başına en iyi puanı tutan, sezonlara bölünebilen sıralama.
• Turnuva: Oyuncu ya da klan katılımcılarıyla tek eleme, çift eleme ya da lig usulü bracket; final ödülü ile.

Puan yazma ve tablo yönetimi sunucu anahtarıyla yapılır. Oyun istemcisi tabloyu oyuncu oturumuyla okur ve sunucu anahtarı gerekmez.

Modül kapalıysa uçlar 404 ve {"code":"module_disabled","module":"competition"} döner. Modülü Oyun ayarları › Modüller sayfasından açın.

Panelde nerede

Turnuvalar için panel ekranı yoktur; yalnız REST ile yönetilir.

Veri modeli (düz dille)

• Tablo tanımı: key, name, metric_expr, order (asc: küçük puan iyi, desc: büyük puan iyi), season, tie_policy, player_visible, unit ve unit_suffix. Tanım sürümlüdür.
• Sezon (season): none (hiç sıfırlanmaz), daily, weekly, monthly (UTC takvimine hizalı: gün 00:00 UTC’de, hafta Pazartesi 00:00 UTC’de, ay ayın birinde döner) ya da custom (custom_period_ms uzunluğunda dönem). Sezon kapanınca sıralaması değişmez bir kayda alınır.
• Puan: Tam sayı (i64). Bir oyuncunun sezondaki en iyi puanı sayılır (desc’te en yüksek, asc’te en düşük). Daha kötü bir puan göndermek sıralamayı değiştirmez.
• Eşitlik (tie_policy): Şimdilik tek seçenek score_achieved_player_id: önce puan, sonra o puana ilk ulaşan, sonra oyuncu kimliği.
• Sıra (rank): 1’den başlar.
• Birim (unit): points, money (en küçük para birimi) ya da duration_ms; unit_suffix 1–8 karakterlik ektir ($, ms …). Birim yalnız gösterim içindir.
• player_visible: true ise oyuncu oturumu tabloyu okuyabilir; varsayılan false.
• metric_expr: Kayıt anında derlenen CEL ifadesi (zorunlu, boş olamaz). Eklentilerin kendiliğinden kurduğu tablolar event.score kullanır; REST ile kurarken de aynı ifadeyi yazın.

Oyunun yaptığı çağrılar

Sunucu uçları Authorization: Bearer crx_live_<önek>_<gizli> ister; istemci anahtarı ve oyuncu oturumu reddedilir. Oyuncu ucu çerez ya da oturum belirteci ve x-crx-env: <ortam uuid> ile çalışır; geliştirici anahtarı kabul edilmez.

Not

TypeScript SDK’sında oyuncu okuması için player.leaderboard(key, { limit }) vardır; sunucu uçları (puan yazma, tanım, turnuva) için tipli istemci yoktur ve ham REST ile çağrılır. Bkz. TypeScript SDK.

Tablo tanımı

POST /v1/leaderboards
Authorization: Bearer crx_live_<önek>_<gizli>
Content-Type: application/json

{
  "key": "daily-earnings", "name": "Günlük kazanç",
  "metric_expr": "event.score", "order": "desc",
  "season": "daily", "tie_policy": "score_achieved_player_id",
  "player_visible": true, "unit": "money", "unit_suffix": "$"
}

201 döner ve { id, key, name, metric_expr, order, season, custom_period_ms, tie_policy, season_key } gelir. season: "custom" için custom_period_ms pozitif olmalıdır.

Puan yazmak

POST /v1/leaderboards/daily-earnings/scores
Authorization: Bearer crx_live_<önek>_<gizli>
Idempotency-Key: score-oyuncu-1234-2026-11-03
Content-Type: application/json

{ "player_id": "0192f0f2-5b1a-7c3e-9d11-4a5b6c7d8e9f", "score": 4200 }

{ "entry": { "rank": 7, "player_id": "0192f0f2-…", "score": 4200, "achieved_at_ms": 1790000000000 }, "replayed": false }

Yanıt 202’dir: puan kalıcı olarak kabul edilmiştir; sıralama projeksiyonu kısa bir gecikmeyle güncellenir, bu yüzden hemen ardından okunan tablo birkaç saniye geride kalabilir. Idempotency-Key zorunludur: aynı anahtar ve aynı gövde aynı sonucu replayed: true ile döndürür.

Tabloyu oyuncu oturumuyla okumak

GET /v1/player/leaderboards/daily-earnings?limit=10
x-crx-env: 0192f000-0000-7000-8000-00000000e001

{
  "leaderboard": { "key": "daily-earnings", "name": "Günlük kazanç", "order": "desc", "season": "daily", "seasonKey": "2026-11-03", "seasonEndsAtMs": 1790121600000, "unit": "money", "unitSuffix": "$" },
  "entries": [ { "rank": "1", "playerId": "…", "displayName": "Ayşe", "score": "9800", "achievedAtMs": 1790000000000 } ],
  "me": { "rank": "7", "playerId": "…", "displayName": "Siz", "score": "4200", "achievedAtMs": 1790000000000 }
}

• Yalnız player_visible tablolar okunur; aksi 404. Modül kapalıysa da 404.
• limit 1–50 (varsayılan 20).
• rank ve score JSON’da ondalık metindir (kayıpsız i64); SDK bunları bigint yapar. Alan adları bu uçta camelCase’tir.
• Yasaklı ve silinmiş oyuncular süzülür ve sıra sayfa içinde yoğun numaralanır; me, görünür oyuncular arasındaki sıranızdır. Bu sezonda puanı yoksa me null’dır.
• Birinci sayfa kısa süre (en çok birkaç saniye) önbelleğe alınır.

Turnuvalar

POST /v1/tournaments
Authorization: Bearer crx_live_<önek>_<gizli>
Content-Type: application/json

{
  "name": "Kış Kupası", "format": "single_elimination", "participant_type": "player",
  "capacity": 16,
  "registration_opens_at_ms": 1790000000000, "registration_closes_at_ms": 1790086400000,
  "seeding_source": "registration_order",
  "prize_table": { "currency_key": "gold", "amount": 5000 }
}

• format: single_elimination, double_elimination, round_robin. participant_type: player ya da clan.
• capacity 2–1024; kayıt kapanışı açılıştan sonra olmalı; name 1–200 karakter.
• seeding_source: registration_order (kayıt sırası; leaderboard_id verilmez) ya da leaderboard (yalnız oyuncu turnuvasında; leaderboard_id zorunlu).
• prize_table: currency_key (boşluksuz, en çok 200 karakter) ve pozitif amount içeren nesne.
• Akış: oluştur → participants ile kaydet ({ "participant_id" }) → start ile bracket’i üret → her maç için result bildir (reporter_id, reported_side: home away admin, outcome: home_win away_win draw, score). admin tarafı itirazı çözmek içindir.
• Yanıtlar turnuvanın güncel görünümünü ({ "tournament": { … } }) taşır.

Sürümleme ve tekrar güvenliği

• Puan yazma, katılımcı kaydı ve maç sonucu Idempotency-Key ister (aynı anahtar + aynı gövde: tekrar çalışmaz; farklı gövde: 422).
• Tablo tanımı sürümlüdür; liste ve sıralama okumaları sürüm başlığı istemez.
• Genel kurallar: Idempotency ve eşzamanlılık.

Olaylar

Puan kabulü score_submitted, sezon geçişi season_closed/season_opened olaylarını üretir; bunlar görev hedeflerinde ve kural otomasyonunda kullanılabilir. Webhook filtresi olarak seçilebilen türler arasında skor tablosu ya da turnuva olayı yoktur; filtresiz kayıtlı uç noktalar bütün olayları alır ve bunlara skor olayları da dahildir, ancak zarf biçimi belgelenmiş bir sözleşme değildir. Final ödülü için Ödüller sayfasındaki ödül verme akışını kullanın.

Sınırlar

• Oyuncu okumasında limit 1–50; sunucu entries uçlarında sayfalama imleçlidir.
• Turnuva capacity 2–1024.
• season: custom için pozitif custom_period_ms gerekir.

Sık görülen hatalar

Çalışan örnek: puan yaz, tabloyu oku

/** Skor tablosu: sunucu puan yazar (ham REST), oyun istemcisi tabloyu oyuncu oturumuyla okur. */
import type { PlayerClient } from "@ferdiunal/open-play-ts";

/** Sunucu: `POST /v1/leaderboards/{key}/scores`. Sunucu anahtarı gerekir; Idempotency-Key zorunludur. */
export async function submitScore(baseUrl: string, serverApiKey: string, board: string, playerId: string, score: number, requestKey: string): Promise<number> {
  const response = await fetch(`${baseUrl}/v1/leaderboards/${encodeURIComponent(board)}/scores`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${serverApiKey}`,
      "Content-Type": "application/json",
      "Idempotency-Key": requestKey,
    },
    body: JSON.stringify({ player_id: playerId, score }),
  });
  if (response.status !== 202) throw new Error(`Puan yazılamadı: HTTP ${response.status} ${await response.text()}`);
  const body = (await response.json()) as { entry: { rank: number }; replayed: boolean };
  return body.entry.rank;
}

/** Oyun istemcisi: tablonun ilk sayfası ve oyuncunun kendi satırı (`player_visible` tablolar). */
export async function showBoard(player: PlayerClient, board: string): Promise<void> {
  const view = await player.leaderboard(board, { limit: 10 });
  for (const row of view.entries) console.log(`${row.rank}. ${row.displayName} — ${row.score}`);
  if (view.me !== null) console.log(`Siz: ${view.me.rank}. sıra, ${view.me.score} puan`);
}

İlgili sayfalar

• Ödüller · Klanlar ve partiler · Karakterler
• TypeScript SDK · Sayılar ve kodlama

Bildirimler

Bu sayfa oyuncuya oyun içi (gelen kutusu) ve push bildirimi göndermenin yolunu anlatır: panelde sağlayıcı, şablon ve kural kurulumu; oyunun cihaz kaydı, gelen kutusu okuması ve sunucudan doğrudan gönderim. Bildirim altyapısını kendiniz yazmadan kullanmak istiyorsanız okuyun.

Ne işe yarar

Bildirim modülü (notifications) bir bildirimi önce kuyruğa yazar, sonra arka plandaki işçi sağlayıcıya (FCM, APNs ya da OneSignal) gönderir. API’de senkron push gönderimi yoktur: isteğiniz kuyruğa yazıldığında 200 alırsınız; teslimat sonradan olur.

Bildirimin metni şablondan gelir. Şablon panelde yazılır; oyun yalnız şablon anahtarını ve doldurma verisini gönderir. Bildirimi iki yolla üretebilirsiniz:

• Sunucudan gönderim: Oyun sunucunuz POST /v1/notifications çağırır.
• Kural: Panelde kurduğunuz kural, bir oyun olayı olunca (ör. seviye atlama, görev tamamlama, mağaza satın alma) otomatik bildirim üretir.

Modül kapalıysa uçlar 404 ve {"code":"module_disabled","module":"notifications"} döner. Modülü Oyun ayarları › Modüller sayfasından açın.

Panelde nerede

Sağlayıcı kimlik bilgileri panelde yalnız yetkili rolle girilir ve sunucuda mühürlü saklanır; panel yalnız parmak izini gösterir.

Veri modeli (düz dille)

• Sağlayıcı (provider): fcm, apns, one_signal. Her ortam için ayrı açılıp kapatılır.
• Cihaz (device): Oyuncunun bir sağlayıcıdaki kayıtlı belirteci (token) ve platformu (ios, android, web). Aynı (ortam, sağlayıcı, belirteç) tekrar kaydedilebilir; yanıt hangi dalın işlediğini söyler (created, revived, refreshed).
• Şablon (template): Anahtar, dil başına başlık ve gövde, {{yer_tutucu}} alanları. İstenen dil yoksa İngilizce (en) kullanılır. Her bildirim, gönderildiği andaki şablon sürümüne bağlanır.
• Kanal: in_game (yalnız gelen kutusu), push (yalnız push), both.
• Bildirim (inbox satırı): id, template_key, title, body, data, channel, status, created_at, sent_at, read_at. Durum: queued, sent, delivered, failed, read.
• Tekrar anahtarı (dedup_key): Aynı (ortam, oyuncu, anahtar) ikinci kez yazılmaz.

Oyunun yaptığı çağrılar

İki kimlik türü vardır: oyuncu oturumu (çerez ya da oturum belirteci + x-crx-env: <ortam uuid>) ve sunucu anahtarı (Authorization: Bearer crx_live_<önek>_<gizli>).

Oyuncu uçlarında x-csrf-token ve Origin denetimi uygulanmaz; oturum çerezi ya da oturum belirteci yeterlidir.

TypeScript SDK’sında oyuncu tarafı hazırdır: player.notifications altında getPushConfig, registerDevice, unregisterDevice, enableWebPush, disableWebPush, inbox ve markRead bulunur. Sunucudan gönderim için tipli istemci yoktur; ham REST kullanılır. Bkz. TypeScript SDK.

Sunucudan bildirim göndermek

POST /v1/notifications
Authorization: Bearer crx_live_<önek>_<gizli>
Content-Type: application/json

{
  "player_id": "0192f0f2-5b1a-7c3e-9d11-4a5b6c7d8e9f",
  "template_key": "daily_reward_ready",
  "locale": "tr",
  "data": { "amount": 250 },
  "channel": "both",
  "dedup_key": "daily-2026-11-03"
}

{ "id": "0192f400-…", "duplicate": false }

• locale: kısa dil kodu (tr, en …). İstenen dil şablonda yoksa en kullanılır.
• dedup_key (isteğe bağlı, 1–256 karakter): aynı anahtar ikinci kez gelirse yeni satır yazılmaz; 200 ve duplicate: true ile ilk bildirimin kimliği döner.
• 403: istemci anahtarı ya da oyuncu oturumu. 404: şablon hiçbir dilde yok. 400: template_key boş ya da 128 karakterden uzun, locale biçimi geçersiz ya da şablondaki bir yer tutucu data içinde eksik.

Gelen kutusunu okumak

GET /v1/notifications?status=queued&limit=20
x-crx-env: 0192f000-0000-7000-8000-00000000e001

{
  "items": [
    { "id": "0192f400-…", "template_key": "daily_reward_ready", "template_version": 2, "title": "Günlük ödülün hazır", "body": "250 altın seni bekliyor.", "data": { "amount": 250 }, "channel": "both", "status": "sent", "created_at": "2026-11-03T09:00:00Z", "sent_at": "2026-11-03T09:00:02Z", "read_at": null }
  ],
  "next_cursor": null
}

Liste yeniden eskiye sıralıdır (created_at, id). limit 1–100; next_cursor null ise son sayfadır. Teslimi başarısız olan satırlar da listelenir. POST /v1/notifications/{id}/read satırı read yapar; ikinci çağrı aynı satırı döndürür ve yeni olay üretmez.

Push cihazı kaydetmek

POST /v1/devices
x-crx-env: 0192f000-0000-7000-8000-00000000e001
Content-Type: application/json

{ "provider": "fcm", "platform": "android", "token": "<cihaz belirteci>", "device_meta": { "model": "Pixel 8" } }

{ "id": "…", "registration": "created", "provider": "fcm", "platform": "android", "created_at": "2026-11-03T09:00:00Z" }

provider apns, fcm ya da one_signal; platform ios, android ya da web. Belirteç boş olamaz. Oyuncu kimliği gövdeden değil oturumdan gelir. app_key çok uygulamalı ortamlarda uygulamayı ayırır.

Not

Üretilmiş OpenAPI belgesi cihaz sağlayıcısını onesignal olarak yazar; sunucu ve SDK one_signal kullanır. Bilinen bir belge sapmasıdır; one_signal gönderin.

Web push için player.notifications.enableWebPush tarayıcı izin akışını, GET /v1/push/config ile aldığı ayarlarla yürütür; çıkışta session.logout() bu sayfadan kaydedilmiş web cihazını kendiliğinden iptal eder.

Kurallar: olay olunca otomatik bildirim

Panelde bir kural; tetikleyici (kapalı bir listeden bir oyun olayı; örneğin level_up, quest_completed, store_purchase_completed, vip_tier_up), isteğe bağlı koşul, şablon, dil, kanal ve alıcı oyuncu yolundan oluşur. Kural sürümleri panelin geçmiş sekmesinde görünür. Bildirimin kendisi yeni bir kural tetiklemez. Kural editörü bir “canlı önizleme” ve test gönderimi sunar. Ayrıntılı alanlar için panel sayfasına bakın.

Sürümleme ve tekrar güvenliği

• Gönderim: dedup_key ile tekrar güvenliği; Idempotency-Key başlığı yoktur.
• Cihaz kaydı ve okundu işareti doğal olarak idempotenttir.
• Şablon sürümü bildirime bağlanır; şablonu sonradan değiştirmek eski bildirimi etkilemez.

Olaylar

Bildirim kuyruğa yazıldığında bir notification_queued olayı üretilir ve gönderim işçisi onu tüketir. Webhook filtresi olarak seçilebilen türler arasında bildirim yoktur; filtresiz kayıtlı uç noktalar bu iç olayı da alır, ancak zarf biçimi belgelenmiş bir sözleşme değildir.

Sınırlar

• dedup_key 1–256 karakter; gelen kutusu limit 1–100.
• Push teslimatı en-iyi-çabadır: sağlayıcı reddederse satır failed olur. Cihaz kalıcı geçersizse (örn. silinmiş uygulama) cihaz otomatik iptal edilir.
• Sağlayıcı kimlik bilgileri tanımlı değilse bildirim kuyrukta bekler ve panelde sağlayıcı durumu uyarı gösterir.

Sık görülen hatalar

Çalışan örnek

Oyuncu tarafında gelen kutusunu boşaltma:

/** Oyuncu tarafı: gelen kutusunu okur ve okunmamış bildirimleri okundu işaretler. */
import type { PlayerClient } from "@ferdiunal/open-play-ts";

/** İlk sayfadaki okunmamış bildirimleri yazdırır ve okundu yapar. */
export async function drainInbox(player: PlayerClient): Promise<number> {
  const page = await player.notifications.inbox({ limit: 20 });
  let marked = 0;
  for (const item of page.items) {
    if (item.readAt !== null) continue;
    console.log(item.title, item.body, item.data);
    await player.notifications.markRead(item.id);
    marked += 1;
  }
  return marked;
}

Sunucudan gönderim için curl örneği yukarıdadır.

İlgili sayfalar

• Karakterler · Ödüller · Mağaza ve IAP · Oyun kuralları
• TypeScript SDK · Hatalar

Webhook’lar

Bu sayfa Open Play’in oyun olaylarını kendi sunucunuza HTTP POST ile nasıl ilettiğini anlatır: uç nokta kaydı, olay türleri, imza doğrulaması, yeniden deneme ve tekrar eden teslimatla başa çıkma. Karakter, mağaza ya da ödül olayında kendi arka uç sisteminizi tetiklemek istiyorsanız okuyun.

Ne işe yarar

Open Play bir olay oluştuğunda (ör. level_up, store_purchase_completed, reward_granted) kayıtlı uç noktalarınıza imzalı bir POST gönderir. Teslimat en az bir kez (at-least-once) yapılır: aynı olay ağ hataları yüzünden birden çok gelebilir, bu yüzden alıcınız tekrarı X-Crx-Event-Id ile elemelidir.

Modül kapalıysa uçlar 404 ve {"code":"module_disabled","module":"webhooks"} döner. Modülü Oyun ayarları › Modüller sayfasından açın.

Panelde nerede

Panel bu sayfada salt okunurdur: uç nokta kaydı REST ile yapılır; panelde yeniden gönderme ya da başarısız teslimatı kurtarma düğmesi yoktur. Panel sırları, ham gövdeyi ve ham hata metnini göstermez.

Veri modeli (düz dille)

• Uç nokta (endpoint): url, isteğe bağlı event_types süzgeci, enabled ve created_at.
• Sır (secret): Sunucu üretir (whsec_ + 64 küçük harf hex), yalnız kayıt yanıtında bir kez döner ve şifreli saklanır. Sonra hiçbir uç onu vermez. Sır değiştirme ucu yoktur: yenilemek için uç noktayı silip yeniden kaydedin.
• Olay zarfı: Gönderilen JSON gövdesi. Her zarfta event_id, type, environment_id ve data bulunur.
• Teslimat (delivery): Bir olayın bir uç noktaya gönderimi. Durumları bekleyen, teslim edilen ve başarısız (DLQ).

Seçilebilir olay türleri

event_types boşsa uç nokta bütün olayları alır (aşağıdaki not). Doluysa yalnız şu türlerden seçebilirsiniz:

Bilinmeyen bir tür 400 döner. Tam liste ve veri alanları: Webhook olayları.

Uyarı

Süzgeci boş bırakırsanız uç nokta yukarıdaki listeyle sınırlı kalmaz: outbox’a yazılan bütün olayları (eşya, cüzdan, klan, parti, skor, bildirim kuyruğu gibi) alır. Bu ek olayların zarf biçimi belgelenmiş bir sözleşme değildir ve haber verilmeden değişebilir. Üretimde event_types süzgecini her zaman açıkça verin.

Zarf biçimi

Karakter olayları:

{
  "event_id": "0192f500-1111-7222-8333-944455556666",
  "type": "level_up",
  "character_id": "0192f0f2-5b1a-7c3e-9d11-4a5b6c7d8e9f",
  "environment_id": "0192f000-0000-7000-8000-00000000e001",
  "seq": 12,
  "data": { "...": "olaya özgü alanlar" }
}

Mağaza olaylarında character_id yoktur; seq ile birlikte now_ms (olayın işlendiği an) ve actor_api_key_id bulunur. reward_granted olayında player_id ve data içinde source_kind, table_key, table_version ile verilenler yer alır; çekiliş tohumu hiçbir olayda yoktur.

Oyunun yaptığı çağrılar

Bütün yönetim uçları sunucu anahtarıyla çağrılır; istemci anahtarı 403 alır:

Authorization: Bearer crx_live_<önek>_<gizli>

TypeScript SDK’sı bu dört ucu tipli sunar: createWebhook, listWebhooks, getWebhook, deleteWebhook (bkz. TypeScript SDK).

Uç nokta kaydetmek

POST /v1/webhooks
Authorization: Bearer crx_live_<önek>_<gizli>
Content-Type: application/json

{
  "url": "https://hooks.ornek-oyun.com/open-play",
  "event_types": ["level_up", "store_purchase_completed"]
}

{
  "id": "0192f600-…",
  "url": "https://hooks.ornek-oyun.com/open-play",
  "event_types": ["level_up", "store_purchase_completed"],
  "enabled": true,
  "created_at": "2026-11-03T09:00:00Z",
  "secret": "whsec_<64 hex karakter>"
}

secret değerini hemen güvenli bir yere (gizli yönetim servisine) yazın; bir daha okunamaz.

Kayıt kuralları:

• URL https olmalı; kullanıcı bilgisi (user:parola@) taşımamalı; harf dışı kontrol karakteri ve boşluk içermemeli. Loopback, özel ve link-local IP adresleri kayıtta reddedilir (400).
• Ayrıca her gönderimde adın çözümlendiği IP yeniden denetlenir; özel ya da loopback adrese çözümlenen ad gönderilemez. Yönlendirme (redirect) takip edilmez.
• Aynı URL aktifken ikinci kayıt 409.

Teslimat

Her olay için uç noktanıza şu istek gelir:

POST /open-play
Content-Type: application/json
X-Crx-Signature: t=1790000000,v1=9c1f…e2
X-Crx-Event-Id: 0192f500-1111-7222-8333-944455556666
X-Crx-Event-Type: level_up

{ …zarf… }

İmzayı doğrulamak

İmza, "{t}.{ham gövde}" metninin, kayıtta dönen sırrın tamamı (whsec_… önekiyle) anahtar alınarak hesaplanan HMAC-SHA256 özetidir (küçük harf hex). Doğrulama adımları:

1. X-Crx-Signature başlığından t ve v1 değerlerini ayırın.
2. Ham gövde baytlarını alın. JSON’u ayrıştırıp yeniden serileştirmeyin; imza tel üzerindeki birebir baytlar içindir.
3. HMAC-SHA256(secret, t + "." + ham_gövde) hesaplayın ve v1 ile sabit zamanlı karşılaştırın.
4. t değerini kendi saatinizle karşılaştırın; çok eski (örneğin 5 dakikadan eski) istekleri reddedin. Her yeniden denemede t yenilenir, bu yüzden gerçek bir yeniden deneme bu pencerede kalır.
5. X-Crx-Event-Id daha önce işlendiyse işlemi tekrarlamadan 2xx dönün.

Yanıt ve yeniden deneme kuralları

• Yalnız 2xx başarıdır. Başka her yanıt, zaman aşımı ve bağlantı hatası yeniden denemeyi tetikler.
• Bağlantı için 5 saniye, DNS dahil toplam 10 saniye beklenir.
• Gövde 64 KB’ı aşarsa gönderilmez ve hata sayılır.
• Gecikme min(1 sn × 2^deneme, 5 dk)’dır ve ±%20 rastgelelik içerir. En çok 10 deneme yapılır; 10. başarısız denemeden sonra teslimat başarısız (DLQ) durumuna alınır ve otomatik tekrar edilmez.
• Uç noktayı sildiğinizde bekleyen teslimatlar da başarısız duruma alınır.
• Sıra garantisi yoktur: olaylar karakter için seq ile sıralanabilir, ama teslimat sırası değişebilir.
• Uç nokta yokken oluşan olaylar sonradan gönderilmez; geriye dönük teslimat yoktur.

Sürümleme ve tekrar güvenliği

• Alıcı tarafı: X-Crx-Event-Id ile tekrar eleme zorunludur. Aynı olay yeniden denemede aynı event_id ile gelir; imza zamanı (t) yenilenir.
• Kayıt ucunda Idempotency-Key yoktur; aynı URL’yi ikinci kez kaydetmek 409 döner.
• Zarfta bir olay sürümü alanı yoktur; tanımadığınız alanları yok sayın ve gövdeyi sıkı bir şemayla reddetmeyin.

Sınırlar

• Gövde 64 KB; toplam bekleme 10 saniye; 10 deneme.
• Liste ucunda limit 1–200.
• Redirect takip edilmez; yalnız https.

Sık görülen hatalar

Çalışan örnek: Node ile alıcı

Aşağıdaki sunucu imzayı doğrular, tekrar eden olayı eler ve 2xx döner. Sır ortam değişkeninden gelir; üretimde kalıcı bir depoyla tekrar elemesi yapın.

/** Webhook alıcısı (Node 22): imzayı doğrular, tekrar eden teslimatı `X-Crx-Event-Id` ile eler. */
import { createHmac, timingSafeEqual } from "node:crypto";
import { createServer } from "node:http";

const SECRET = process.env["OPEN_PLAY_WEBHOOK_SECRET"] ?? ""; // uç noktayı kaydederken bir kez dönen sır
const TOLERANCE_SECONDS = 300; // eski teslimatı (replay) reddetme penceresi: alıcının kendi politikası
const seen = new Set<string>(); // örnek amaçlı bellek; üretimde kalıcı depo kullanın

/** `X-Crx-Signature: t=<unix-sn>,v1=<hex>` değerini ham gövdeye karşı doğrular. */
export function verifySignature(secret: string, header: string, rawBody: Buffer, nowSeconds: number): boolean {
  const parts = new Map(header.split(",").map((part) => part.split("=", 2) as [string, string]));
  const t = parts.get("t");
  const v1 = parts.get("v1");
  if (t === undefined || v1 === undefined) return false;
  if (Math.abs(nowSeconds - Number(t)) > TOLERANCE_SECONDS) return false;
  const expected = createHmac("sha256", secret).update(`${t}.`).update(rawBody).digest("hex");
  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(v1, "utf8");
  return a.length === b.length && timingSafeEqual(a, b);
}

createServer((req, res) => {
  const chunks: Buffer[] = [];
  req.on("data", (chunk: Buffer) => chunks.push(chunk));
  req.on("end", () => {
    const rawBody = Buffer.concat(chunks); // imza ham bayt üzerindendir: JSON'u yeniden serileştirmeyin
    const signature = req.headers["x-crx-signature"];
    if (typeof signature !== "string" || !verifySignature(SECRET, signature, rawBody, Math.floor(Date.now() / 1000))) {
      res.writeHead(401).end();
      return;
    }
    const eventId = String(req.headers["x-crx-event-id"] ?? "");
    if (!seen.has(eventId)) {
      seen.add(eventId);
      const event = JSON.parse(rawBody.toString("utf8")) as { type: string; data: unknown };
      console.log("olay", event.type, event.data);
    }
    res.writeHead(200).end(); // yalnız 2xx başarıdır; başka kod yeniden denemeyi tetikler
  });
}).listen(8080);

İlgili sayfalar

• Webhook olayları · Karakterler · Mağaza ve IAP · Ödüller
• Güvenlik · Hatalar

Scene, görsel ve 3B modeller

Bu sayfa oyunun dünyasını oluşturan üç parçayı anlatır: gerçek zamanlı scene (sahne/oda) kaydı, panelden ve sunucudan yüklenen görseller ve operatörün yüklediği 3B modeller. Şehir odalarını sunucudan açmak, ikon ve afiş görselini yönetmek ya da modelleri oyuna sunmak istiyorsanız okuyun.

Ne işe yarar

• Scene: Gerçek zamanlı eklentinin oyuncuları topladığı oda. Oyun sunucusu açılışta ihtiyaç duyduğu scene’leri kaydeder; kayıt idempotenttir.
• Görsel (asset): PNG, JPEG ya da WebP. İçerik adreslidir: adres dosyanın sha256 özetidir, aynı dosya bir kez saklanır. Mağaza afişi, para birimi ikonu ve içerik grubu image alanları bu depoyu kullanır.
• 3B model: Operatörün panelde yüklediği glb (ya da dönüştürülen kaynak dosya). Yayınlanınca eşyaya ya da karaktere bağlanır ve oyun onu katalogdan alır.

Scene ve görsel yazma uçları scenes modülüne bağlıdır; modül kapalıysa 404 ve {"code":"module_disabled","module":"scenes"} döner. Görsel ve model okuma uçları çekirdektir ve modül kapalıyken de çalışır. Modülü Oyun ayarları › Modüller sayfasından açın.

Panelde nerede

Veri modeli (düz dille)

Scene

• Kimlik üç parçadan türetilir: plugin_id (eklenti), module_id (gerçek zamanlı modül) ve key (en çok 96 karakter). Aynı üçlü her zaman aynı scene’e çıkar.
• capacity: Odanın oyuncu kapasitesi; en çok 10 000.
• state: open, draining (boşalıyor) ya da closed.
• partition_id: Scene’in dağıtık çalıştığı bölüm kimliği (sunucu üretir).

Görsel

• Tür dosyanın ilk baytlarından çıkarılır; Content-Type başlığı yalnız tavsiyedir. Kabul edilen türler image/png, image/jpeg, image/webp.
• En çok 2 MiB; genişlik ve yükseklik her biri en çok 4096 piksel.
• Yanıt sha256, contentType, byteSize ve created (bu çağrıda yazıldı mı) verir.

3B model

• Yükleme glb olabilir ya da fbx, obj, usdz, stl, blend, 3mf, dxf gibi kaynak biçimlerinden dönüştürülür. Dönüştürme durumu queued, converting, ready, failed’dır; başarısızlığın nedeni panelde Türkçe cümleyle görünür (ör. harici kaynağa başvuru, bütçe aşımı, 2B DXF).
• Her model sürümlüdür; yayınlanan sürüm katalogda görünür. Yaşam döngüsü active, archived, purged.
• Varsayılan sınırlar: yüklenen dosya 50 MiB, ortam kotası 1 GiB, ortamda 200 model, model başına 20 sürüm, operatör başına 10 dakikada 10 yükleme.
• Dönüştürücü yalnız amd64 mimarisinde çalışır; başka mimaride yalnız glb yüklenebilir.

Oyunun yaptığı çağrılar

Yönetim uçları Authorization: Bearer crx_live_<önek>_<gizli> ister; istemci anahtarı 403 alır.

Scene sağlamak

PUT /v1/scenes
Authorization: Bearer crx_live_<önek>_<gizli>
Content-Type: application/json

{ "plugin_id": "package-ride", "module_id": "package-ride.presence", "key": "istanbul-1", "capacity": 200 }

{ "scene_id": "…", "plugin_id": "package-ride", "module_id": "package-ride.presence", "key": "istanbul-1", "partition_id": "…", "capacity": 200, "state": "open", "created": true }

• Scene yoksa yazılır (201, created: true); varsa değiştirilmeden döner (200, created: false). Idempotency-Key gerekmez.
• 400: kimlik, anahtar ya da kapasite geçersiz (gövde hataları da 400’dür). 403: istemci anahtarı. 409: aynı anahtarda farklı kimlikli scene. 422: eklenti bu ortamda etkin değil.