Device Token: paano gumagana, pagkuha ng APNS token at pag-update

Ano ang Device Token

Device Token (token ng device) ay isang natatanging identifier sa anyo ng hex string na nabuo ng APNS (Apple Push Notification Service) para sa bawat app sa isang iOS device. Ang token ay ang susi kung saan ang server ay nagpapadala ng mga push notification sa isang partikular na device. Kung walang tamang Device Token, hindi maihahatid ng server ang push notification — tinatanggihan ng APNS ang kahilingan na may error na 400 BadRequest.

Paano nabubuo ang token

Ang Device Token ay nilikha ng iOS system sa unang pagkontak ng app sa APNS pagkatapos ng pag-install. Ang proseso ng pagbuo ay may kasamang cryptographic na pag-link sa identifier ng app (bundle ID) at natatanging identifier ng device (UID), pagkatapos ay ibinabalik ng APNS ang isang 32-byte token sa hex format (64 character) sa app. Ang token ay hindi permanente — ang system ay maaaring lumikha ng bago sa ilalim ng ilang mga kundisyon.

Papel ng token sa paghahatid ng push notification

Kapag nagpadala ang server ng push notification, isasama nito ang Device Token sa HTTP/2 request sa APNS. Sinusuri ng APNS ang bisa ng token: kung ang token ay kabilang sa ibang kapaligiran (sandbox sa halip na production), nag-expire o na-revoke, ibinabalik ng Apple server ang error na 410 Gone o 400 BadRequest. Pagkatapos lamang ng matagumpay na pag-validate ng token, sisimulan ng APNS ang paghahatid ng notification sa device.

Pagkakaiba ng Device Token sa iba pang mga identifier

Ang Device Token ay hindi dapat ipagkamali sa IDFA (Identifier for Advertisers), IDFV (Identifier for Vendor) o UID (Unique Device Identifier). Ang IDFA at IDFV ay ginagamit para sa advertising at analytics, ang UID ay hardware serial number. Ang Device Token ay umiiral lamang para sa mga push notification at hindi nagbubunyag ng impormasyon tungkol sa user o device sa labas ng APNS.

Paano natatanggap at nagrerehistro ang device ng token

Ang proseso ng pagkuha ng Device Token ay binubuo ng ilang mga mandatoryong hakbang, simula sa paghingi ng pahintulot mula sa user hanggang sa pagpapadala ng token sa server. Bawat hakbang ay kritikal — ang paglaktaw sa alinman ay nagreresulta sa kawalan ng kakayahang magpadala ng push notification sa device.

Paghingi ng pahintulot para sa mga notification

Unang hakbang, humihingi ang app ng pahintulot mula sa user para sa pagpapadala ng mga notification sa pamamagitan ng UNUserNotificationCenter.current().requestAuthorization. Ang user ay maaaring pumayag, tumanggi, o pumili ng mga opsyonal na opsyon (alert, badge, sound). Kung walang malinaw na pahintulot ng user, hindi maglalabas ng Device Token ang system, kahit na tawagin ng app ang registerForRemoteNotifications. Pagkatapos makuha ang pahintulot, tinatawag ng app ang UIApplication.shared.registerForRemoteNotifications(), na nag-uumpisa sa proseso ng pagrehistro sa APNS.

Pagtanggap ng token mula sa APNS

Pagkatapos ng pagrehistro, ibinabalik ng APNS ang token sa pamamagitan ng delegado ng AppDelegate: application(_:didRegisterForRemoteNotificationsWithDeviceToken:). Ang matagumpay na tawag ay naglalaman ng Data object na may token, na dapat i-convert sa hex string para sa pagpapadala sa server. Kung may error, tinatawag ng system ang application(_:didFailToRegisterForRemoteNotificationsWithError:) na may paglalarawan ng problema: maling configuration ng certificate, walang network, o maling configuration ng proyekto.

Pagpapadala ng token sa sarili mong server

Pagkatapos matanggap ang token, dapat itong agad na ipadala ng app sa sarili nitong server para sa pag-imbak sa database. Ang API request ay may kasamang token, identifier ng device (para sa pagtutugma), kapaligiran (sandbox/production) at opsyonal na karagdagang data: bersyon ng OS, modelo ng device, wika. Inirerekomenda na ulitin ang pagpapadala ng token sa bawat paglunsad ng app, upang ang server ay laging may napapanahong token.

// Paghiling ng pahintulot at pagrehistro sa APNS
func registerForPushNotifications() {
    UNUserNotificationCenter.current()
        .requestAuthorization(options: [.alert, .sound, .badge]) {
        [weak self] granted, error in
        guard granted else {
            print("Hindi nakuha ang pahintulot")
            return
        }
        DispatchQueue.main.async {
            UIApplication.shared
                .registerForRemoteNotifications()
        }
    }
}

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

    // Ipadala ang token sa server
    PushTokenService.shared
        .sendTokenToServer(tokenString) { success in
        if success {
            UserDefaults.standard.set(tokenString,
                forKey: "lastDeviceToken")
        }
    }
}

Pamamahala ng token sa panig ng server

Ang panig ng server ng push system ay dapat mag-imbak ng Device Token sa database, na nakaugnay sa user at kapaligiran. Kapag nagpapadala ng notification, bubuo ang server ng request sa APNS, kasama ang token sa URL at JWT token (o certificate) para sa awtorisasyon. Ang tamang pamamahala ng token ay kritikal na nakakaapekto sa porsyento ng paghahatid ng push notification.

Istruktura ng database ng token

Ang talahanayan ng token sa server ay dapat maglaman ng hindi bababa sa: Device Token (natatangi), identifier ng user, kapaligiran (sandbox/production), petsa ng huling pag-update at katayuan (aktibo/hindi aktibo). Inirerekomenda ang pagdagdag ng index sa token para sa mabilis na paghahanap kapag nagpapadala at sa user para makuha ang listahan ng lahat ng device ng user. Maraming app ang nagpapahintulot sa isang user na magkaroon ng maraming device — bawat isa ay may sariling token.

Awtorisasyon ng mga request sa APNS

Para magpadala ng push notification, dapat awtorisahin ng server ang request sa APNS sa dalawang paraan. Batay sa certificate (Certificate-based) ay gumagamit ng SSL certificate na nabuo sa Apple Developer Console. Ang paraang batay sa token (Token-based) ay gumagamit ng JWT na may .p8 key, na may bisa hanggang 30 araw nang hindi kailangang i-update ang certificate. Ang awtorisasyong batay sa token ay itinuturing na mas moderno at inirerekomenda ng Apple para sa mga bagong proyekto.

Pagbubuo ng HTTP/2 APNS request

Ang request sa APNS ay may kasamang HTTP/2 POST method, URL na may path na /3/device/{device_token}, mga header ng awtorisasyon at JSON body na may payload. Ang apns-topic header ay obligatoryong naglalaman ng bundle ID ng app. Ang apns-priority ay tumutukoy sa prayoridad ng paghahatid (5 — agad, 10 — may pagtitipid ng baterya). Ang apns-expiration ay nagtatakda ng oras sa segundo mula sa epoch hanggang sa susubukan ng APNS na ihatid ang notification.

// Halimbawa ng pagpapadala ng push sa Node.js sa pamamagitan ng 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');
    }
});

Batch na pagpapadala at paglilimita ng bilis

Kapag nagpapadala ng push notification sa maraming device, gamitin ang batch na pagpapadala na may kontrol sa bilis. Inirerekomenda ng APNS na huwag lumampas sa 1500 request bawat segundo bawat koneksyon. Kapag lumampas sa limitasyon, ibinabalik ng Apple server ang error na 429 Too Many Requests. Para sa malawakang pagpapadala, gumamit ng maraming koneksyon at ipamahagi ang load nang pantay-pantay sa mga device.

Pag-update at invalidation ng token

Device Token ay hindi permanente at maaaring magbago sa ilang mga senaryo, na nangangailangan ng mekanismo ng pag-update sa server. Kung patuloy na magpapadala ng push ang server sa lumang token, ibinabalik ng APNS ang error na 410 Gone, na nagpapahiwatig na ang token ay hindi na wasto para sa kapaligirang iyon.

Kailan nagbabago ang token

Idodokumento ng Apple ang ilang mga senaryo kung saan nagbabago ang Device Token: nag-reinstall ang user ng app, nag-restore ng device mula sa iCloud backup, nag-install ng bagong bersyon ng iOS, pati na rin kapag nag-reset ng mga setting ng network o privacy. Sa bawat kaso, ang app sa susunod na paglunsad ay makakatanggap ng bagong token mula sa APNS. Dapat i-update ng server ang token sa database, burahin ang luma at i-save ang bago.

Pangangasiwa ng error na 410 Gone mula sa APNS

Kapag nagpadala ang server ng push sa lumang token, ibinabalik ng APNS ang HTTP 410 na may header na apns-unless-timestamp. Ang header na ito ay nagpapahiwatig ng oras kung kailan naging hindi wasto ang token. Dapat agad na burahin o i-deactivate ng server ang token na ito sa database upang hindi na muling magpadala dito. Ang pagbalewala sa error na 410 ay humahantong sa pag-aaksaya ng resources at pagbaba ng delivery rate.

Pana-panahong paglilinis ng mga hindi aktibong token

Upang mapanatiling napapanahon ang database ng token, inirerekomenda ang pana-panahong paglilinis. Ang script ng paglilinis ay nagsusuri ng APNS logs mula sa huling N araw, hinahanap ang lahat ng token na nakatanggap ng error na 410, at dini-deactivate ang mga ito sa database. Dagdag pa, maaaring burahin ang mga token na walang aktibidad ng user nang higit sa 90 araw — ito ay mga walang silbing record na nagpapalaki lamang ng laki ng database.

Pagsusuri ng token bago ang mass sending

Bago ang maramihang pagpapadala ng push notification (newsletter, promo campaign), inirerekomenda na suriin muna ang pagiging napapanahon ng mga token. Ang APNS ay hindi nagbibigay ng direktang API para sa batch validation ng mga token, kaya ginagamit ang estratehiya ng pagpapadala ng test push na may mababang prayoridad at pagsusuri ng mga error. Ang mga token na nagbalik ng error na 410 ay hindi isasama sa pangunahing pagpapadala.

Halimbawang code para makuha ang Device Token

Tingnan natin ang buong siklo ng pagkuha ng Device Token sa Swift, kabilang ang paghawak ng error at pagpapadala sa server. Saklaw ng code ang paghingi ng pahintulot, pagrehistro sa APNS, pag-convert ng Data sa hex string, paghawak ng error at pagpapadala ng token sa sariling server na may mga pagsubok muli kung mabigo.

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

        // Subukan muli pagkatapos ng pagkaantala sa mga error sa network
        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
            }
        }
    }
}

Paghawak ng error sa pagrehistro

Ang mga error sa pagrehistro sa APNS ay maaaring sanhi ng iba't ibang dahilan. Ang pinakakaraniwan — walang network, maling configuration ng certificate sa Xcode (hal., naka-disable ang capability na Push Notifications), paggamit ng simulator (na hindi sumusuporta sa push) o maling provisioning profile. Sa production, mahalagang i-log ang mga error at, kung maaari, ulitin ang pagrehistro sa susunod na paglunsad ng app.

Pag-test ng Device Token sa simulator

Hindi sinusuportahan ng iOS Simulator ang pagkuha ng totoong Device Token. Para sa pag-test ng pagrehistro sa simulator, gumamit ng i386 architecture checks: sa debug build maaari mong i-simulate ang pagkuha ng token o gumamit ng UI tests na may mock objects. Ang tunay na pag-test ng push notification ay palaging ginagawa sa isang pisikal na device na nakakonekta sa Xcode.