Push Notifications

Kirim notifikasi Web Push ke pengguna Anda. Siapkan dengan SDK dan biarkan AI mengurus semua pengaturannya.

Catatan

API push notification sebagian sudah berfungsi di level SDK — subscription tersimpan, dan pemanggilan send berhasil tanpa error. Namun, pengiriman push ke browser secara nyata belum diaktifkan di production: VAPID key yang dikembalikan oleh enable() adalah byte acak, bukan P-256 EC key yang valid, sehingga subscription browser (pushManager.subscribe) akan gagal sampai pengiriman production diaktifkan. Pesan dicatat di log tetapi tidak dikirim ke perangkat. Pengiriman production akan segera hadir.

Setiap aplikasi Proyecta dapat mengirim push notification browser dan PWA ke penggunanya. SDK Proyecta menangani pembuatan VAPID key, penyimpanan subscription, manajemen topik, dan pengiriman — tanpa memerlukan akun pihak ketiga.

Cara kerjanya

Push notification di Proyecta mengikuti siklus Web Push standar dengan empat langkah:

1. Enable — buat VAPID key untuk aplikasi Anda (satu kali saja)
2. Subscribe — daftarkan perangkat pengguna untuk menerima notifikasi
3. Identify — hubungkan subscription anonim ke pengguna yang sudah masuk
4. Send — kirim notifikasi ke pengguna tertentu, topik, atau semua orang

Keempat langkah tersebut tersedia di proyecta.pushNotifications dalam SDK.

Aktifkan push untuk aplikasi Anda

Pemanggilan pertama menghasilkan VAPID public key yang dibutuhkan browser untuk membuat subscription. Bersifat idempoten — memanggil ulang akan mengembalikan key yang sama.

import Proyecta from '@proyecta-ai/sdk';

const proyecta = new Proyecta({ apiKey: process.env.PROYECTA_API_KEY });

const { vapidPublicKey } = await proyecta.pushNotifications.enable();

Tanyakan ke AI: "Enable push notifications and store the VAPID key in a PROYECTA_VAPID_PUBLIC_KEY env var".

Subscribe perangkat pengguna

Di sisi client, buat subscription Web Push dengan VAPID key, lalu kirimkan ke server bersama visitorId:

// client side
const registration = await navigator.serviceWorker.ready;
const subscription = await registration.pushManager.subscribe({
    userVisibleOnly: true,
    applicationServerKey: PROYECTA_VAPID_PUBLIC_KEY,
});

// server side (or via your API route)
const { secret } = await proyecta.pushNotifications.subscribe({
    visitorId: currentUser?.id ?? generateAnonymousId(),
    subscription: {
        endpoint: subscription.endpoint,
        keys: {
            auth: subscription.keys.auth,
            p256dh: subscription.keys.p256dh,
        },
    },
});
// Store `secret` on the client — it's required to unsubscribe or identify later

Gunakan ID pengguna yang telah terautentikasi sebagai visitorId jika pengguna sudah masuk, atau UUID yang dibuat secara otomatis untuk pengunjung anonim.

Hubungkan subscription anonim ke pengguna

Saat pengunjung anonim masuk, hubungkan subscription mereka yang sudah ada ke ID pengguna yang terautentikasi agar send berikutnya dapat menarget mereka:

await proyecta.pushNotifications.identify({
    secret: storedSubscriptionSecret,
    userId: authenticatedUser.id,
});

Kirim notifikasi

Anda dapat menarget visitor ID tertentu, topik, keduanya (sebagai gabungan), atau broadcast ke semua orang. Hilangkan visitorIds dan topics untuk melakukan broadcast.

// Send to specific users
await proyecta.pushNotifications.send({
    title: 'Your order has shipped',
    body: 'Track it from your dashboard',
    visitorIds: ['user_123', 'user_456'],
    data: { orderId: 'ord_789' }, // custom payload
});

// Send to everyone subscribed to a topic
await proyecta.pushNotifications.send({
    title: 'New feature just dropped',
    topics: ['product-updates'],
    icon: 'https://cdn.example.com/icon.png',
    image: 'https://cdn.example.com/banner.png',
});

// Broadcast to all subscribers
await proyecta.pushNotifications.send({
    title: 'Scheduled maintenance at 2am UTC',
});

send mengembalikan { sent, failed } sehingga Anda mengetahui hasil pengirimannya. Jumlah sent dalam respons stub saat ini mencerminkan jumlah subscription tersimpan yang ditarget, bukan pengiriman nyata ke browser — jangan mengandalkannya sebagai konfirmasi pengiriman sampai pengiriman production diaktifkan.

Topik

Pengguna dapat berlangganan topik bernama (misalnya product-updates, weekly-digest) melalui sub-resource proyecta.pushNotifications.topics. Ini adalah cara yang disarankan untuk mengelola daftar opt-in — Anda tidak perlu melacak visitor ID sendiri untuk pembaruan bergaya broadcast.

Unsubscribe

Hapus subscription menggunakan secret yang dikembalikan dari subscribe:

await proyecta.pushNotifications.unsubscribe({ secret });

Biarkan AI mengurus semuanya

Anda tidak perlu menulis semua ini secara manual. Tanyakan ke AI:

• "Enable push notifications for my app. Register a service worker, call pushNotifications.subscribe on the client after the user grants permission, and store the secret in localStorage."
• "Send a push to all users subscribed to the 'breaking-news' topic whenever a new article is published."
• "After a user signs in, call pushNotifications.identify to link their anonymous subscription to their user ID."

Catatan Penting

• Preview tidak mengirim push nyata. Push notification hanya berfungsi pada versi aplikasi yang sudah dipublish karena browser memerlukan HTTPS pada origin yang sesungguhnya.
• iOS memerlukan PWA. Di iOS 16.4+, Web Push hanya berfungsi dari Progressive Web App yang sudah diinstal (ditambahkan ke home screen), bukan langsung dari Safari.
• Izin hanya bisa diminta satu kali. Jika pengguna menolak izin notifikasi, browser tidak mengizinkan Anda meminta ulang secara programatik. Anda harus mengarahkan mereka ke pengaturan browser atau perangkat mereka.

Segera Hadir

• Pengiriman terjadwal dan berbasis event — kirim secara otomatis berdasarkan event aplikasi atau jadwal tertentu
• Deep linking — buka layar tertentu di aplikasi saat notifikasi diketuk