Device Token : fonctionnement, obtention du jeton APNS et mise à jour

Qu’est-ce qu’un Device Token

Device Token (jeton d’appareil) est un identifiant unique sous forme de chaîne hexadécimale qu’APNS (Apple Push Notification Service) génère pour chaque application sur un appareil iOS. Le jeton est la clé par laquelle le serveur envoie des notifications push à un appareil spécifique. Sans Device Token valide, le serveur ne peut pas livrer les notifications push — APNS rejette la requête avec une erreur 400 BadRequest.

Comment le jeton est formé

Le Device Token est créé par le système iOS lors du premier contact de l’application avec APNS après l’installation. Le processus de génération implique une liaison cryptographique avec le bundle ID de l’application et l’identifiant unique de l’appareil (UID), après quoi APNS renvoie à l’application un jeton de 32 octets au format hexadécimal (64 caractères). Le jeton n’est pas permanent — le système peut en générer un nouveau sous certaines conditions.

Rôle du jeton dans la livraison des notifications push

Lorsque le serveur envoie une notification push, il inclut le Device Token dans la requête HTTP/2 à APNS. APNS valide le jeton : si le jeton appartient à un autre environnement (sandbox au lieu de production), a expiré ou a été révoqué, le serveur Apple renvoie une erreur 410 Gone ou 400 BadRequest. Ce n’est qu’après une validation réussie du jeton qu’APNS commence à livrer la notification à l’appareil.

Différence entre Device Token et autres identifiants

Device Token ne doit pas être confondu avec IDFA (Identifier for Advertisers), IDFV (Identifier for Vendor) ou UID (Unique Device Identifier). IDFA et IDFV sont utilisés pour la publicité et les analyses, UID est un numéro de série matériel. Device Token existe exclusivement pour les notifications push et ne divulgue pas d’informations sur l’utilisateur ou l’appareil en dehors d’APNS.

Comment l’appareil obtient et enregistre le jeton

Le processus d’obtention d’un Device Token comprend plusieurs étapes obligatoires, de la demande d’autorisation à l’utilisateur jusqu’à l’envoi du jeton au serveur. Chaque étape est critique — en sauter une rend impossible l’envoi de notifications push à l’appareil.

Demande d’autorisation de notification

La première étape consiste pour l’application à demander à l’utilisateur l’autorisation d’envoyer des notifications via UNUserNotificationCenter.current().requestAuthorization. L’utilisateur peut accepter, refuser ou sélectionner des options facultatives (alerte, badge, son). Sans consentement explicite de l’utilisateur, le système n’émettra pas de Device Token, même si l’application appelle registerForRemoteNotifications. Après avoir obtenu l’autorisation, l’application appelle UIApplication.shared.registerForRemoteNotifications(), ce qui lance le processus d’inscription auprès d’APNS.

Obtention du jeton auprès d’APNS

Après l’inscription, APNS renvoie le jeton via le délégué AppDelegate : application(_:didRegisterForRemoteNotificationsWithDeviceToken:). Un appel réussi contient un objet Data avec le jeton, qui doit être converti en chaîne hexadécimale pour la transmission au serveur. En cas d’erreur, le système appelle application(_:didFailToRegisterForRemoteNotificationsWithError:) avec une description du problème : configuration de certificat incorrecte, indisponibilité du réseau ou configuration de projet incorrecte.

Envoi du jeton à votre serveur

Après avoir reçu le jeton, l’application doit l’envoyer immédiatement à son serveur pour le stocker dans la base de données. La requête API inclut le jeton, l’identifiant de l’appareil (pour le mappage), l’environnement (sandbox/production) et éventuellement des données supplémentaires : version de l’OS, modèle de l’appareil, langue. Il est recommandé de renvoyer le jeton à chaque lancement de l’application afin que le serveur ait toujours un jeton à jour.

// Demander l’autorisation et s’inscrire auprès d’APNS
func registerForPushNotifications() {
    UNUserNotificationCenter.current()
        .requestAuthorization(options: [.alert, .sound, .badge]) {
        [weak self] granted, error in
        guard granted else {
            print("Autorisation non accordée")
            return
        }
        DispatchQueue.main.async {
            UIApplication.shared
                .registerForRemoteNotifications()
        }
    }
}

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

    // Envoyer le jeton au serveur
    PushTokenService.shared
        .sendTokenToServer(tokenString) { success in
        if success {
            UserDefaults.standard.set(tokenString,
                forKey: "lastDeviceToken")
        }
    }
}

Gestion des jetons côté serveur

Le côté serveur du système push doit stocker le Device Token dans la base de données, associé à l’utilisateur et à l’environnement. Lors de l’envoi d’une notification, le serveur forme une requête à APNS, incluant le jeton dans l’URL et un jeton JWT (ou certificat) pour l’autorisation. Une gestion correcte des jetons affecte de manière critique le taux de livraison des notifications push.

Structure de la base de données des jetons

La table des jetons sur le serveur doit contenir au minimum : Device Token (unique), ID utilisateur, environnement (sandbox/production), date de dernière mise à jour et statut (actif/inactif). Il est recommandé d’ajouter un index sur le jeton pour une recherche rapide lors de l’envoi et sur l’utilisateur pour obtenir la liste de tous les appareils d’un utilisateur. De nombreuses applications permettent à un utilisateur d’avoir plusieurs appareils — chacun avec son propre jeton.

Autorisation des requêtes à APNS

Pour envoyer une notification push, le serveur doit autoriser la requête à APNS de deux manières. Basée sur certificat utilise un certificat SSL généré dans Apple Developer Console. Basée sur jeton utilise un JWT (JSON Web Token) avec une clé .p8 valide jusqu’à 30 jours sans nécessité de renouveler le certificat. L’autorisation basée sur jeton est considérée comme plus moderne et est recommandée par Apple pour les nouveaux projets.

Formation d’une requête HTTP/2 APNS

La requête à APNS inclut la méthode HTTP/2 POST, une URL avec le chemin /3/device/{device_token}, des en-têtes d’autorisation et un corps JSON avec la charge utile. L’en-tête apns-topic doit contenir le bundle ID de l’application. apns-priority indique la priorité de livraison (5 — immédiatement, 10 — avec économie de batterie). apns-expiration définit le temps en secondes depuis l’époque jusqu’auquel APNS tentera de livrer la notification.

// Exemple d’envoi de push sur Node.js via 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 envoyé avec succès');
    }
});

Envoi par lots et limitation de débit

Lors de l’envoi de notifications push à un grand nombre d’appareils, utilisez l’envoi par lots avec contrôle de débit. APNS recommande de ne pas dépasser 1500 requêtes par seconde par connexion. En cas de dépassement de la limite, le serveur Apple renvoie une erreur 429 Too Many Requests. Pour les campagnes à grande échelle, utilisez plusieurs connexions et répartissez la charge uniformément entre les appareils.

Mise à jour et invalidation des jetons

Device Token n’est pas permanent et peut changer dans plusieurs scénarios, ce qui nécessite un mécanisme de mise à jour sur le serveur. Si le serveur continue d’envoyer des notifications push à un jeton obsolète, APNS renvoie une erreur 410 Gone, indiquant que le jeton n’est plus valide pour l’environnement donné.

Quand le jeton change

Apple documente plusieurs scénarios dans lesquels le Device Token change : l’utilisateur réinstalle l’application, restaure l’appareil à partir d’une sauvegarde iCloud, installe une nouvelle version d’iOS ou réinitialise les paramètres réseau ou de confidentialité. Dans chaque cas, l’application recevra un nouveau jeton d’APNS lors de son prochain lancement. Le serveur doit mettre à jour le jeton dans la base de données, en supprimant l’ancien et en enregistrant le nouveau.

Traitement de l’erreur 410 Gone d’APNS

Lorsque le serveur envoie une notification push à un jeton obsolète, APNS renvoie HTTP 410 avec l’en-tête apns-unless-timestamp. Cet en-tête indique l’heure à partir de laquelle le jeton est devenu invalide. Le serveur doit immédiatement supprimer ou désactiver ce jeton dans la base de données pour éviter de lui renvoyer des notifications. Ignorer l’erreur 410 gaspille des ressources et réduit le taux de délivrabilité.

Nettoyage périodique des jetons inactifs

Pour maintenir la base de données de jetons à jour, il est recommandé d’effectuer un nettoyage périodique. Le script de nettoyage analyse les journaux APNS des N derniers jours, trouve tous les jetons ayant reçu une erreur 410 et les désactive dans la base de données. De plus, les jetons sans activité utilisateur depuis plus de 90 jours peuvent être supprimés — ce sont des enregistrements inutiles qui ne font qu’augmenter la taille de la base de données.

Validation des jetons avant envoi massif

Avant l’envoi massif de notifications push (newsletters, campagnes promotionnelles), il est recommandé de pré-valider les jetons. APNS ne fournit pas d’API directe pour la validation par lots des jetons. La stratégie utilisée consiste donc à envoyer un push de test avec une faible priorité et à analyser les erreurs. Les jetons qui renvoient une erreur 410 sont exclus de l’envoi principal.

Exemple de code pour obtenir un Device Token

Parcourons le cycle complet d’obtention d’un Device Token en Swift, y compris la gestion des erreurs et l’envoi au serveur. Le code couvre la demande d’autorisation, l’inscription auprès d’APNS, la conversion de Data en chaîne hexadécimale, la gestion des erreurs et l’envoi du jeton à votre propre serveur avec des tentatives de réessai en cas d’échec.

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

        // Réessayer après un délai en cas d’erreurs réseau
        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
            }
        }
    }
}

Gestion des erreurs lors de l’inscription

Les erreurs lors de l’inscription à APNS peuvent être causées par diverses raisons. Les plus courantes incluent l’indisponibilité du réseau, une configuration de certificat incorrecte dans Xcode (par exemple, la capacité Push Notifications désactivée), l’utilisation du simulateur (qui ne prend pas en charge les push) ou un profil de provisionnement incorrect. En production, il est important de journaliser les erreurs et, si possible, de répéter l’inscription au prochain lancement de l’application.

Test du Device Token sur le simulateur

Le simulateur iOS ne prend pas en charge la réception d’un vrai Device Token. Pour tester l’inscription sur le simulateur, utilisez des vérifications d’architecture i386 : dans une compilation de débogage, vous pouvez simuler la réception du jeton ou utiliser des tests d’interface utilisateur avec des objets simulés. Les tests réels de notifications push sont toujours effectués sur un appareil physique connecté à Xcode.