Push Notifications

Gửi thông báo Web Push đến người dùng của bạn. Thiết lập bằng SDK và để AI kết nối mọi thứ.

Mọi ứng dụng Proyecta đều có thể gửi thông báo push cho trình duyệt và PWA đến người dùng. Proyecta SDK xử lý việc tạo VAPID key, lưu trữ subscription, quản lý topic và gửi thông báo — không cần tài khoản bên thứ ba.

Cách hoạt động

Push notification trong Proyecta tuân theo vòng đời Web Push chuẩn với bốn bước:

Enable — tạo VAPID key cho ứng dụng của bạn (một lần duy nhất)
Subscribe — đăng ký thiết bị của người dùng để nhận thông báo
Identify — liên kết một subscription ẩn danh với người dùng đã đăng nhập
Send — gửi thông báo đến người dùng cụ thể, topic, hoặc tất cả mọi người

Cả bốn chức năng đều nằm trong proyecta.pushNotifications của SDK.

Kích hoạt push cho ứng dụng

Lệnh gọi đầu tiên tạo ra một VAPID public key mà trình duyệt cần để tạo subscription. Đây là thao tác idempotent — gọi lại sẽ trả về cùng một key.

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

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

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

Hỏi AI: "Enable push notifications and store the VAPID key in a PROYECTA_VAPID_PUBLIC_KEY env var".

Đăng ký thiết bị của người dùng

Ở phía client, tạo một Web Push subscription với VAPID key, sau đó gửi nó lên server cùng với 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

Dùng ID người dùng đã xác thực làm visitorId nếu người dùng đã đăng nhập, hoặc một UUID được tạo ngẫu nhiên cho khách truy cập ẩn danh.

Liên kết subscription ẩn danh với người dùng

Khi một khách truy cập ẩn danh đăng nhập, hãy liên kết subscription hiện có của họ với ID người dùng đã xác thực để lần gọi send tiếp theo có thể nhắm đúng mục tiêu:

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

Gửi thông báo

Bạn có thể nhắm đến các visitor ID cụ thể, topic, cả hai (dạng hợp nhất), hoặc broadcast đến tất cả mọi người. Bỏ qua cả visitorIds và topics để 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 trả về { sent, failed } để bạn biết kết quả gửi thông báo. Số lượng sent trong phản hồi stub hiện tại phản ánh số lượng subscription được lưu trữ được nhắm đến, không phải số lần gửi thực tế đến trình duyệt — đừng dựa vào đó như một xác nhận gửi thành công cho đến khi tính năng gửi production được kích hoạt.

Topics

Người dùng có thể đăng ký theo dõi các topic được đặt tên (ví dụ: product-updates, weekly-digest) thông qua sub-resource proyecta.pushNotifications.topics. Đây là cách được khuyến nghị để quản lý danh sách opt-in — bạn không cần tự theo dõi visitor ID cho các cập nhật dạng broadcast.

Hủy đăng ký

Xóa một subscription bằng cách sử dụng secret được trả về từ subscribe:

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

Để AI kết nối mọi thứ

Bạn không cần phải tự viết tất cả những điều này. Hãy hỏi 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."

Lưu ý

Preview không gửi push thật. Push notification chỉ hoạt động trên phiên bản đã publish của ứng dụng vì trình duyệt yêu cầu HTTPS trên một origin thực.
iOS yêu cầu PWA. Trên iOS 16.4 trở lên, Web Push chỉ hoạt động từ một Progressive Web App đã được cài đặt (thêm vào màn hình chính), không hoạt động trực tiếp từ Safari.
Quyền chỉ hỏi một lần. Nếu người dùng từ chối quyền thông báo, trình duyệt không cho phép bạn nhắc lại theo cách lập trình. Bạn phải hướng dẫn họ vào cài đặt trình duyệt hoặc thiết bị.

Sắp ra mắt

Gửi theo lịch trình và theo sự kiện — tự động gửi dựa trên các sự kiện trong ứng dụng hoặc theo lịch trình
Deep linking — mở một màn hình cụ thể trong ứng dụng khi người dùng nhấn vào thông báo