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.