Device Token: cum funcționează, obținerea tokenului APNS și actualizarea

Ce este Device Token

Device Token (tokenul dispozitivului) este un identificator unic sub formă de șir hex pe care APNS (serviciul de notificări push Apple) îl generează pentru fiecare aplicație de pe un dispozitiv iOS. Tokenul este cheia prin care serverul trimite notificări push către un anumit dispozitiv. Fără un Device Token corect, serverul nu poate livra notificarea push — APNS respinge cererea cu eroarea 400 BadRequest.

Cum se formează tokenul

Device Token este creat de sistemul iOS la prima apelare a APNS de către aplicație după instalare. Procesul de generare include o legătură criptografică la identificatorul aplicației (bundle ID) și identificatorul unic al dispozitivului (UID), după care APNS returnează aplicației un token de 32 de octeți în format hex (64 de caractere). Tokenul nu este permanent — sistemul poate genera unul nou în anumite condiții.

Rolul tokenului în livrarea notificărilor push

Când serverul trimite o notificare push, include Device Token în cererea HTTP/2 către APNS. APNS verifică validitatea tokenului: dacă tokenul aparține unui alt mediu (sandbox în loc de production), a expirat sau a fost revocat, serverul Apple returnează eroarea 410 Gone sau 400 BadRequest. Doar după validarea cu succes a tokenului, APNS începe livrarea notificării către dispozitiv.

Diferența dintre Device Token și alte identificatoare

Device Token nu trebuie confundat cu IDFA (identificatorul pentru agenții de publicitate), IDFV (identificatorul pentru furnizor) sau UID (identificatorul unic al dispozitivului). IDFA și IDFV sunt utilizați pentru publicitate și analitică, UID este numărul de serie hardware. Device Token există exclusiv pentru notificări push și nu dezvăluie informații despre utilizator sau dispozitiv în afara APNS.

Cum primește și înregistrează dispozitivul tokenul

Procesul de obținere a Device Token constă din mai mulți pași obligatorii, începând cu solicitarea permisiunii de la utilizator și terminând cu transmiterea tokenului către server. Fiecare pas este critic — omiterea oricăruia duce la imposibilitatea trimiterii notificărilor push către dispozitiv.

Solicitarea permisiunii pentru notificări

Primul pas, aplicația solicită utilizatorului permisiunea pentru trimiterea notificărilor prin UNUserNotificationCenter.current().requestAuthorization. Utilizatorul poate accepta, refuza sau alege opțiunile opționale (alert, badge, sound). Fără acordul explicit al utilizatorului, sistemul nu va emite Device Token, chiar dacă aplicația apelează registerForRemoteNotifications. După obținerea permisiunii, aplicația apelează UIApplication.shared.registerForRemoteNotifications(), ceea ce inițiază procesul de înregistrare în APNS.

Obținerea tokenului de la APNS

După înregistrare, APNS returnează tokenul prin delegatul AppDelegate: application(_:didRegisterForRemoteNotificationsWithDeviceToken:). Apelul reușit conține un obiect Data cu tokenul, care trebuie convertit în șir hex pentru transmiterea către server. În caz de eroare, sistemul apelează application(_:didFailToRegisterForRemoteNotificationsWithError:) cu descrierea problemei: configurare incorectă a certificatelor, lipsa rețelei sau configurare incorectă a proiectului.

Transmiterea tokenului către propriul server

După obținerea tokenului, aplicația trebuie să îl transmită imediat propriului server pentru stocare în baza de date. Cererea API include tokenul, identificatorul dispozitivului (pentru asociere), mediul (sandbox/production) și opțional date suplimentare: versiunea OS, modelul dispozitivului, limba. Se recomandă repetarea transmiterii tokenului la fiecare pornire a aplicației, astfel încât serverul să aibă întotdeauna un token actualizat.

// Solicitarea permisiunii și înregistrarea în APNS
func registerForPushNotifications() {
    UNUserNotificationCenter.current()
        .requestAuthorization(options: [.alert, .sound, .badge]) {
        [weak self] granted, error in
        guard granted else {
            print("Permisiunea nu a fost obținută")
            return
        }
        DispatchQueue.main.async {
            UIApplication.shared
                .registerForRemoteNotifications()
        }
    }
}

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

    // Trimite tokenul la server
    PushTokenService.shared
        .sendTokenToServer(tokenString) { success in
        if success {
            UserDefaults.standard.set(tokenString,
                forKey: "lastDeviceToken")
        }
    }
}

Gestionarea tokenurilor pe partea serverului

Partea server a sistemului de notificări push trebuie să stocheze Device Token în baza de date, asociat cu utilizatorul și mediul. La trimiterea notificării, serverul formează o cerere către APNS, incluzând tokenul în URL și tokenul JWT (sau certificatul) pentru autorizare. Gestionarea corectă a tokenurilor influențează critic procentul de livrare a notificărilor push.

Structura bazei de date a tokenurilor

Tabelul tokenurilor pe server trebuie să conțină cel puțin: Device Token (unic), identificatorul utilizatorului, mediul (sandbox/production), data ultimei actualizări și starea (activ/inactiv). Se recomandă adăugarea unui index pe token pentru căutare rapidă la trimitere și pe utilizator pentru obținerea listei tuturor dispozitivelor utilizatorului. Multe aplicații permit unui utilizator să aibă mai multe dispozitive — fiecare cu propriul token.

Autorizarea cererilor către APNS

Pentru trimiterea notificării push, serverul trebuie să autorizeze cererea către APNS în două moduri. Pe bază de certificat (Certificate-based) utilizează un certificat SSL generat în Apple Developer Console. Metoda pe bază de token (Token-based) utilizează JWT cu o cheie .p8, care este valabilă până la 30 de zile fără a fi nevoie de actualizarea certificatului. Autorizarea pe bază de token este considerată mai modernă și este recomandată de Apple pentru proiecte noi.

Formarea cererii HTTP/2 APNS

Cererea către APNS include metoda POST HTTP/2, URL-ul cu calea /3/device/{device_token}, anteturile de autorizare și corpul JSON cu payloadul. Antetul apns-topic conține obligatoriu bundle ID-ul aplicației. apns-priority specifică prioritatea livrării (5 — imediat, 10 — cu economisirea bateriei). apns-expiration stabilește timpul în secunde de la epoch până la care APNS va încerca să livreze notificarea.

// Exemplu de trimitere push în Node.js prin APNS HTTP/2
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 sent successfully');
    }
});

Trimiterea în lot și limitarea ratei

La trimiterea notificărilor push către un număr mare de dispozitive, utilizați trimiterea în lot cu controlul vitezei. APNS recomandă să nu depășiți 1500 de cereri pe secundă per conexiune. La depășirea limitei, serverul Apple returnează eroarea 429 Too Many Requests. Pentru trimiteri la scară largă, utilizați mai multe conexiuni și distribuiți sarcina uniform între dispozitive.

Actualizarea și invalidarea tokenurilor

Device Token nu este permanent și se poate modifica în mai multe scenarii, ceea ce necesită un mecanism de actualizare pe server. Dacă serverul continuă să trimită notificări push către tokenul învechit, APNS returnează eroarea 410 Gone, indicând că tokenul nu mai este valabil pentru acel mediu.

Când se modifică tokenul

Apple documentează mai multe scenarii în care Device Token se modifică: utilizatorul reinstalează aplicația, restaurează dispozitivul din backup iCloud, instalează o nouă versiune iOS, precum și la resetarea setărilor de rețea sau confidențialitate. În fiecare caz, aplicația la următoarea pornire va primi un nou token de la APNS. Serverul trebuie să actualizeze tokenul în baza de date, ștergându-l pe cel vechi și salvându-l pe cel nou.

Gestionarea erorii 410 Gone de la APNS

Când serverul trimite un push către un token învechit, APNS returnează HTTP 410 cu antetul apns-unless-timestamp. Acest antet indică momentul de la care tokenul a devenit invalid. Serverul trebuie să șteargă sau să dezactiveze imediat acest token în baza de date pentru a nu mai trimite la el. Ignorarea erorii 410 duce la risipirea resurselor și scăderea ratei de livrare.

Curățarea periodică a tokenurilor inactive

Pentru a menține baza de date a tokenurilor actualizată, se recomandă efectuarea unei curățări periodice. Scriptul de curățare analizează logurile APNS din ultimele N zile, găsește toate tokenurile pentru care s-a primit eroarea 410 și le dezactivează în baza de date. Suplimentar, se pot șterge tokenurile pentru care nu a existat activitate a utilizatorului de mai mult de 90 de zile — acestea sunt înregistrări inutile care doar măresc dimensiunea bazei de date.

Verificarea tokenurilor înainte de trimiterea în masă

Înainte de trimiterea în masă a notificărilor push (newsletter, campanie promoțională), se recomandă verificarea prealabilă a actualității tokenurilor. APNS nu oferă o API directă pentru validarea în lot a tokenurilor, de aceea se utilizează strategia de trimitere a unui push de test cu prioritate scăzută și analiza erorilor. Tokenurile care au returnat eroarea 410 sunt excluse din trimiterea principală.

Exemplu de cod pentru obținerea Device Token

Să analizăm ciclul complet de obținere a Device Token în Swift, inclusiv gestionarea erorilor și transmiterea către server. Codul acoperă solicitarea permisiunii, înregistrarea în APNS, conversia Data în șir hex, gestionarea erorilor și trimiterea tokenului către propriul server cu reîncercări în caz de eșec.

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)")

        // Reîncercare după întârziere la erori de rețea
        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
            }
        }
    }
}

Gestionarea erorilor la înregistrare

Erorile la înregistrarea în APNS pot fi cauzate de diverse motive. Cele mai frecvente — lipsa rețelei, configurarea incorectă a certificatelor în Xcode (de exemplu, capability Push Notifications dezactivat), utilizarea simulatorului (care nu suportă notificări push) sau un provisioning profile incorect. În producție, este important să logați erorile și, dacă este posibil, să repetați înregistrarea la următoarea pornire a aplicației.

Testarea Device Token pe simulator

Simulatorul iOS nu suportă obținerea unui Device Token real. Pentru testarea înregistrării pe simulator, utilizați verificări de arhitectură i386: în versiunea debug puteți simula obținerea tokenului sau utilizați teste UI cu obiecte mock. Testarea reală a notificărilor push se efectuează întotdeauna pe un dispozitiv fizic conectat la Xcode.