Device Token: cara kerja, memperoleh token APNS dan pembaruan

Apa itu Device Token

Device Token (token perangkat) adalah pengidentifikasi unik dalam bentuk string hex yang dihasilkan APNS (Apple Push Notification Service) untuk setiap aplikasi di perangkat iOS. Token adalah kunci yang digunakan server untuk mengirim notifikasi push ke perangkat tertentu. Tanpa Device Token yang benar, server tidak dapat mengirimkan notifikasi push — APNS menolak permintaan dengan kesalahan 400 BadRequest.

Bagaimana token dibentuk

Device Token dibuat oleh sistem iOS pada kontak pertama aplikasi dengan APNS setelah instalasi. Proses pembuatan mencakup pengikatan kriptografi ke pengidentifikasi aplikasi (bundle ID) dan pengidentifikasi unik perangkat (UID), setelah itu APNS mengembalikan token 32-byte dalam format hex (64 karakter) ke aplikasi. Token tidak permanen — sistem dapat membuat yang baru dalam kondisi tertentu.

Peran token dalam pengiriman notifikasi push

Ketika server mengirim notifikasi push, ia menyertakan Device Token dalam permintaan HTTP/2 ke APNS. APNS memeriksa validitas token: jika token milik lingkungan lain (sandbox bukan production), kedaluwarsa atau dicabut, server Apple mengembalikan kesalahan 410 Gone atau 400 BadRequest. Hanya setelah validasi token berhasil, APNS mulai mengirimkan notifikasi ke perangkat.

Perbedaan antara Device Token dan pengidentifikasi lainnya

Device Token tidak boleh disamakan dengan IDFA (Identifier for Advertisers), IDFV (Identifier for Vendor) atau UID (Unique Device Identifier). IDFA dan IDFV digunakan untuk iklan dan analitik, UID adalah nomor seri perangkat keras. Device Token ada secara eksklusif untuk notifikasi push dan tidak mengungkapkan informasi tentang pengguna atau perangkat di luar APNS.

Bagaimana perangkat menerima dan mendaftarkan token

Proses mendapatkan Device Token terdiri dari beberapa langkah wajib, dimulai dari meminta izin dari pengguna hingga mengirim token ke server. Setiap langkah sangat penting — melewatkan salah satunya menyebabkan tidak dapat mengirim notifikasi push ke perangkat.

Meminta izin untuk notifikasi

Langkah pertama, aplikasi meminta izin pengguna untuk mengirim notifikasi melalui UNUserNotificationCenter.current().requestAuthorization. Pengguna dapat menyetujui, menolak, atau memilih opsi opsional (alert, badge, sound). Tanpa persetujuan eksplisit pengguna, sistem tidak akan mengeluarkan Device Token, bahkan jika aplikasi memanggil registerForRemoteNotifications. Setelah mendapatkan izin, aplikasi memanggil UIApplication.shared.registerForRemoteNotifications(), yang memulai proses pendaftaran di APNS.

Menerima token dari APNS

Setelah pendaftaran, APNS mengembalikan token melalui delegasi AppDelegate: application(_:didRegisterForRemoteNotificationsWithDeviceToken:). Panggilan berhasil berisi objek Data dengan token, yang harus dikonversi menjadi string hex untuk dikirim ke server. Jika terjadi kesalahan, sistem memanggil application(_:didFailToRegisterForRemoteNotificationsWithError:) dengan deskripsi masalah: konfigurasi sertifikat yang salah, tidak ada jaringan, atau konfigurasi proyek yang tidak benar.

Mengirim token ke server sendiri

Setelah menerima token, aplikasi harus segera mengirimkannya ke server sendiri untuk disimpan di database. Permintaan API mencakup token, pengidentifikasi perangkat (untuk pencocokan), lingkungan (sandbox/production) dan opsional data tambahan: versi OS, model perangkat, bahasa. Disarankan untuk mengulangi pengiriman token setiap kali aplikasi dijalankan, sehingga server selalu memiliki token terkini.

// Meminta izin dan mendaftar di APNS
func registerForPushNotifications() {
    UNUserNotificationCenter.current()
        .requestAuthorization(options: [.alert, .sound, .badge]) {
        [weak self] granted, error in
        guard granted else {
            print("Izin tidak diperoleh")
            return
        }
        DispatchQueue.main.async {
            UIApplication.shared
                .registerForRemoteNotifications()
        }
    }
}

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

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

Pengelolaan token di sisi server

Sisi server sistem push harus menyimpan Device Token di database, terkait dengan pengguna dan lingkungan. Saat mengirim notifikasi, server membentuk permintaan ke APNS, menyertakan token di URL dan token JWT (atau sertifikat) untuk otorisasi. Pengelolaan token yang benar secara kritis mempengaruhi persentase pengiriman notifikasi push.

Struktur database token

Tabel token di server harus berisi setidaknya: Device Token (unik), pengidentifikasi pengguna, lingkungan (sandbox/production), tanggal pembaruan terakhir dan status (aktif/tidak aktif). Disarankan menambahkan indeks pada token untuk pencarian cepat saat mengirim dan pada pengguna untuk mendapatkan daftar semua perangkat pengguna. Banyak aplikasi mengizinkan satu pengguna memiliki beberapa perangkat — masing-masing dengan tokennya sendiri.

Otorisasi permintaan ke APNS

Untuk mengirim notifikasi push, server harus mengotorisasi permintaan ke APNS dengan dua cara. Berbasis sertifikat (Certificate-based) menggunakan sertifikat SSL yang dibuat di Apple Developer Console. Metode berbasis token (Token-based) menggunakan JWT dengan kunci .p8, yang berlaku hingga 30 hari tanpa perlu memperbarui sertifikat. Otorisasi berbasis token dianggap lebih modern dan direkomendasikan Apple untuk proyek baru.

Membentuk permintaan HTTP/2 APNS

Permintaan ke APNS mencakup metode POST HTTP/2, URL dengan jalur /3/device/{device_token}, header otorisasi dan badan JSON dengan payload. Header apns-topic wajib berisi bundle ID aplikasi. apns-priority menentukan prioritas pengiriman (5 — segera, 10 — hemat baterai). apns-expiration menetapkan waktu dalam detik dari epoch hingga APNS akan mencoba mengirimkan notifikasi.

// Contoh pengiriman push di Node.js melalui 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');
    }
});

Pengiriman batch dan pembatasan kecepatan

Saat mengirim notifikasi push ke sejumlah besar perangkat, gunakan pengiriman batch dengan kontrol kecepatan. APNS merekomendasikan tidak melebihi 1500 permintaan per detik per koneksi. Saat melebihi batas, server Apple mengembalikan kesalahan 429 Too Many Requests. Untuk pengiriman skala besar, gunakan beberapa koneksi dan distribusikan beban secara merata ke perangkat.

Pembaruan dan invalidasi token

Device Token tidak permanen dan dapat berubah dalam beberapa skenario, yang memerlukan mekanisme pembaruan di server. Jika server terus mengirim push ke token yang sudah usang, APNS mengembalikan kesalahan 410 Gone, yang menunjukkan bahwa token tidak lagi valid untuk lingkungan tersebut.

Kapan token berubah

Apple mendokumentasikan beberapa skenario di mana Device Token berubah: pengguna menginstal ulang aplikasi, memulihkan perangkat dari cadangan iCloud, menginstal versi iOS baru, serta saat mereset pengaturan jaringan atau privasi. Dalam setiap kasus, aplikasi pada peluncuran berikutnya akan menerima token baru dari APNS. Server harus memperbarui token di database, menghapus yang lama dan menyimpan yang baru.

Menangani kesalahan 410 Gone dari APNS

Ketika server mengirim push ke token usang, APNS mengembalikan HTTP 410 dengan header apns-unless-timestamp. Header ini menunjukkan waktu setelah token menjadi tidak valid. Server harus segera menghapus atau menonaktifkan token ini di database untuk tidak mengirim lagi ke token tersebut. Mengabaikan kesalahan 410 menyebabkan pemborosan sumber daya dan penurunan tingkat pengiriman.

Pembersihan berkala token tidak aktif

Untuk menjaga database token tetap terkini, disarankan untuk melakukan pembersihan berkala. Skrip pembersihan menganalisis log APNS dari N hari terakhir, menemukan semua token yang menerima kesalahan 410, dan menonaktifkannya di database. Selain itu, token yang tidak memiliki aktivitas pengguna lebih dari 90 hari dapat dihapus — ini adalah catatan tidak berguna yang hanya meningkatkan ukuran database.

Memeriksa token sebelum pengiriman massal

Sebelum pengiriman massal notifikasi push (buletin, kampanye promosi), disarankan untuk memeriksa keaktualan token terlebih dahulu. APNS tidak menyediakan API langsung untuk validasi batch token, oleh karena itu digunakan strategi mengirim push uji dengan prioritas rendah dan analisis kesalahan. Token yang mengembalikan kesalahan 410 dikeluarkan dari pengiriman utama.

Contoh kode untuk mendapatkan Device Token

Mari kita lihat siklus lengkap mendapatkan Device Token di Swift, termasuk penanganan kesalahan dan pengiriman ke server. Kode mencakup meminta izin, mendaftar di APNS, mengonversi Data menjadi string hex, menangani kesalahan, dan mengirim token ke server sendiri dengan percobaan ulang jika gagal.

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

        // Coba ulang setelah penundaan pada kesalahan jaringan
        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
            }
        }
    }
}

Penanganan kesalahan saat pendaftaran

Kesalahan saat pendaftaran di APNS dapat disebabkan oleh berbagai alasan. Yang paling umum — tidak ada jaringan, konfigurasi sertifikat yang salah di Xcode (misalnya, kemampuan Push Notifications dinonaktifkan), penggunaan simulator (yang tidak mendukung push) atau provisioning profile yang salah. Dalam produksi, penting untuk mencatat kesalahan dan, jika memungkinkan, mengulangi pendaftaran saat aplikasi dijalankan berikutnya.

Menguji Device Token di simulator

iOS Simulator tidak mendukung mendapatkan Device Token asli. Untuk menguji pendaftaran di simulator, gunakan pemeriksaan arsitektur i386: dalam build debug Anda dapat mensimulasikan penerimaan token atau menggunakan tes UI dengan objek mock. Pengujian nyata notifikasi push selalu dilakukan pada perangkat fisik yang terhubung ke Xcode.