Device Token: Funktionsweise, Abruf des APNS-Tokens und Aktualisierung

Was ist ein Device Token

Device Token (Gerätetoken) ist eine eindeutige Kennung in Form eines Hex-Strings, den APNS (Apple Push Notification Service) für jede App auf einem iOS-Gerät generiert. Der Token ist der Schlüssel, mit dem der Server Push-Benachrichtigungen an ein bestimmtes Gerät sendet. Ohne einen gültigen Device Token kann der Server keine Push-Benachrichtigungen zustellen — APNS lehnt die Anfrage mit einem 400 BadRequest-Fehler ab.

Wie der Token gebildet wird

Der Device Token wird vom iOS-System erstellt, wenn die App nach der Installation zum ersten Mal Kontakt mit APNS aufnimmt. Der Generierungsprozess umfasst eine kryptografische Bindung an die Bundle-ID der App und die eindeutige Gerätekennung (UID), woraufhin APNS der App einen 32-Byte-Token im Hex-Format (64 Zeichen) zurückgibt. Der Token ist nicht dauerhaft — das System kann unter bestimmten Bedingungen einen neuen Token generieren.

Rolle des Tokens bei der Zustellung von Push-Benachrichtigungen

Wenn der Server eine Push-Benachrichtigung sendet, fügt er den Device Token in die HTTP/2-Anfrage an APNS ein. APNS validiert den Token: Wenn der Token zu einer anderen Umgebung (Sandbox statt Production) gehört, abgelaufen oder widerrufen ist, gibt der Apple-Server einen 410 Gone- oder 400 BadRequest-Fehler zurück. Erst nach erfolgreicher Token-Validierung beginnt APNS mit der Zustellung der Benachrichtigung an das Gerät.

Unterschied zwischen Device Token und anderen Kennungen

Device Token sollte nicht mit IDFA (Identifier for Advertisers), IDFV (Identifier for Vendor) oder UID (Unique Device Identifier) verwechselt werden. IDFA und IDFV werden für Werbung und Analysen verwendet, UID ist eine Hardware-Seriennummer. Device Token existiert ausschließlich für Push-Benachrichtigungen und gibt keine Informationen über den Benutzer oder das Gerät außerhalb von APNS preis.

Wie das Gerät den Token erhält und registriert

Der Prozess zum Abrufen eines Device Tokens besteht aus mehreren obligatorischen Schritten, von der Anforderung der Benutzerberechtigung bis zum Senden des Tokens an den Server. Jeder Schritt ist entscheidend — das Überspringen eines davon führt dazu, dass keine Push-Benachrichtigungen an das Gerät gesendet werden können.

Anfordern der Benachrichtigungsberechtigung

Der erste Schritt besteht darin, dass die App über UNUserNotificationCenter.current().requestAuthorization die Berechtigung des Benutzers zum Senden von Benachrichtigungen anfordert. Der Benutzer kann zustimmen, ablehnen oder optionale Optionen (Alert, Badge, Sound) auswählen. Ohne ausdrückliche Zustimmung des Benutzers gibt das System keinen Device Token aus, selbst wenn die App registerForRemoteNotifications aufruft. Nach Erhalt der Berechtigung ruft die App UIApplication.shared.registerForRemoteNotifications() auf, was den Registrierungsprozess bei APNS initiiert.

Abrufen des Tokens von APNS

Nach der Registrierung gibt APNS den Token über den AppDelegate zurück: application(_:didRegisterForRemoteNotificationsWithDeviceToken:). Ein erfolgreicher Aufruf enthält ein Data-Objekt mit dem Token, das für die Übertragung an den Server in einen Hex-String konvertiert werden muss. Im Fehlerfall ruft das System application(_:didFailToRegisterForRemoteNotificationsWithError:) mit einer Beschreibung des Problems auf: falsche Zertifikatskonfiguration, Netzwerkverfügbarkeit oder falsche Projektkonfiguration.

Senden des Tokens an Ihren Server

Nach Erhalt des Tokens sollte die App ihn sofort an ihren Server senden, um ihn in der Datenbank zu speichern. Die API-Anfrage enthält den Token, die Gerätekennung (für die Zuordnung), die Umgebung (Sandbox/Production) und optional zusätzliche Daten: OS-Version, Gerätemodell, Sprache. Es wird empfohlen, den Token bei jedem App-Start erneut zu senden, damit der Server immer einen aktuellen Token hat.

// Berechtigung anfordern und bei APNS registrieren
func registerForPushNotifications() {
    UNUserNotificationCenter.current()
        .requestAuthorization(options: [.alert, .sound, .badge]) {
        [weak self] granted, error in
        guard granted else {
            print("Berechtigung nicht erteilt")
            return
        }
        DispatchQueue.main.async {
            UIApplication.shared
                .registerForRemoteNotifications()
        }
    }
}

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

    // Token an Server senden
    PushTokenService.shared
        .sendTokenToServer(tokenString) { success in
        if success {
            UserDefaults.standard.set(tokenString,
                forKey: "lastDeviceToken")
        }
    }
}

Serverseitige Token-Verwaltung

Die Serverseite des Push-Systems muss den Device Token in der Datenbank speichern, verknüpft mit dem Benutzer und der Umgebung. Beim Senden einer Benachrichtigung erstellt der Server eine Anfrage an APNS, die den Token in der URL und ein JWT-Token (oder Zertifikat) zur Autorisierung enthält. Eine korrekte Token-Verwaltung wirkt sich entscheidend auf die Zustellrate von Push-Benachrichtigungen aus.

Struktur der Token-Datenbank

Die Token-Tabelle auf dem Server sollte mindestens enthalten: Device Token (eindeutig), Benutzer-ID, Umgebung (Sandbox/Production), Datum der letzten Aktualisierung und Status (aktiv/inaktiv). Es wird empfohlen, einen Index auf dem Token für schnelle Suche beim Senden und auf dem Benutzer zum Abrufen der Liste aller Geräte eines Benutzers hinzuzufügen. Viele Apps erlauben einem Benutzer mehrere Geräte — jedes mit seinem eigenen Token.

Autorisierung von APNS-Anfragen

Um eine Push-Benachrichtigung zu senden, muss der Server die Anfrage an APNS auf zwei Arten autorisieren. Zertifikatsbasiert verwendet ein in der Apple Developer Console generiertes SSL-Zertifikat. Token-basiert verwendet ein JWT (JSON Web Token) mit einem .p8-Schlüssel, der bis zu 30 Tage ohne Erneuerung des Zertifikats gültig ist. Die tokenbasierte Autorisierung gilt als moderner und wird von Apple für neue Projekte empfohlen.

Erstellen einer HTTP/2-APNS-Anfrage

Die Anfrage an APNS enthält die HTTP/2-POST-Methode, eine URL mit dem Pfad /3/device/{device_token}, Autorisierungsheader und einen JSON-Body mit der Nutzlast. Der apns-topic-Header muss die Bundle-ID der App enthalten. apns-priority gibt die Zustellungspriorität an (5 — sofort, 10 — batterieschonend). apns-expiration legt die Zeit in Sekunden seit der Epoche fest, bis zu der APNS versucht, die Benachrichtigung zuzustellen.

// Beispiel zum Senden von Push auf Node.js über 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 erfolgreich gesendet');
    }
});

Batch-Versand und Drosselung

Beim Senden von Push-Benachrichtigungen an eine große Anzahl von Geräten verwenden Sie den Batch-Versand mit Geschwindigkeitskontrolle. APNS empfiehlt, nicht mehr als 1500 Anfragen pro Sekunde pro Verbindung zu überschreiten. Bei Überschreitung des Limits gibt der Apple-Server einen 429 Too Many Requests-Fehler zurück. Verwenden Sie für groß angelegte Kampagnen mehrere Verbindungen und verteilen Sie die Last gleichmäßig auf die Geräte.

Token-Aktualisierung und Ungültigmachung

Device Token ist nicht dauerhaft und kann sich in mehreren Szenarien ändern, was einen Aktualisierungsmechanismus auf dem Server erfordert. Wenn der Server weiterhin Push-Benachrichtigungen an einen veralteten Token sendet, gibt APNS einen 410 Gone-Fehler zurück, der angibt, dass der Token für die jeweilige Umgebung nicht mehr gültig ist.

Wann sich der Token ändert

Apple dokumentiert mehrere Szenarien, in denen sich der Device Token ändert: Der Benutzer installiert die App neu, stellt das Gerät aus einem iCloud-Backup wieder her, installiert eine neue iOS-Version oder setzt Netzwerk- oder Datenschutzeinstellungen zurück. In jedem Fall erhält die App beim nächsten Start einen neuen Token von APNS. Der Server muss den Token in der Datenbank aktualisieren, den alten entfernen und den neuen speichern.

Behandlung des 410 Gone-Fehlers von APNS

Wenn der Server eine Push-Benachrichtigung an einen veralteten Token sendet, gibt APNS HTTP 410 mit dem apns-unless-timestamp-Header zurück. Dieser Header gibt die Zeit an, nach der der Token ungültig wurde. Der Server muss diesen Token sofort in der Datenbank löschen oder deaktivieren, um ein erneutes Senden an ihn zu vermeiden. Das Ignorieren des 410-Fehlers verschwendet Ressourcen und verringert die Zustellbarkeitsrate.

Regelmäßige Bereinigung inaktiver Token

Um die Token-Datenbank aktuell zu halten, wird empfohlen, regelmäßige Bereinigungen durchzuführen. Das Bereinigungsskript analysiert die APNS-Protokolle der letzten N Tage, findet alle Token, die einen 410-Fehler erhalten haben, und deaktiviert sie in der Datenbank. Zusätzlich können Token ohne Benutzeraktivität seit mehr als 90 Tagen entfernt werden — dies sind nutzlose Datensätze, die nur die Datenbankgröße erhöhen.

Token-Validierung vor dem Massenversand

Vor dem Massenversand von Push-Benachrichtigungen (Newsletter, Werbekampagnen) wird empfohlen, die Token vorab zu validieren. APNS bietet keine direkte API für die Batch-Token-Validierung, daher wird die Strategie verwendet, einen Test-Push mit niedriger Priorität zu senden und Fehler zu analysieren. Token, die einen 410-Fehler zurückgeben, werden vom Hauptversand ausgeschlossen.

Codebeispiel zum Abrufen eines Device Tokens

Lassen Sie uns den vollständigen Zyklus zum Abrufen eines Device Tokens in Swift durchgehen, einschließlich Fehlerbehandlung und Senden an den Server. Der Code umfasst das Anfordern der Berechtigung, die Registrierung bei APNS, die Konvertierung von Data in einen Hex-String, die Fehlerbehandlung und das Senden des Tokens an Ihren eigenen Server mit erneuten Versuchen bei Fehlschlag.

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

        // Wiederholung nach Verzögerung bei Netzwerkfehlern
        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
            }
        }
    }
}

Fehlerbehandlung während der Registrierung

Fehler während der APNS-Registrierung können verschiedene Ursachen haben. Die häufigsten sind Netzwerkverfügbarkeit, falsche Zertifikatskonfiguration in Xcode (z. B. deaktivierte Push Notifications-Funktion), Verwendung des Simulators (der Push nicht unterstützt) oder ein falsches Provisioning-Profil. In der Produktion ist es wichtig, Fehler zu protokollieren und wenn möglich die Registrierung beim nächsten App-Start zu wiederholen.

Testen des Device Tokens im Simulator

Der iOS-Simulator unterstützt den Empfang eines echten Device Tokens nicht. Zum Testen der Registrierung im Simulator verwenden Sie i386-Architekturprüfungen: In einem Debug-Build können Sie den Token-Empfang simulieren oder UI-Tests mit Mock-Objekten verwenden. Echte Push-Benachrichtigungstests werden immer auf einem physischen Gerät durchgeführt, das mit Xcode verbunden ist.