Oyuncu kimliği

#Neden gerekli?

Ziyaretçi doğrulanmış bir oyuncuya bağlandığında:

• temsilciler konuşmada doğrulanmış oyuncu kimliğini ve operatör verilerini görür;
• yapay zekâ asistanı bakiye, yatırım, bonus geçmişi gibi hesap verilerini operatör API’nizden okuyabilir (yalnızca bu oyuncu için);
• bonus gibi işlemler yalnızca doğrulanmış oyuncular için istenebilir.

Operatör API’nize yapılan çağrılarda oyuncu kimliği her zaman bu token’dan gelen değerle doldurulur; ziyaretçinin yazdıklarıyla değiştirilemez.

#Akış

1. Sırrı alın

   Yönetim panelinde Web siteleri ve widget sayfasında Kimlik sırrını göster (denetlenir) düğmesine tıklayın (websites:write yetkisi gerekir; her gösterim denetim kaydına yazılır). Sır her web sitesi için ayrıdır ve base64url biçiminde gösterilir. Yalnızca sunucunuzda saklayın.

2. Sunucunuzda token imzalayın

   Oyuncu giriş yaptığında, sırrı base64url ile çözüp elde ettiğiniz baytlarla bir HS256 JWT imzalayın (aşağıdaki örneklere bakın).

3. Token’ı widget’a verin

   Sayfanız window.TwoPeople.identify(token) çağırır. Widget token’ı POST/api/v1/widget/identity ucuna iletir; platform imzayı ve talepleri doğrular, ziyaretçiyi oyuncuya bağlar.

#Token biçimi

// header
{ "alg": "HS256", "typ": "JWT" }
// payload
{
  "sub": "player-48213",          // your player id
  "aud": "wk_…",                  // the website's widget key
  "iat": 1767225600,              // issued at (unix seconds)
  "exp": 1767225900,              // expiry, at most iat + 300
  "jti": "5f0c2a8e-…"             // unique token id (single use)
}

#Sunucu örnekleri

Örneklerde widget anahtarı ve sır ortam değişkenlerinden okunur: TWOPEOPLE_WIDGET_KEY ve TWOPEOPLE_IDENTITY_SECRET.

// npm install jose
import { SignJWT } from 'jose';
import { randomUUID } from 'node:crypto';

// The secret is shown base64url-encoded: decode it to bytes before signing.
const secret = Buffer.from(process.env.TWOPEOPLE_IDENTITY_SECRET, 'base64url');
const widgetKey = process.env.TWOPEOPLE_WIDGET_KEY; // wk_…

export async function playerIdentityToken(playerId) {
  const now = Math.floor(Date.now() / 1000);
  return new SignJWT({})
    .setProtectedHeader({ alg: 'HS256', typ: 'JWT' })
    .setSubject(String(playerId)) // your player id
    .setAudience(widgetKey)
    .setJti(randomUUID()) // unique per token
    .setIssuedAt(now)
    .setExpirationTime(now + 300) // at most 5 minutes
    .sign(secret);
}

#Sayfada kullanım

Token kısa ömürlü ve tek kullanımlık olduğundan, en güvenlisi onu ihtiyaç anında kendi sunucunuzdan almaktır. window.TwoPeople widget yüklendikten sonra tanımlanır:

// Runs on your page after the player has logged in.
// /api/support/identity-token is an endpoint on YOUR backend that returns
// { token } for the logged-in player (see the server examples above).
function whenWidgetReady(callback) {
  if (window.TwoPeople) return callback(window.TwoPeople);
  setTimeout(() => whenWidgetReady(callback), 200);
}

whenWidgetReady(async (widget) => {
  const res = await fetch('/api/support/identity-token', {
    method: 'POST',
    credentials: 'include',
  });
  if (!res.ok) return;
  const { token } = await res.json();
  const linked = await widget.identify(token); // true when the player is verified
  if (!linked) console.warn('2people: player identity was not accepted');
});

identify(), oyuncu bağlandığında true, token reddedildiğinde ya da istek başarısız olduğunda false döner. Açık bir konuşma varsa bağlantıdan sonra güncellenir.

#Hatalar

POST/api/v1/widget/identity ucu reddettiğinde application/problem+json döner: