novu-manage-subscribers

サブスクライバーの管理

サブスクライバーは、通知を受け取るユーザーです。各サブスクライバーには、一意の subscriberId があります。通常は、アプリケーションのユーザー ID を使用します。

SDK のセットアップ

import { Novu } from "@novu/api";

const novu = new Novu({
  secretKey: process.env.NOVU_SECRET_KEY,
});

サブスクライバーの作成

await novu.subscribers.create({
  subscriberId: "user-123",       // required — your system's user ID
  email: "[email protected]",      // optional
  firstName: "Jane",              // optional
  lastName: "Doe",                // optional
  phone: "+15551234567",          // optional
  avatar: "https://example.com/jane.jpg",  // optional
  locale: "en-US",                // optional
  timezone: "America/New_York",   // optional
  data: {                         // optional — custom key-value data
    plan: "pro",
    company: "Acme Inc",
  },
});

必須なのは subscriberId のみです。 それ以外のフィールドはすべて省略可能です。

サブスクライバーの取得

const subscriber = await novu.subscribers.retrieve("user-123");

サブスクライバーの検索

const results = await novu.subscribers.search({
  email: "[email protected]",
});

サブスクライバーの更新

await novu.subscribers.patch(
  { firstName: "Jane", data: { plan: "enterprise" } },
  // subscriberId
  "user-123"
);

サブスクライバーの削除

await novu.subscribers.delete("user-123");

一括作成

複数のサブスクライバーを一度に作成します。1 回のリクエストで最大 500 人のサブスクライバーを作成できます。

await novu.subscribers.createBulk({
  subscribers: [
    { subscriberId: "user-1", email: "[email protected]", firstName: "Alice" },
    { subscriberId: "user-2", email: "[email protected]", firstName: "Bob" },
    { subscriberId: "user-3", email: "[email protected]", firstName: "Carol" },
  ],
});

トピック

トピックは、サブスクライバーをまとめた名前付きのグループです。一度に複数のサブスクライバーへ通知を送るために使用します。

トピックの作成

await novu.topics.create({
  key: "engineering-team",
  name: "Engineering Team",
});

トピックへのサブスクライバーの追加

await novu.topics.subscriptions.create(
  { subscriptions: ["subscriberId-1", "subscriberId-2", "subscriberId-3"] },
  "engineering-team-topic"
);

トピックからのサブスクライバーの削除

await novu.topics.subscriptions.delete(
  { subscriptions: ["subscriberId-1", "subscriberId-2"] },
  "engineering-team-topic"
);

トピックの一覧表示

const topics = await novu.topics.list({

});

トピックの削除

await novu.topics.delete("engineering-team-topic");

トピックへのトリガー

トピックへのトリガーの例については、trigger-notification を参照してください。

await novu.trigger({
  workflowId: "project-update",
  to: { type: "Topic", topicKey: "engineering-team-topic" },
  payload: { message: "Sprint review at 3pm" },
});

サブスクライバーの認証情報

プッシュ通知やチャットの連携用に、チャネル固有の認証情報を設定します。

FCM プッシュトークン

await novu.subscribers.credentials.update(
  { 
    providerId: "fcm", 
    //  use integrationIdentifier if there are multiple fcm type active integrations
    integrationIdentifier: "fcm-abc-123", 
    credentials: { deviceTokens: ["fcm-device-token-here"] } 
  },
  "subsriberId-1"
);

APNS プッシュトークン

await novu.subscribers.credentials.update(
  { 
    providerId: "apns", 
    // use integrationIdentifier if there are multiple apns type active integrations
    integrationIdentifier: "fcm-abc-123", 
    credentials: { deviceTokens: ["apns-device-token-here"] } 
  },
  "user-123"
);

よくある落とし穴

1. subscriberId はユーザー自身の ID です — システムと Novu をつなぐ ID です。データベースに登録された、安定した一意の識別子を使用してください。
2. トリガー時にサブスクライバーが自動作成されます — トリガー時に to でサブスクライバーの全情報を渡すと、Novu は存在しない場合にサブスクライバーを作成します。ただし、明示的に作成すると、より細かく制御できます。
3. サブスクライバーのデータは環境ごとに管理されます — 開発環境、ステージング環境、本番環境では、サブスクライバーのレコードが個別に管理されます。
4. トリガーする前にトピックを作成する必要があります — トピックを作成し、サブスクライバーを追加してから送信してください。
5. サブスクライバーを削除しても、その通知は削除されません — 既存の通知はシステムに残ります。
6. 存在しないサブスクライバーをトピックに追加する場合 - 存在しないサブスクライバーをトピックに追加しても、その環境では自動作成されないため、トピックにも追加されません。トピックに追加する前に、必ずサブスクライバーを作成してください。

参考資料

• サブスクライバーの CRUD の例
• トピックの例
• 認証情報の例