Device Token: jak funguje, získání tokenu APNS a aktualizace

Co je Device Token

Device Token (token zařízení) je jedinečný identifikátor ve formě hex řetězce, který APNS (Apple Push Notification Service) generuje pro každou aplikaci na zařízení iOS. Token je klíč, pomocí kterého server odesílá push notifikace na konkrétní zařízení. Bez správného Device Tokenu server nemůže doručit push notifikaci — APNS zamítná požadavek s chybou 400 BadRequest.

Jak se token tvoří

Device Token je vytvářen systémem iOS při prvním kontaktu aplikace s APNS po instalaci. Proces generování zahrnuje kryptografické propojení s identifikátorem aplikace (bundle ID) a jedinečným identifikátorem zařízení (UID), poté APNS vrátí aplikaci 32-bajtový token v hex formátu (64 znaků). Token není trvalý — systém může za určitých podmínek vygenerovat nový.

Role tokenu při doručování push notifikací

Když server odesílá push notifikaci, zahrne Device Token do HTTP/2 požadavku na APNS. APNS ověřuje platnost tokenu: pokud token patří do jiného prostředí (sandbox místo production), vypršel nebo byl odvolán, server Apple vrátí chybu 410 Gone nebo 400 BadRequest. Až po úspěšném ověření tokenu začne APNS doručovat notifikaci na zařízení.

Rozdíl mezi Device Token a ostatními identifikátory

Device Token by neměl být zaměňován s IDFA (Identifier for Advertisers), IDFV (Identifier for Vendor) nebo UID (Unique Device Identifier). IDFA a IDFV se používají pro reklamu a analýzu, UID je hardwarové sériové číslo. Device Token existuje výhradně pro push notifikace a neodhaluje informace o uživateli nebo zařízení mimo APNS.

Jak zařízení získává a registruje token

Proces získání Device Tokenu se skládá z několika povinných kroků, počínaje žádostí o povolení od uživatele a končí předáním tokenu na server. Každý krok je kritický — vynechání kteréhokoli z nich vede k nemožnosti odesílání push notifikací na zařízení.

Žádost o povolení pro notifikace

Prvním krokem aplikace žádá uživatele o povolení pro odesílání notifikací prostřednictvím UNUserNotificationCenter.current().requestAuthorization. Uživatel může souhlasit, odmítnout nebo vybrat volitelné možnosti (alert, badge, sound). Bez výslovného souhlasu uživatele systém nevydá Device Token, i když aplikace zavolá registerForRemoteNotifications. Po získání povolení aplikace zavolá UIApplication.shared.registerForRemoteNotifications(), což zahájí proces registrace v APNS.

Získání tokenu od APNS

Po registraci APNS vrátí token prostřednictvím delegáta AppDelegate: application(_:didRegisterForRemoteNotificationsWithDeviceToken:). Úspěšné volání obsahuje Data objekt s tokenem, který je třeba převést na hex řetězec pro předání serveru. V případě chyby systém zavolá application(_:didFailToRegisterForRemoteNotificationsWithError:) s popisem problému: nesprávná konfigurace certifikátů, chybějící síť nebo nesprávná konfigurace projektu.

Předání tokenu na vlastní server

Po získání tokenu by jej aplikace měla okamžitě předat svému serveru k uložení do databáze. API požadavek zahrnuje token, identifikátor zařízení (pro párování), prostředí (sandbox/production) a volitelně další údaje: verzi OS, model zařízení, jazyk. Doporučuje se opakovat předání tokenu při každém spuštění aplikace, aby měl server vždy aktuální token.

// Žádost o povolení a registrace v APNS
func registerForPushNotifications() {
    UNUserNotificationCenter.current()
        .requestAuthorization(options: [.alert, .sound, .badge]) {
        [weak self] granted, error in
        guard granted else {
            print("Povolení nebylo získáno")
            return
        }
        DispatchQueue.main.async {
            UIApplication.shared
                .registerForRemoteNotifications()
        }
    }
}

// Získání Device Tokenu z APNS
func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    let tokenString = deviceToken
        .map { String(format: "%02.2hhx", $0) }
        .joined()
    print("Device Token: \(tokenString)")

    // Odeslání tokenu na server
    PushTokenService.shared
        .sendTokenToServer(tokenString) { success in
        if success {
            UserDefaults.standard.set(tokenString,
                forKey: "lastDeviceToken")
        }
    }
}

Práce s tokeny na straně serveru

Serverová část push systému musí ukládat Device Token v databázi, asociovaný s uživatelem a prostředím. Při odesílání notifikace server vytvoří požadavek na APNS, včetně tokenu v URL a JWT tokenu (nebo certifikátu) pro autorizaci. Správná správa tokenů kriticky ovlivňuje procento doručení push notifikací.

Struktura databáze tokenů

Tabulka tokenů na serveru by měla obsahovat alespoň: Device Token (jedinečný), identifikátor uživatele, prostředí (sandbox/production), datum poslední aktualizace a stav (aktivní/neaktivní). Doporučuje se přidat index na token pro rychlé vyhledávání při odesílání a na uživatele pro získání seznamu všech zařízení uživatele. Mnoho aplikací umožňuje jednomu uživateli mít více zařízení — každé s vlastním tokenem.

Autorizace požadavků na APNS

Pro odeslání push notifikace musí server autorizovat požadavek na APNS dvěma způsoby. Na základě certifikátu (Certificate-based) používá SSL certifikát vygenerovaný v Apple Developer Console. Metoda na základě tokenu (Token-based) používá JWT s klíčem .p8, který je platný až 30 dní bez nutnosti obnovy certifikátu. Autorizace na základě tokenu je považována za modernější a Apple ji doporučuje pro nové projekty.

Formování HTTP/2 požadavku APNS

Požadavek na APNS zahrnuje HTTP/2 POST metodu, URL s cestou /3/device/{device_token}, autorizační hlavičky a JSON tělo s payloadem. Hlavička apns-topic povinně obsahuje bundle ID aplikace. apns-priority určuje prioritu doručení (5 — okamžitě, 10 — s úsporou baterie). apns-expiration nastavuje čas v sekundách od epochy, do kterého se APNS bude pokoušet doručit notifikaci.

// Příklad odeslání push v Node.js přes 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');
    }
});

Dávkové odesílání a omezování rychlosti

Při odesílání push notifikací na velký počet zařízení použijte dávkové odesílání s kontrolou rychlosti. APNS doporučuje nepřekračovat 1500 požadavků za sekundu na jedno připojení. Při překročení limitu server Apple vrátí chybu 429 Too Many Requests. Pro rozsáhlé zásilky použijte více připojení a rovnoměrně rozdělte zátěž mezi zařízení.

Aktualizace a neplatnost tokenů

Device Token není trvalý a může se změnit v několika scénářích, což vyžaduje mechanismus aktualizace na serveru. Pokud server nadále odesílá push na zastaralý token, APNS vrátí chybu 410 Gone, což znamená, že token již není platný pro dané prostředí.

Kdy se token mění

Apple dokumentuje několik scénářů, při kterých se Device Token mění: uživatel přeinstaluje aplikaci, obnoví zařízení ze zálohy iCloud, nainstaluje novou verzi iOS, a také při resetování síťových nebo soukromých nastavení. V každém případě aplikace při následujícím spuštění obdrží nový token z APNS. Server by měl aktualizovat token v databázi, odstranit starý a uložit nový.

Zpracování chyby 410 Gone od APNS

Když server odešle push na zastaralý token, APNS vrátí HTTP 410 s hlavičkou apns-unless-timestamp. Tato hlavička udává čas, od kterého je token neplatný. Server by měl okamžitě odstranit nebo deaktivovat tento token v databázi, aby na něj znovu neodesílal. Ignorování chyby 410 vede k plýS tvání zdrojů a snížení míry doručení.

Pravidelné čištění neaktivních tokenů

Pro udržení databáze tokenů aktuální se doporučuje provádět pravidelné čištění. Skript čištění analyzuje APNS logy za posledních N dní, najde všechny tokeny, na které byla obdržena chyba 410, a deaktivuje je v databázi. Dodatečně lze odstranit tokeny, u kterých nebyla aktivita uživatele více než 90 dní — to jsou zbytečné záznamy, které pouze zvětšují velikost databáze.

Kontrola tokenů před hromadným odesíláním

Před hromadným odesíláním push notifikací (newsletter, promo kampaň) se doporučuje předběžně zkontrolovat aktuálnost tokenů. APNS neposkytuje přímé API pro dávkovou validaci tokenů, proto se používá strategie odeslání testovacího push s nízkou prioritou a analýzy chyb. Tokeny, které vrátily chybu 410, jsou z hlavního odesílání vyloučeny.

Příklad kódu pro získání Device Tokenu

Podívejme se na úplný cyklus získání Device Tokenu v Swift, včetně zpracování chyb a předání na server. Kód zahrnuje žádost o povolení, registraci v APNS, převod Data na hex řetězec, zpracování chyb a odeslání tokenu na vlastní server s opakováním při neúsPěchu.

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

        // Opakování po zpoždění při síťových chybách
        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
            }
        }
    }
}

Zpracování chyb při registraci

Chyby při registraci v APNS mohou být způsobeny různými příčinami. Nejčastější — chybějící síť, nesprávná konfigurace certifikátů v Xcode (například vypnutá capability Push Notifications), použití simulátoru (který nepodporuje push) nebo nesprávný provisioning profile. V produkci je důležité chyby logovat a pokud je to možné, opakovat registraci při příštím spuštění aplikace.

Testování Device Tokenu na simulátoru

iOS Simulator nepodporuje získání skutečného Device Tokenu. Pro testování registrace na simulátoru použijte kontroly architektury i386: v debug sestavení můžete simulovat získání tokenu nebo použít UI testy s mock objekty. Skutečné testování push notifikací se vždy prováDí na fyzickém zařízení připojeném k Xcode.