푸시 알림

사용자에게 Web Push 알림을 전송하세요. SDK로 설정하고 AI가 모든 것을 연결하도록 맡기세요.

모든 Proyecta 앱은 사용자에게 브라우저 및 PWA 푸시 알림을 전송할 수 있습니다. Proyecta SDK가 VAPID 키 생성, 구독 저장, 토픽 관리, 전달을 처리하므로 서드파티 계정이 필요 없습니다.

작동 방식

Proyecta의 푸시 알림은 표준 Web Push 라이프사이클을 따르며 네 단계로 구성됩니다:

Enable — 앱의 VAPID 키 생성 (최초 1회)
Subscribe — 사용자 기기를 알림 수신에 등록
Identify — 익명 구독을 로그인한 사용자와 연결
Send — 특정 사용자, 토픽, 또는 전체에게 알림 전달

네 가지 모두 SDK의 proyecta.pushNotifications 아래에 있습니다.

앱에서 푸시 활성화하기

첫 번째 호출은 브라우저가 구독을 생성하는 데 필요한 VAPID 공개 키를 생성합니다. 멱등성을 가지므로 다시 호출해도 동일한 키가 반환됩니다.

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

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

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

AI에게 요청해 보세요: "Enable push notifications and store the VAPID key in a PROYECTA_VAPID_PUBLIC_KEY env var".

사용자 기기 구독하기

클라이언트에서 VAPID 키로 Web Push 구독을 생성한 후, 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로 인증된 사용자 ID를 사용하고, 익명 방문자의 경우 생성된 UUID를 사용하세요.

익명 구독을 사용자와 연결하기

익명 방문자가 로그인하면, 다음 send 호출에서 해당 사용자를 대상으로 지정할 수 있도록 기존 구독을 인증된 사용자 ID와 연결합니다:

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

알림 전송하기

특정 visitor ID, 토픽, 또는 둘 다(합집합)를 대상으로 하거나 전체에게 브로드캐스트할 수 있습니다. 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 }를 반환하므로 전달 결과를 확인할 수 있습니다. 현재 stub 응답의 sent 수는 실제 브라우저 전달 수가 아닌 대상으로 지정된 저장된 구독 수를 나타냅니다 — 프로덕션 전달이 활성화될 때까지 이를 전달 확인으로 신뢰하지 마세요.

토픽

사용자는 proyecta.pushNotifications.topics 서브 리소스를 통해 명명된 토픽(예: product-updates, weekly-digest)을 구독할 수 있습니다. 브로드캐스트 방식의 업데이트를 위한 옵트인 목록을 관리할 때 권장되는 방법으로, visitor ID를 직접 추적할 필요가 없습니다.

구독 취소

subscribe에서 반환된 secret을 사용하여 구독을 제거합니다:

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

AI에게 연결을 맡기기

이 모든 코드를 직접 작성할 필요가 없습니다. 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."

주의 사항

Preview에서는 실제 푸시가 전송되지 않습니다. 브라우저가 실제 origin의 HTTPS를 요구하기 때문에, 푸시 알림은 앱의 게시된(published) 버전에서만 작동합니다.
iOS는 PWA가 필요합니다. iOS 16.4 이상에서 Web Push는 Safari에서 직접 접근하는 것이 아닌, 설치된 Progressive Web App(홈 화면에 추가된)에서만 작동합니다.
알림 권한은 한 번만 요청할 수 있습니다. 사용자가 알림 권한을 거부하면 브라우저는 프로그래밍 방식으로 재요청을 허용하지 않습니다. 사용자를 브라우저 또는 기기 설정으로 안내해야 합니다.

출시 예정

예약 및 이벤트 트리거 전송 — 앱 이벤트 또는 일정에 따라 자동으로 전송
딥 링킹 — 알림을 탭했을 때 앱의 특정 화면 열기