Device Token Endpoint Kullanım Kılavuzu

Genel Bakış

/notifications/device-token endpoint'i hem cihaz token kaydı/güncellemesi hem de kullanıcı timezone bilgisi güncellemesi için kullanılır. Endpoint, esnek bir yapıya sahiptir ve tüm alanlar opsiyoneldir. Bu sayede kullanıcı izin vermediği durumlarda bile timezone gibi bilgiler güncellenebilir.

Endpoint Detayları

URL: POST /notifications/device-token
Authentication: JWT Bearer Token (opsiyonel - kullanıcı giriş yapmışsa otomatik ilişkilendirilir)

Request Body

Tüm alanlar opsiyoneldir. En az bir alan gönderilmelidir.

{
  token?: string;        // Firebase Cloud Messaging cihaz token değeri
  platform?: string;     // Platform bilgisi (örn: ios | android | web)
  deviceId?: string;     // Cihazı ayırt etmek için ek kimlik (max 255 karakter)
  timezone?: string;     // Kullanıcı timezone bilgisi (örn: Europe/Istanbul, America/New_York)
}

Kullanım Senaryoları

Senaryo 1: Token ile Tam Kayıt/Güncelleme

Token gönderildiğinde, token kaydı yapılır veya güncellenir (upsert). Aynı token tekrar gönderilirse mevcut kayıt güncellenir ve lastUsedAt alanı güncellenir.

Örnek İstek:

POST /notifications/device-token
{
  "token": "fcm_token_12345",
  "platform": "ios",
  "deviceId": "iphone-14-pro",
  "timezone": "Europe/Istanbul"
}

Sonuç:

• Token kaydı yapılır veya güncellenir
• Kullanıcı giriş yapmışsa token kullanıcı ile ilişkilendirilir
• Timezone bilgisi kullanıcıya kaydedilir

Senaryo 2: Sadece Timezone Güncelleme (Token Yok)

Token gönderilmediğinde, sadece timezone bilgisi güncellenir. Bu durum kullanıcının push notification izni vermediği senaryolarda kullanışlıdır.

Örnek İstek:

POST /notifications/device-token
{
  "timezone": "America/New_York"
}

Sonuç:

• Token kaydı yapılmaz
• Sadece kullanıcının timezone bilgisi güncellenir
• Kullanıcı giriş yapmış olmalıdır (userId gereklidir)

Senaryo 3: Token ve Timezone Güncelleme

Token ile birlikte timezone da gönderilebilir. Bu durumda hem token kaydı yapılır hem de timezone güncellenir.

Örnek İstek:

POST /notifications/device-token
{
  "token": "fcm_token_12345",
  "timezone": "Europe/Istanbul"
}

Sonuç:

• Token kaydı yapılır veya güncellenir
• Timezone bilgisi kullanıcıya kaydedilir

Senaryo 4: Sadece Platform/DeviceId Güncelleme

Token mevcut ise, sadece platform veya deviceId bilgisi güncellenebilir.

Örnek İstek:

POST /notifications/device-token
{
  "token": "fcm_token_12345",
  "platform": "android"
}

Sonuç:

• Mevcut token kaydı güncellenir
• Platform bilgisi güncellenir
• lastUsedAt alanı güncellenir

Response

Başarılı Yanıt (200 OK):

{
  "success": true
}

Hata Yanıtları:

• 400 Bad Request: Geçersiz istek veya validation hatası
• 401 Unauthorized: Yetkilendirme hatası (JWT token geçersiz veya eksik)

Önemli Notlar

1. Token Opsiyonelliği: Token gönderilmediğinde hiçbir token kaydı yapılmaz. Sadece timezone güncellemesi yapılır.

2. Upsert Mantığı: Token gönderildiğinde, aynı token için mevcut kayıt varsa güncellenir, yoksa yeni kayıt oluşturulur.

3. Kullanıcı İlişkilendirme:

   • Kullanıcı giriş yapmışsa (JWT token geçerli), token otomatik olarak kullanıcı ile ilişkilendirilir
   • Kullanıcı giriş yapmamışsa, token anonim olarak kaydedilir

4. Timezone Güncelleme:

   • Timezone null/undefined gönderilirse işlem yapılmaz (sessizce geçilir)
   • Timezone güncellemesi için kullanıcı giriş yapmış olmalıdır (userId gereklidir)

5. Platform Değerleri: Platform alanı için önerilen değerler: ios, android, web

6. DeviceId: Cihazı ayırt etmek için kullanılır, maksimum 255 karakter olabilir

Kullanım Örnekleri

React Native Örneği

// Token ve timezone ile kayıt
const registerDeviceToken = async (fcmToken: string, timezone: string) => {
  try {
    const response = await fetch('https://api.example.com/notifications/device-token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${authToken}`,
      },
      body: JSON.stringify({
        token: fcmToken,
        platform: 'ios',
        timezone: timezone,
      }),
    });
    return await response.json();
  } catch (error) {
    console.error('Token kayıt hatası:', error);
  }
};

// Sadece timezone güncelleme (kullanıcı push izni vermedi)
const updateTimezone = async (timezone: string) => {
  try {
    const response = await fetch('https://api.example.com/notifications/device-token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${authToken}`,
      },
      body: JSON.stringify({
        timezone: timezone,
      }),
    });
    return await response.json();
  } catch (error) {
    console.error('Timezone güncelleme hatası:', error);
  }
};

Axios Örneği

import axios from 'axios';

// Token ile kayıt
const registerToken = async (token: string, timezone?: string) => {
  return axios.post('/notifications/device-token', {
    token,
    platform: 'android',
    timezone,
  });
};

// Sadece timezone güncelleme
const updateTimezoneOnly = async (timezone: string) => {
  return axios.post('/notifications/device-token', {
    timezone,
  });
};

İlgili Endpoint'ler

• Token Silme: DELETE /notifications/device-token/:token
• Test Bildirimi: POST /notifications/test

Değişiklik Geçmişi

• Güncelleme: Token alanı opsiyonel hale getirildi. Token null gönderildiğinde sadece timezone güncellemesi yapılıyor.
• Güncelleme: Endpoint hem ekleme hem güncelleme için kullanılabiliyor (upsert mantığı).