Cara Mendukung Push Langsung dengan Token FCM/APNs

Skenario yang Berlaku

Artikel ini berlaku untuk Anda jika aplikasi Anda memenuhi kondisi berikut:

• Aplikasi sudah terhubung langsung ke Google FCM dan iOS APNs, memiliki token FCM dan token APNs sendiri, serta mengirim push secara mandiri dengan protokol native;
• Versi aplikasi lama belum mengintegrasikan SDK EngageLab AppPush, sehingga banyak pengguna lama tidak memiliki registration_id EngageLab dan tidak dapat dijangkau melalui API Buat Push;
• Anda ingin memasukkan pengguna lama tersebut ke sistem push EngageLab terlebih dahulu tanpa memaksa pembaruan aplikasi, lalu bermigrasi ke SDK secara bertahap.

Ringkasan Solusi

Untuk skenario ini, EngageLab menyediakan API Registrasi Perangkat: server Anda langsung mengirimkan token FCM atau device token APNs yang sudah dimiliki, dan EngageLab membuat registration_id yang terkait secara unik untuk masing-masing token. Setelah itu, Anda dapat mengirim pesan berdasarkan registration_id melalui API Buat Push, sama seperti pengguna yang terdaftar melalui SDK, dan memanfaatkan kemampuan berbasis registration_id seperti tag, alias, dan statistik.

flowchart LR
    token["Token FCM / APNs<br/>yang sudah Anda miliki"]
    register["API Registrasi Perangkat<br/>/v4/devices/token/registration_id"]
    regId["registration_id"]
    push["API Buat Push<br/>/v4/push"]
    device["Perangkat pengguna<br/>menerima notifikasi"]

    token --> register --> regId --> push --> device

Langkah integrasi:

1. Server Anda memanggil API Registrasi Perangkat untuk mengirim token secara batch per platform (1–500 token per permintaan) dan menyimpan pemetaan antara registration_id yang dikembalikan dan setiap token;
2. Saat mengirim push, isi registration_id pengguna tujuan pada to.registration_id di API Buat Push;
3. Saat token berubah (onNewToken FCM, registrasi ulang APNs), panggil kembali API Registrasi Perangkat untuk mendapatkan registration_id baru.

Pertanyaan yang sering muncul setelah integrasi: ketika pengguna mengetuk notifikasi di ponselnya, apakah aplikasi membuka halaman beranda, atau dapat langsung masuk ke halaman tujuan seperti detail pesanan? Penjelasan berikut menggunakan FCM Android sebagai contoh.

Navigasi Klik Notifikasi: Kesimpulan

Navigasi ke halaman tujuan dapat diwujudkan, tetapi tidak otomatis tersedia hanya karena registration_id telah didaftarkan.

• Secara default, mengetuk notifikasi hanya akan membuka aplikasi;
• Halaman mana yang dibuka ditentukan oleh logika penanganan klik aplikasi Anda sendiri;
• Untuk menuju halaman tujuan, server harus menentukan intent.url dalam permintaan push, dan aplikasi Anda harus menyediakan Activity yang dapat merespons action tersebut.

API Registrasi Perangkat hanya bertugas membangun pemetaan antara token FCM dan registration_id; API ini tidak menambahkan kemampuan navigasi halaman apa pun ke aplikasi Anda, dan pengguna ini juga tidak melewati logika perantara klik notifikasi yang bergantung pada SDK EngageLab. Karena itu, ini adalah solusi transisi; dalam jangka panjang tetap disarankan untuk bermigrasi ke SDK EngageLab AppPush, lihat bagian "Rekomendasi Jangka Panjang" di akhir artikel.

Perilaku Default: Tanpa Konfigurasi Aksi Klik

Ketika permintaan push tidak mengonfigurasi notification.android.intent, notifikasi yang dikirim EngageLab ke FCM tidak membawa click_action. Perilaku klik saat itu sepenuhnya mengikuti perilaku default FCM:

• Saat aplikasi berada di latar belakang atau telah dimatikan, notifikasi ditampilkan otomatis oleh FCM, dan ketukan akan membuka Activity peluncur aplikasi (Activity yang dideklarasikan sebagai MAIN/LAUNCHER di AndroidManifest.xml);
• Apakah pengguna akhir melihat halaman beranda, halaman login, atau kembali ke halaman yang sebelumnya dibuka, bergantung pada logika startup aplikasi Anda dan kondisi task stack saat itu.

Jadi, "membuka aplikasi secara default" tidak sama dengan "pasti kembali ke halaman beranda". Lihat dokumentasi resmi Firebase: Menerima pesan di aplikasi Android.

Mewujudkan Navigasi ke Halaman Tujuan: intent.url → click_action

Rantai Pemetaan

Server EngageLab memetakan nilai notification.android.intent.url di API Buat Push ke field android.notification.click_action pada notifikasi FCM, lalu sistem Android mencari Activity di aplikasi Anda yang cocok dengan action tersebut.

flowchart LR
    pushApi["API Buat Push<br/>notification.android.intent.url"]
    fcm["Pesan FCM<br/>android.notification.click_action"]
    activity["Aplikasi Anda<br/>Activity yang cocok dengan action"]
    target["Halaman bisnis tujuan<br/>(mis. detail pesanan)"]

    pushApi --> fcm --> activity --> target

Definisi resmi click_action dapat dilihat di FCM AndroidNotification.

Langkah 1: Server Menentukan intent.url dalam Permintaan Push

Saat mengirim push berdasarkan registration_id, tambahkan intent.url di dalam notification.android dan bawa parameter bisnis melalui extras:

              
              curl -X POST https://pushapi-sgp.engagelab.com/v4/push \
  -u "appKey:masterSecret" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "push",
    "to": {
      "registration_id": ["13065ffa4e1a6cc91c3"]
    },
    "body": {
      "platform": "android",
      "notification": {
        "android": {
          "title": "Pesanan telah dikirim",
          "alert": "Pesanan Anda 20260911001 telah dikirim. Ketuk untuk melihat pelacakan",
          "intent": {
            "url": "intent:#Intent;action=com.example.app.ORDER_DETAIL;component=com.example.app/com.example.app.OrderDetailActivity;end"
          },
          "extras": {
            "order_id": "20260911001",
            "page": "order_detail"
          }
        }
      }
    },
    "request_id": "order-shipped-20260911001"
  }'

            

Hal yang perlu diperhatikan mengenai nilai intent.url:

• Formatnya adalah Intent URI Android (intent:#Intent;...;end), bukan alamat halaman web sembarangan;
• action adalah nama aksi kustom yang didefinisikan aplikasi Anda, dan component adalah nama paket/nama kelas lengkap Activity;
• Dalam satu url, action dan component boleh diisi salah satu saja, tetapi disarankan mengisi keduanya agar Activity tujuan dapat dicocokkan dengan tepat;
• Untuk tipe nilai lainnya (membuka beranda, Deeplink, dll.), lihat penjelasan intent pada field notifikasi android di API Buat Push.

Langkah 2: Aplikasi Anda Menyediakan Activity yang Cocok

Di AndroidManifest.xml, deklarasikan intent-filter pada Activity tujuan dengan action yang sama seperti pada intent.url:

              
              <activity
    android:name=".OrderDetailActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="com.example.app.ORDER_DETAIL" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

            

Setelah FCM menampilkan notifikasi dan notifikasi diketuk, Activity yang bersangkutan akan diluncurkan dengan action tersebut, dan pasangan kunci-nilai extras dari notifikasi dimasukkan ke extras Intent. Activity tujuan membaca parameter dan menyelesaikan routing bisnis:

              
              class OrderDetailActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val orderId = intent.getStringExtra("order_id")
        if (orderId.isNullOrEmpty()) {
            // Jika parameter tidak ada, kembali ke daftar pesanan atau beranda
            startActivity(Intent(this, MainActivity::class.java))
            finish()
            return
        }
        showOrderDetail(orderId)
    }
}

            

Jika aplikasi Anda sudah memiliki halaman perantara routing terpadu (misalnya semua klik notifikasi masuk terlebih dahulu ke PushRouterActivity, lalu didistribusikan ke halaman tertentu berdasarkan parameter), Anda dapat mengarahkan component pada intent.url ke halaman perantara tersebut. Halaman perantara membaca extras lalu berpindah ke halaman bisnis seperti detail pesanan, sehingga tidak perlu mendeklarasikan action terpisah untuk setiap halaman bisnis.

Hal yang Perlu Diperhatikan

• Apakah perlu mengintegrasikan SDK EngageLab? Tidak perlu. Rantai di atas hanya bergantung pada mekanisme click_action FCM dan deklarasi Activity di aplikasi Anda sendiri.
• Penanganan click_action yang sudah ada dapat digunakan kembali: jika aplikasi Anda sebelumnya sudah mengimplementasikan logika click_action saat mengirim langsung lewat FCM, cukup isi nilai action semula ke intent.url.
• Jika belum ada penanganan click_action, perlu ditambahkan: jika aplikasi Anda saat ini hanya mengandalkan perilaku buka default, tambahkan deklarasi Activity dan logika parsing parameter sesuai "Langkah 2"; jika tidak, meskipun server mengonfigurasi intent.url, sistem tidak akan menemukan Activity yang dapat merespons.
• Parameter bisnis dikirim melalui extras: intent.url menentukan "halaman mana yang dibuka"; konten yang ditampilkan di halaman sebaiknya dikirim lewat extras (seperti order_id) dan diurai oleh Activity tujuan.
• Perilaku saat aplikasi di latar depan: saat aplikasi berada di latar depan, FCM tidak menampilkan notifikasi secara otomatis, melainkan memanggil onMessageReceived aplikasi Anda; apakah notifikasi ditampilkan dan bagaimana navigasi setelah klik sepenuhnya diimplementasikan oleh aplikasi Anda.
• Cara verifikasi: saat uji integrasi, gunakan dulu intent:#Intent;action=android.intent.action.MAIN;end untuk memastikan jalur kanal berfungsi normal, lalu ganti dengan action bisnis untuk memverifikasi navigasi ke halaman tujuan.

Rekomendasi Jangka Panjang: Segera Bermigrasi ke SDK EngageLab AppPush

API Registrasi Perangkat diposisikan sebagai solusi kompatibilitas dan transisi, yang memungkinkan pengguna lama dari versi aplikasi terdahulu tetap dapat dijangkau tanpa mengintegrasikan SDK, serta menghasilkan registration_id terkait sebagai persiapan untuk mengakses kemampuan EngageLab AppPush lainnya di kemudian hari. API ini menyelesaikan masalah "apakah pesan bisa sampai", bukan menggantikan SDK.

Kami menyarankan Anda menjadikannya bagian dari strategi migrasi, bukan solusi jangka panjang:

• Versi aplikasi baru mengintegrasikan SDK EngageLab AppPush: pengguna baru memperoleh registration_id melalui registrasi standar SDK dan langsung menikmati kemampuan tampilan notifikasi dan penanganan klik yang lengkap.
• Versi aplikasi lama bertransisi dengan token langsung: pengguna lama tetap menerima push melalui registration_id yang didaftarkan lewat API Registrasi Perangkat; kedua sistem dapat berjalan berdampingan tanpa perlu digabung secara paksa.
• Konvergensi bertahap seiring pembaruan versi: seiring pengguna meningkatkan ke versi yang mengintegrasikan SDK, jumlah pengguna token langsung akan berkurang secara alami dan akhirnya menyatu ke sistem SDK.

Dibandingkan dengan cara langsung yang dijelaskan dalam artikel ini, setelah mengintegrasikan SDK:

• Navigasi klik notifikasi ditangani secara terpadu oleh SDK; ketiga tipe yang didukung intent.url (Activity tertentu, beranda aplikasi, Deeplink) tidak memerlukan deklarasi action dan logika parsing satu per satu di sisi aplikasi;
• Tampilan notifikasi di latar depan, gaya bilah notifikasi (builder_id, style, channel_id, dll.), badge, pengelompokan pesan, dan field lainnya dapat berfungsi sepenuhnya;
• SDK secara otomatis melaporkan informasi perangkat dan perilaku seperti klik, sehingga statistik pengiriman dan klik di konsol lebih lengkap.

Untuk cara integrasi, lihat Panduan Integrasi SDK Android dan Panduan Integrasi SDK iOS.