novu-manage-preferences

設定の管理

Novu には 2 段階の設定システムがあります。

1. ワークフローのデフォルト設定 — UI ベースのワークフローではダッシュボードで、フレームワークベースのワークフローではコードで設定し、すべてのサブスクライバーに適用されます。
2. サブスクライバーによる上書き設定 — エンドユーザーが設定し、ワークフローのデフォルト設定を上書きします。

ワークフローレベルの設定

@novu/framework でワークフローを定義する際に、デフォルト設定を行います。

import { workflow } from "@novu/framework";

const alertWorkflow = workflow("system-alert", execute, {
  preferences: {
    all: { enabled: true, readOnly: false },
    channels: {
      email: { enabled: true },
      sms: { enabled: false },
      push: { enabled: true },
      chat: { enabled: false },
      inApp: { enabled: true },
    },
  },
});

コードでワークフローを作成していますか？Framework のセットアップ、Bridge Endpoint、ステップの制御、デプロイの詳細については、framework-integration を参照してください。

チャネルの種類

チャネル	説明
email	メール通知
sms	SMS テキストメッセージ
push	モバイル／ウェブのプッシュ通知
chat	Slack、Discord、Teams など
inApp	アプリ内受信トレイ通知

読み取り専用の設定

readOnly: true を設定すると、ワークフローのチャネルが設定 UI に表示されなくなり、サブスクライバーはオン／オフを切り替えられません。

const criticalAlertWorkflow = workflow("critical-alert", execute, {
  preferences: {
    all: { enabled: true, readOnly: true },  // subscriber CANNOT disable
  },
});

readOnly と critical の違い — 適切な方を選ぶ

これらは異なる保証を持つ別々の仕組みです。全体の比較については、design-workflow/references/severity-and-critical.md を参照してください。

フラグ	動作
preferences.all.readOnly: true	UI のみ。 ワークフローを設定 UI に表示しないため、サブスクライバーは切り替えられません。
critical: true (ワークフローレベル)	実行時。 サブスクライバーの設定を無視し、ダイジェストをスキップして、遅延なしで実行します。

通知を必ず配信する必要がある場合（アカウントの停止、セキュリティアラート、パスワードのリセットなど）は、critical: true を設定してください。readOnly: true だけでは、実行時に既存のサブスクライバーによる上書き設定は無視されません。

任意の設定（サブスクライバーによる編集が可能）

const marketingWorkflow = workflow("weekly-newsletter", execute, {
  preferences: {
    all: { enabled: true, readOnly: false },  // subscriber CAN disable
    channels: {
      email: { enabled: true },
      sms: { enabled: false },  // off by default, subscriber can enable
    },
  },
});

サブスクライバーレベルの設定

サブスクライバーは、ワークフローのデフォルト設定を上書きできます（readOnly: true の場合を除く）。

サブスクライバーの設定を取得する

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

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

const preferences = await novu.subscribers.preferences.list({
  subscriberId: "subscriber-123",
});

サブスクライバーの設定を更新する

await novu.subscribers.preferences.update(
  {
    workflowId: "weekly-newsletter",
    channels: {
      email: false,   // opt out of email
      inApp: true,    // keep in-app
    },
  },
  "subscriber-123"
);

グローバル設定

workflowId を省略すると、すべてのワークフローの設定を更新できます。

await novu.subscribers.preferences.update(
  {
    channels: {
      sms: false,  // disable SMS for all workflows
    },
  },
  "subscriber-123"
);

設定の適用順序

Novu が通知を配信するかどうかを判断する際、次の順序で設定を確認します。

1. サブスクライバーのワークフロー設定（最も具体的） — 特定のワークフローに対するサブスクライバーの上書き設定
2. サブスクライバーのグローバル設定 — すべてのワークフローに適用されるサブスクライバーのデフォルト設定
3. ワークフローのデフォルト設定 — 開発者がコードで定義したデフォルト設定
4. システムのデフォルト設定 — すべてのチャネルが有効

最も具体的な設定が優先されます。特定のワークフローでサブスクライバーがメールを無効にしている場合、グローバルのメール設定が有効でも、ワークフローの設定が優先されます。

設定 UI コンポーネント

React

import { Inbox } from "@novu/react";

function App() {
  return (
    <Inbox
      applicationIdentifier="YOUR_NOVU_APP_ID"
      subscriberId="subscriber-123"
      subscriberHash="HMAC_HASH"
    >
      {/* The Preferences panel is built into the Inbox */}
    </Inbox>
  );
}

<Inbox /> コンポーネントには、設定アイコンからアクセスできる設定パネルが組み込まれています。

単独の設定コンポーネント

<Preferences /> コンポーネントを単独で使用します。

import { Inbox, Preferences } from "@novu/react";

function PreferencesPage() {
  return (
    <Inbox
      applicationIdentifier="YOUR_NOVU_APP_ID"
      subscriberId="subscriber-123"
    >
      <Preferences />
    </Inbox>
  );
}

よくあるパターン

重要なアラート（常に有効）

preferences: {
  all: { enabled: true, readOnly: true },
}

サブスクライバーはオプトアウトできません。セキュリティアラート、支払い通知、法的通知に使用します。

マーケティング（オプトアウトしやすい設定）

preferences: {
  all: { enabled: true, readOnly: false },
  channels: {
    email: { enabled: true },
    sms: { enabled: false },
  },
}

サブスクライバーはチャネルを切り替えられます。SMS はデフォルトでオフです。

デフォルトではアプリ内通知のみ

preferences: {
  all: { enabled: false },
  channels: {
    inApp: { enabled: true },
  },
}

アプリ内通知のみが有効です。サブスクライバーは必要に応じて、ほかのチャネルを有効にできます。

よくある落とし穴

1. readOnly: true はチャネル単位ではなく、ワークフロー単位です — all レベルで readOnly を設定します。個々のチャネルはこれを継承します。
2. サブスクライバーの上書き設定は、readOnly のワークフローには適用されません — ワークフローが読み取り専用の場合、サブスクライバーの設定は無視されます。
3. ワークフローのデフォルトで enabled: false にすると、チャネルはオフになります — サブスクライバーは引き続きチャネルを有効にできます（readOnly: true の場合を除きます）。
4. Preferences UI には、読み取り専用ではないワークフローのみが表示されます — 読み取り専用のワークフローは、サブスクライバーの設定パネルに表示されません。
5. グローバル設定は、読み取り専用ではないすべてのワークフローに適用されます — 「すべてのメールを無効にする」設定として便利ですが、ワークフロー固有の設定が優先されます。

参考資料

• ワークフロー設定の例
• サブスクライバー設定の例
• 設定 UI の例