Device Token: működése, APNS token megszerzése és frissítése

Mi az a Device Token

Device Token (eszköztoken) egy egyedi azonosító hex karaktersorozat formájában, amelyet az APNS (Apple Push Notification Service) generál minden alkalmazáshoz egy iOS-eszközön. A token az a kulcs, amellyel a szerver push üzeneteket küld egy adott eszközre. Helyes Device Token nélkül a szerver nem tud push üzenetet kézbesíteni — az APNS elutasítja a kérést 400 BadRequest hibával.

Hogyan jön létre a token

A Device Tokent az iOS rendszer hozza létre az alkalmazás APNS-sel való első kapcsolatfelvételekor a telepítés után. A generálási folyamat kriptográfiai kapcsolódást tartalmaz az alkalmazás azonosítójához (bundle ID) és az eszköz egyedi azonosítójához (UID), ezután az APNS visszaadja az alkalmazásnak a 32 bájtos tokent hex formátumban (64 karakter). A token nem állandó — a rendszer bizonyos körülmények között újat generálhat.

A token szerepe a push üzenetek kézbesítésében

Amikor a szerver push üzenetet küld, belefoglalja a Device Tokent az APNS-nek szóló HTTP/2 kérésbe. Az APNS ellenőrzi a token érvényességét: ha a token egy másik környezethez tartozik (sandbox a production helyett), lejárt vagy visszavonták, az Apple szerver 410 Gone vagy 400 BadRequest hibát ad vissza. Csak a token sikeres érvényesítése után kezdi meg az APNS az üzenet kézbesítését az eszközre.

A Device Token és más azonosítók közötti különbség

A Device Token nem tévesztendő össze az IDFA-val (Identifier for Advertisers), IDFV-vel (Identifier for Vendor) vagy UID-val (Unique Device Identifier). Az IDFA és IDFV célja a reklámozás és analitika, az UID hardver sorozatszám. A Device Token kizárólag push üzenetekhez létezik, és nem fedi fel a felhasználóról vagy eszközről szóló információkat az APNS-en kívül.

Hogyan kapja meg és regisztrálja az eszköz a tokent

A Device Token megszerzésének folyamata több kötelező lépésből áll, a felhasználó engedélyének kérésétől a token szerverre való elküldésig. Minden lépés kritikus — bármelyik kihagyása lehetetlenné teszi a push üzenetek küldését az eszközre.

Engedély kérése az értesítésekhez

Első lépésként az alkalmazás engedélyt kér a felhasználótól az értesítések küldéséhez az UNUserNotificationCenter.current().requestAuthorization segítségével. A felhasználó beleegyezhet, megtagadhatja vagy választhat opcionális opciókat (alert, badge, sound). A felhasználó kifejezett beleegyezése nélkül a rendszer nem bocsátja ki a Device Tokent, még akkor sem, ha az alkalmazás meghívja a registerForRemoteNotifications függvényt. Az engedély megszerzése után az alkalmazás meghívja az UIApplication.shared.registerForRemoteNotifications() függvényt, ami elindítja az APNS-ben történő regisztráció folyamatát.

Token fogadása az APNS-től

A regisztráció után az APNS a tokent az AppDelegate delegáltján keresztül adja vissza: application(_:didRegisterForRemoteNotificationsWithDeviceToken:). A sikeres hívás egy Data objektumot tartalmaz a tokennel, amelyet hex karaktersorozattá kell alakítani a szerverre történő továbbításhoz. Hiba esetén a rendszer meghívja az application(_:didFailToRegisterForRemoteNotificationsWithError:) függvényt a probléma leírásával: helytelen tanúsítványkonfiguráció, nincs hálózat vagy a projekt helytelen konfigurációja.

Token elküldése a saját szerverre

A token kézhez vétele után az alkalmazásnak azonnal el kell küldenie azt a saját szerverére az adatbázisban történő tároláshoz. Az API kérés tartalmazza a tokent, az eszköz azonosítóját (az összerendeléshez), a környezetet (sandbox/production) és opcionálisan további adatokat: OS verzió, eszköz modell, nyelv. Javasolt a token küldését minden alkalmazásindításkor megismételni, hogy a szerver mindig aktuális tokennel rendelkezzen.

// Engedély kérése és regisztráció az APNS-ben
func registerForPushNotifications() {
    UNUserNotificationCenter.current()
        .requestAuthorization(options: [.alert, .sound, .badge]) {
        [weak self] granted, error in
        guard granted else {
            print("Az engedély nem érkezett meg")
            return
        }
        DispatchQueue.main.async {
            UIApplication.shared
                .registerForRemoteNotifications()
        }
    }
}

// Device Token fogadása az APNS-től
func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    let tokenString = deviceToken
        .map { String(format: "%02.2hhx", $0) }
        .joined()
    print("Device Token: \(tokenString)")

    // Token küldése a szerverre
    PushTokenService.shared
        .sendTokenToServer(tokenString) { success in
        if success {
            UserDefaults.standard.set(tokenString,
                forKey: "lastDeviceToken")
        }
    }
}

Tokenek kezelése a szerver oldalán

A push rendszer szerver része a Device Tokent az adatbázisban kell tárolnia, a felhasználóhoz és környezethez kapcsolva. Értesítés küldésekor a szerver kérést küld az APNS-nek, beleértve a tokent az URL-be és a JWT tokent (vagy tanúsítványt) a hitelesítéshez. A tokenek helyes kezelése kritikus hatással van a push üzenetek kézbesítési arányára.

A token adatbázis struktúrája

A szerveren lévő token táblázatnak legalább a következőket kell tartalmaznia: Device Token (egyedi), felhasználó azonosító, környezet (sandbox/production), utolsó frissítés dátuma és állapot (aktív/inaktív). Javasolt index hozzáadása a tokenre a gyors kereséshez küldéskor és a felhasználóra a felhasználó összes eszközének listájához. Sok alkalmazás lehetővé teszi, hogy egy felhasználónak több eszköze legyen — mindegyik saját tokenekkel.

APNS kérések hitelesítése

Push üzenet küldéséhez a szervernek két módon kell hitelesítenie a kérést az APNS felé. Tanúsítvány alapú (Certificate-based) az Apple Developer Console-ban generált SSL tanúsítványt használ. A token alapú módszer (Token-based) JWT-t használ .p8 kulccsal, amely 30 napig érvényes a tanúsítvány frissítésének szükségessége nélkül. A token alapú hitelesítés modernebbnek számít, és az Apple új projektekhez ajánlja.

HTTP/2 APNS kérés összeállítása

Az APNS-nek szóló kérés tartalmazza a HTTP/2 POST módszert, az URL-t a /3/device/{device_token} úttal, a hitelesítési fejléceket és a JSON törzset a payloaddal. Az apns-topic fejléc kötelezően tartalmazza az alkalmazás bundle ID-ját. Az apns-priority megadja a kézbesítés prioritását (5 — azonnal, 10 — akkumulátor kímélés). Az apns-expiration beállítja az időt másodpercekben az epoch-tól, ameddig az APNS megpróbálja kézbesíteni az üzenetet.

// Példa push küldésre Node.js-ben APNS HTTP/2-n keresztül
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');
    }
});

Küldés tételekben és sebességkorlátozás

Nagyszámú eszközre történő push üzenetküldéskor használja a tételekben történő küldést sebességellenőrzéssel. Az APNS javasolja, hogy ne haladja meg a másodpercenkénti 1500 kérést kapcsolatonként. A korlát túllépésekor az Apple szerver 429 Too Many Requests hibát ad vissza. Nagyméretű küldeményekhez használjon több kapcsolatot, és ossza el egyenletesen a terhelést az eszközök között.

Tokenek frissítése és érvénytelenítése

A Device Token nem állandó, és több forgatókönyvben megváltozhat, ami frissítési mechanizmust igényel a szerveren. Ha a szerver továbbra is push-t küld az elavult tokenre, az APNS 410 Gone hibát ad vissza, jelezve, hogy a token már nem érvényes az adott környezetben.

Mikor változik a token

Az Apple dokumentálja azokat a forgatókönyveket, amikor a Device Token megváltozik: a felhasználó újratelepíti az alkalmazást, visszaállítja az eszközt iCloud biztonsági mentésből, új iOS verziót telepít, valamint a hálózati vagy adatvédelmi beállítások visszaállításakor. Minden esetben az alkalmazás a következő indításkor új tokent kap az APNS-től. A szervernek frissítenie kell a tokent az adatbázisban, törölve a régit és elmentve az újat.

410 Gone hiba kezelése az APNS-től

Amikor a szerver push-t küld egy elavult tokenre, az APNS HTTP 410-et ad vissza az apns-unless-timestamp fejléccel. Ez a fejléc azt az időpontot jelzi, amikor a token érvénytelené vált. A szervernek azonnal törölnie vagy deaktiválnia kell ezt a tokent az adatbázisban, hogy ne küldjön rá újra. A 410-es hiba figyelmen kívül hagyása erőforrások pazarlásához és a kézbesítési arány csökkenéséhez vezet.

Inaktív tokenek időszakos tisztítása

A token adatbázis naprakészen tartásához javasolt időszakos tisztítást végezni. A tisztító szkript elemzi az APNS naplókat az elmúlt N napból, megtalálja az összes tokent, amelyekre 410-es hibát kapott, és deaktiválja azokat az adatbázisban. Ezenkívül törölhetők azok a tokenek, amelyekhez több mint 90 napja nem kapcsolódott felhasználói aktivitás — ezek haszontalan rekordok, amelyek csak növelik az adatbázis méretét.

Tokenek ellenőrzése tömeges küldés előtt

Push üzenetek tömeges küldése (hírlevél, promóciós kampány) előtt javasolt előzetesen ellenőrizni a tokenek aktualitását. Az APNS nem biztosít közvetlen API-t tokenek tételes érvényesítéséhez, ezért az alacsony prioritású teszt push küldésének és a hibaelemzésnek a stratégiáját használják. Azok a tokenek, amelyek 410-es hibát adtak vissza, kizárásra kerülnek a fő küldésből.

Példakód a Device Token megszerzéséhez

Tekintsük át a Device Token megszerzésének teljes ciklusát Swift-ben, beleértve a hibakezelést és a szerverre történő küldést. A kód lefedi az engedély kérését, az APNS-ben történő regisztrációt, a Data hex karaktersorozattá alakítását, a hibakezelést és a token elküldését a saját szerverre újrapróbálkozásokkal sikertelenség esetén.

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

        // Újrapróbálkozás késleltetés után hálózati hibáknál
        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
            }
        }
    }
}

Hibakezelés regisztrációnál

Az APNS-ben történő regisztráció hibáit különféle okok okozhatják. A leggyakoribbak — nincs hálózat, helytelen tanúsítvány konfiguráció az Xcode-ban (például a Push Notifications képesség ki van kapcsolva), a szimulátor használata (amely nem támogatja a push-t) vagy helytelen provisioning profile. Éles környezetben fontos naplózni a hibákat, és ha lehetséges, megismételni a regisztrációt az alkalmazás következő indításakor.

Device Token tesztelése szimulátoron

Az iOS Simulator nem támogatja a valódi Device Token megszerzését. A regisztráció szimulátoron történő teszteléséhez használjon i386 architektúra ellenőrzéseket: a debug építésben szimulálhatja a token megszerzését vagy használhat UI teszteket mock objektumokkal. A push üzenetek valódi tesztelése mindig az Xcode-hoz csatlakoztatott fizikai eszközön történik.