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