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.