プッシュ通知

ユーザーにWeb Push通知を送信できます。SDKでセットアップし、残りはAIに任せましょう。

すべてのProyectaアプリは、ユーザーにブラウザおよびPWAのプッシュ通知を送信できます。Proyecta SDKがVAPIDキーの生成、サブスクリプションの保存、トピックの管理、配信を処理します — サードパーティのアカウントは不要です。

仕組み

Proyectaのプッシュ通知は、標準的なWeb Pushのライフサイクルに従い、4つのステップで構成されます：

Enable — アプリ用のVAPIDキーを生成する（一度だけ）
Subscribe — ユーザーのデバイスを通知受信に登録する
Identify — 匿名のサブスクリプションをサインイン済みユーザーに紐付ける
Send — 特定のユーザー、トピック、またはすべてのユーザーに通知を配信する

これら4つはすべて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,
        },
    },
});
// `secret` をクライアントに保存してください — 後でサブスクライブ解除や識別に必要です

ユーザーがサインイン済みの場合は認証済みユーザーIDをvisitorIdとして使用し、匿名ユーザーの場合は生成した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 }を返すため、配信状況を確認できます。現在のスタブレスポンスにおける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では実際のプッシュは送信されません。 プッシュ通知は、ブラウザが本物のオリジン上でHTTPSを要求するため、公開済みバージョンのアプリでのみ機能します。
iOSではPWAが必要です。 iOS 16.4以降では、Web PushはSafariから直接ではなく、インストール済みのProgressive Web App（ホーム画面に追加済み）からのみ動作します。
通知の許可は一度きりです。 ユーザーが通知の許可を拒否した場合、ブラウザはプログラムによる再プロンプトを許可しません。ブラウザまたはデバイスの設定画面へ誘導する必要があります。

近日公開予定

スケジュール送信およびイベントトリガー送信 — アプリのイベントやスケジュールに基づいて自動送信
ディープリンク — 通知をタップしたときにアプリの特定の画面を開く