اعلان‌های Push

اعلان‌های Web Push را برای کاربران خود ارسال کنید. با SDK راه‌اندازی کنید و بگذارید هوش مصنوعی همه چیز را سیم‌کشی کند.

یادداشت

API های اعلان Push در سطح SDK تا حدی کار می‌کنند — subscription ها ذخیره می‌شوند و فراخوانی‌های send بدون خطا پاسخ می‌دهند. با این حال، تحویل واقعی push در مرورگر در محیط production هنوز فعال نشده است: کلیدهای VAPID که توسط enable() بازگردانده می‌شوند بایت‌های تصادفی هستند، نه کلیدهای EC معتبر P-256، بنابراین subscription مرورگر (pushManager.subscribe) تا زمان فعال‌سازی تحویل production با شکست مواجه خواهد شد. پیام‌ها لاگ می‌شوند اما به دستگاه‌ها push نمی‌شوند. تحویل production به زودی فعال خواهد شد.

هر اپلیکیشن Proyecta می‌تواند اعلان‌های push مرورگر و PWA را برای کاربرانش ارسال کند. SDK Proyecta تولید کلید VAPID، ذخیره‌سازی subscription، مدیریت topic و تحویل را مدیریت می‌کند — بدون نیاز به حساب کاربری شخص ثالث.

نحوه عملکرد

اعلان‌های push در Proyecta از چرخه حیات استاندارد Web Push با چهار مرحله پیروی می‌کنند:

1. Enable — تولید کلیدهای VAPID برای اپ شما (یک‌بار)
2. Subscribe — ثبت دستگاه کاربر برای دریافت اعلان‌ها
3. Identify — لینک کردن یک subscription ناشناس به کاربر وارد شده
4. Send — تحویل اعلان به کاربران خاص، topic ها، یا همه

همه چهار مورد زیر proyecta.pushNotifications در SDK قرار دارند.

فعال‌سازی push برای اپ

اولین فراخوانی یک کلید عمومی VAPID تولید می‌کند که مرورگر برای ایجاد subscription به آن نیاز دارد. این فراخوانی idempotent است — فراخوانی مجدد همان کلید را برمی‌گرداند.

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

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

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

از هوش مصنوعی بخواهید: "Enable push notifications and store the VAPID key in a PROYECTA_VAPID_PUBLIC_KEY env var".

Subscribe کردن دستگاه کاربر

در سمت client، یک subscription برای Web Push با کلید VAPID ایجاد کنید، سپس آن را همراه با 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

اگر کاربر وارد سیستم شده، از شناسه کاربر احراز هویت‌شده به عنوان visitorId استفاده کنید، یا برای بازدیدکنندگان ناشناس یک UUID تولید کنید.

لینک کردن subscription های ناشناس به کاربران

وقتی یک بازدیدکننده ناشناس وارد سیستم می‌شود، subscription موجود آن‌ها را به شناسه کاربر احراز هویت‌شده لینک کنید تا send بعدی بتواند آن‌ها را هدف بگیرد:

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

ارسال اعلان

می‌توانید visitor ID های خاص، topic ها، هر دو (به صورت اجتماع)، یا همه را هدف بگیرید. برای broadcast به همه، هم visitorIds و هم topics را حذف کنید.

// 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 مقدار { sent, failed } را برمی‌گرداند تا بدانید تحویل چگونه پیش رفت. عدد sent در پاسخ فعلی stub نشان‌دهنده تعداد subscription های ذخیره‌شده‌ای است که هدف قرار گرفته‌اند، نه تحویل‌های واقعی در مرورگر — تا زمانی که تحویل production فعال نشده، به آن به عنوان تأیید تحویل اتکا نکنید.

Topic ها

کاربران می‌توانند از طریق sub-resource به نام proyecta.pushNotifications.topics در topic های نام‌گذاری‌شده (مثلاً product-updates، weekly-digest) subscribe شوند. این روش توصیه‌شده برای مدیریت لیست‌های opt-in است — برای به‌روزرسانی‌های از نوع broadcast نیازی نیست خودتان visitor ID ها را ردیابی کنید.

Unsubscribe

با استفاده از secret برگشتی از subscribe، یک subscription را حذف کنید:

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

بگذارید هوش مصنوعی سیم‌کشی کند

لازم نیست هیچ‌کدام از اینها را دستی بنویسید. از هوش مصنوعی بخواهید:

• "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."

نکات مهم

• Preview اعلان‌های push واقعی ارسال نمی‌کند. اعلان‌های push فقط روی نسخه منتشرشده اپ شما کار می‌کنند، زیرا مرورگرها برای این کار به HTTPS روی یک origin واقعی نیاز دارند.
• iOS نیاز به PWA دارد. در iOS 16.4 به بالا، Web Push فقط از یک Progressive Web App نصب‌شده (اضافه‌شده به صفحه اصلی) کار می‌کند، نه مستقیماً از Safari.
• دسترسی یک‌بار داده می‌شود. اگر کاربری دسترسی اعلان را رد کند، مرورگرها اجازه نمی‌دهند به صورت برنامه‌نویسی دوباره درخواست کنید. باید آن‌ها را به تنظیمات مرورگر یا دستگاهشان هدایت کنید.

به زودی

• ارسال زمان‌بندی‌شده و رویداد-محور — ارسال خودکار بر اساس رویدادهای اپ یا یک زمان‌بندی
• Deep linking — باز کردن یک صفحه خاص در اپ هنگامی که روی اعلان ضربه زده می‌شود