Device Token: nasıl çalışır, APNS tokenı alma ve güncelleme

Device Token Nedir

Device Token (cihaz tokenı), APNS’nin (Apple Push Notification Service) bir iOS cihazındaki her uygulama için oluşturduğu, onaltılık dize biçiminde benzersiz bir tanımlayıcıdır. Token, sunucunun belirli bir cihaza push bildirimi göndermesi için kullandığı anahtardır. Geçerli bir Device Token olmadan, sunucu push bildirimleri gönderemez — APNS, 400 BadRequest hatasıyla isteği reddeder.

Token Nasıl Oluşur

Device Token, uygulama yüklemeden sonra APNS ile ilk kez iletişime geçtiğinde iOS sistemi tarafından oluşturulur. Oluşturma süreci, uygulamanın paket kimliği (bundle ID) ve cihazın benzersiz tanımlayıcısı (UID) ile kriptografik bağlantı içerir, ardından APNS uygulamaya onaltılık biçimde (64 karakter) 32 baytlık bir token döndürür. Token kalıcı değildir — sistem belirli koşullar altında yeni bir token oluşturabilir.

Push Bildirimi Gönderiminde Tokenın Rolü

Sunucu bir push bildirimi gönderdiğinde, APNS’ye yapılan HTTP/2 isteğine Device Token’ı dahil eder. APNS tokenı doğrular: token başka bir ortama (üretim yerine sandbox) aitse, süresi dolmuşsa veya iptal edilmişse, Apple sunucusu 410 Gone veya 400 BadRequest hatası döndürür. Token doğrulaması başarılı olduktan sonra APNS, bildirimi cihaza göndermeye başlar.

Device Token ve Diğer Tanımlayıcılar Arasındaki Fark

Device Token, IDFA (Reklam Verenler İçin Tanımlayıcı), IDFV (Satıcı İçin Tanımlayıcı) veya UID (Benzersiz Cihaz Tanımlayıcısı) ile karıştırılmamalıdır. IDFA ve IDFV reklam ve analiz için kullanılır, UID bir donanım seri numarasıdır. Device Token yalnızca push bildirimleri için vardır ve APNS dışında kullanıcı veya cihaz hakkında bilgi ifşa etmez.

Cihaz Tokenı Nasıl Alır ve Kaydeder

Device Token alma süreci, kullanıcıdan izin istemekten sunucuya token göndermeye kadar birkaç zorunlu adımdan oluşur. Her adım kritiktir — herhangi birini atlamak, cihaza push bildirimi gönderememeye neden olur.

Bildirim İzni İsteme

İlk adım, uygulamanın UNUserNotificationCenter.current().requestAuthorization aracılığıyla kullanıcıdan bildirim gönderme izni istemesidir. Kullanıcı kabul edebilir, reddedebilir veya isteğe bağlı seçenekleri (alert, badge, sound) seçebilir. Kullanıcının açık rızası olmadan, uygulama registerForRemoteNotifications’ı çağırsa bile sistem Device Token yayınlamaz. İzni aldıktan sonra uygulama UIApplication.shared.registerForRemoteNotifications() çağrısını yapar ve bu da APNS’ye kayıt sürecini başlatır.

APNS’den Token Alma

Kayıttan sonra APNS, AppDelegate aracılığıyla tokenı döndürür: application(_:didRegisterForRemoteNotificationsWithDeviceToken:). Başarılı bir çağrı, sunucuya iletmek için onaltılık dizeye dönüştürülmesi gereken tokenı içeren bir Data nesnesi içerir. Hata durumunda sistem, sorunun açıklamasıyla application(_:didFailToRegisterForRemoteNotificationsWithError:) çağrısını yapar: yanlış sertifika yapılandırması, ağ kullanılamazlığı veya yanlış proje yapılandırması.

Tokenı Sunucunuza Gönderme

Tokenı aldıktan sonra uygulama, veritabanında depolamak için onu hemen kendi sunucusuna göndermelidir. API isteği tokenı, cihaz tanımlayıcısını (eşleme için), ortamı (sandbox/production) ve isteğe bağlı olarak ek verileri (OS sürümü, cihaz modeli, dil) içerir. Sunucunun her zaman güncel bir tokena sahip olması için tokenın her uygulama başlatılışında yeniden gönderilmesi önerilir.

// İzin isteme ve APNS’ye kayıt olma
func registerForPushNotifications() {
    UNUserNotificationCenter.current()
        .requestAuthorization(options: [.alert, .sound, .badge]) {
        [weak self] granted, error in
        guard granted else {
            print("İzin verilmedi")
            return
        }
        DispatchQueue.main.async {
            UIApplication.shared
                .registerForRemoteNotifications()
        }
    }
}

// APNS’den Device Token alma
func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    let tokenString = deviceToken
        .map { String(format: "%02.2hhx", $0) }
        .joined()
    print("Device Token: \(tokenString)")

    // Tokenı sunucuya gönderme
    PushTokenService.shared
        .sendTokenToServer(tokenString) { success in
        if success {
            UserDefaults.standard.set(tokenString,
                forKey: "lastDeviceToken")
        }
    }
}

Sunucu Tarafında Token Yönetimi

Push sisteminin sunucu tarafı, Device Token’ı veritabanında kullanıcı ve ortamla ilişkilendirerek saklamalıdır. Bildirim gönderirken sunucu, URL’de tokenı ve yetkilendirme için bir JWT tokenı (veya sertifika) içeren APNS’ye bir istek oluşturur. Doğru token yönetimi, push bildirimi teslimat oranını kritik şekilde etkiler.

Token Veritabanı Yapısı

Sunucudaki token tablosu en az şunları içermelidir: Device Token (benzersiz), kullanıcı kimliği, ortam (sandbox/production), son güncelleme tarihi ve durum (etkin/etkin değil). Gönderim sırasında hızlı arama için token üzerinde ve bir kullanıcının tüm cihazlarının listesini almak için kullanıcı üzerinde dizin eklenmesi önerilir. Birçok uygulama, bir kullanıcının her biri kendi tokenına sahip birden fazla cihaza sahip olmasına izin verir.

APNS İsteklerinin Yetkilendirilmesi

Push bildirimi göndermek için sunucu, APNS’ye yapılan isteği iki şekilde yetkilendirmelidir. Sertifika tabanlı, Apple Developer Console’da oluşturulan bir SSL sertifikası kullanır. Token tabanlı, sertifikayı yenilemeye gerek kalmadan 30 güne kadar geçerli olan .p8 anahtarıyla bir JWT (JSON Web Token) kullanır. Token tabanlı yetkilendirme daha modern kabul edilir ve Apple tarafından yeni projeler için önerilir.

HTTP/2 APNS İsteği Oluşturma

APNS’ye yapılan istek, HTTP/2 POST yöntemini, /3/device/{device_token} yolunu içeren URL’yi, yetkilendirme başlıklarını ve yükle birlikte JSON gövdesini içerir. apns-topic başlığı uygulamanın paket kimliğini içermelidir. apns-priority teslimat önceliğini belirtir (5 — hemen, 10 — pil tasarruflu). apns-expiration, APNS’nin bildirimi göndermeye çalışacağı dönemden itibaren saniye cinsinden süreyi ayarlar.

// APNS HTTP/2 üzerinden Node.js’de push gönderme örneği
const http2 = require('http2');
const client = http2.connect('https://api.push.apple.com');

const deviceToken = 'abcdef0123456789...';
const payload = JSON.stringify({
    "aps": { "alert": "Hello!", "sound": "default" }
});

const req = client.request({
    ':method': 'POST',
    ':path': `/3/device/${deviceToken}`,
    'apns-topic': 'com.example.app',
    'apns-priority': '10',
    'apns-expiration': '0',
    'authorization': `bearer ${jwtToken}`
});
req.write(payload);
req.end();
req.on('response', (headers) => {
    if (headers[':status'] === '200') {
        console.log('Push başarıyla gönderildi');
    }
});

Toplu Gönderme ve Hız Sınırlama

Çok sayıda cihaza push bildirimi gönderirken, hız kontrolüyle toplu gönderme kullanın. APNS, bağlantı başına saniyede 1500 isteği aşmamanızı önerir. Sınır aşıldığında Apple sunucusu 429 Too Many Requests hatası döndürür. Büyük ölçekli kampanyalar için birden çok bağlantı kullanın ve yükü cihazlar arasında eşit olarak dağıtın.

Token Güncelleme ve Geçersiz Kılma

Device Token kalıcı değildir ve birkaç senaryoda değişebilir, bu da sunucuda bir güncelleme mekanizması gerektirir. Sunucu eski bir tokena push göndermeye devam ederse, APNS 410 Gone hatası döndürür ve tokenın belirtilen ortam için artık geçerli olmadığını belirtir.

Token Ne Zaman Değişir

Apple, Device Token’ın değiştiği birkaç senaryoyu belgeler: kullanıcı uygulamayı yeniden yükler, cihazı bir iCloud yedeğinden geri yükler, yeni bir iOS sürümü yükler veya ağ veya gizlilik ayarlarını sıfırlar. Her durumda, uygulama bir sonraki başlatılışında APNS’den yeni bir token alacaktır. Sunucu, veritabanındaki tokenı güncellemeli, eskisini kaldırıp yenisini kaydetmelidir.

APNS’den 410 Gone Hatasını Ele Alma

Sunucu eski bir tokena push gönderdiğinde, APNS apns-unless-timestamp başlığıyla HTTP 410 döndürür. Bu başlık, tokenın geçersiz hale geldiği zamanı belirtir. Sunucu, bu tokenı veritabanından derhal silmeli veya devre dışı bırakmalıdır, böylece ona tekrar gönderim yapılmaz. 410 hatasını görmezden gelmek kaynakları boşa harcar ve gönderilebilirlik oranını düşürür.

Etkin Olmayan Tokenların Periyodik Temizliği

Token veritabanını güncel tutmak için periyodik temizlik çalıştırılması önerilir. Temizlik betiği, son N gündeki APNS günlüklerini analiz eder, 410 hatası alan tüm tokenları bulur ve bunları veritabanında devre dışı bırakır. Ek olarak, 90 günden uzun süredir kullanıcı etkinliği olmayan tokenlar kaldırılabilir — bunlar yalnızca veritabanı boyutunu artıran gereksiz kayıtlardır.

Toplu Gönderimden Önce Token Doğrulama

Push bildirimlerinin (bültenler, promosyon kampanyaları) toplu gönderiminden önce, tokenların önceden doğrulanması önerilir. APNS toplu token doğrulaması için doğrudan bir API sağlamaz, bu nedenle düşük öncelikli bir test push’u gönderme ve hataları analiz etme stratejisi kullanılır. 410 hatası döndüren tokenlar ana gönderimden çıkarılır.

Device Token Almak İçin Kod Örneği

Swift’te Device Token almanın tam döngüsünü, hata yönetimi ve sunucuya gönderme dahil olmak üzere inceleyelim. Kod şunları kapsar: izin isteme, APNS’ye kayıt, Data’yı onaltılık dizeye dönüştürme, hata yönetimi ve başarısızlık durumunda yeniden denemelerle kendi sunucunuza token gönderme.

import UIKit
import UserNotifications

final class PushNotificationManager: NSObject {

    static let shared = PushNotificationManager()
    private let apiClient = APIClient()
    private var currentToken: String?

    func register() {
        UNUserNotificationCenter.current()
            .requestAuthorization(
                options: [.alert, .badge, .sound]) {
            [weak self] granted, error in
            guard granted else {
                Analytics.log(
                    "Push permission denied")
                return
            }
            DispatchQueue.main.async {
                UIApplication.shared
                    .registerForRemoteNotifications()
            }
        }
    }

    func handleDeviceToken(_ tokenData: Data) {
        let token = tokenData
            .map { String(format: "%02.2hhx", $0) }
            .joined()

        guard token != currentToken else { return }
        currentToken = token
        sendTokenToServer(token)
    }

    func handleRegistrationError(_ error: Error) {
        Analytics.log(
            "Push registration failed: \(error)")

        // Ağ hatalarında gecikmeden sonra yeniden dene
        if let urlError = error as? URLError,
            urlError.code == .notConnectedToInternet {
            DispatchQueue.main.asyncAfter(
                deadline: .now() + 10) { [weak self] in
                self?.register()
            }
        }
    }

    private func sendTokenToServer(_ token: String) {
        let body = PushTokenRequest(
            token: token,
            environment: Environment.current == .debug
                ? "sandbox" : "production",
            osVersion: UIDevice.current.systemVersion,
            locale: Locale.current.identifier
        )
        apiClient.sendToken(body) { [weak self] result in
            if case .success = result {
                self?.currentToken = token
            }
        }
    }
}

Kayıt Sırasında Hata Yönetimi

APNS kaydı sırasındaki hatalar çeşitli nedenlerden kaynaklanabilir. En yaygın olanlar arasında ağ kullanılamazlığı, Xcode’da yanlış sertifika yapılandırması (örneğin, Push Notifications özelliği devre dışı), simülatör kullanımı (push’u desteklemez) veya yanlış sağlama profili bulunur. Üretimde, hataları günlüğe kaydetmek ve mümkünse bir sonraki uygulama başlatılışında kaydı yeniden denemek önemlidir.

Simülatörde Device Token Test Etme

iOS Simülatörü gerçek bir Device Token almayı desteklemez. Simülatörde kaydı test etmek için i386 mimarisi kontrollerini kullanın: bir hata ayıklama yapısında, token almayı simüle edebilir veya sahte nesnelerle UI testleri kullanabilirsiniz. Gerçek push bildirimi testi her zaman Xcode’a bağlı fiziksel bir cihazda yapılır.