in-app-ui

Knock アプリ内 UI スキル

このスキルは、Knock を使ったアプリ内 UI の構築に役立ちます。2 つのアプリ内プロダクトであるフィードとガイドを大まかに取り上げた後、ガイドについて、プロバイダーのセットアップ、フックを使ったレンダリング、デバッグまで詳しく説明します。

参考：https://docs.knock.app/in-app-ui/overview

概要

このスキルは、目的別にまとめた 4 つのルールファイルで構成されています。クライアントフレームワークに関するガイダンスは、-<framework> サフィックスを付けてフレームワークごとに定義します（現在は React のみ）。フレームワーク共通の概念は、サフィックスのないファイルに記載されています。

1. フィードとガイドの比較（フレームワーク非依存）— 用途に応じてどちらのプロダクトを選ぶべきか、その理由
2. React でのガイドプロバイダーのセットアップ — KnockProvider と KnockGuideProvider の props、それぞれの値の取得元、設定する順序
3. React でのガイドのレンダリング — useGuide / useGuides、型付きコンテンツ、エンゲージメントの追跡を使ったガイドコンポーネントの構築
4. ガイドのデバッグ（フレームワーク非依存）— ガイドのツールバー、トリアージ用チェックリスト、テストのワークフロー

フレームワークの範囲： 現在、このスキルが対象としているのは React（@knocklabs/react）のみです。ユーザーが Vue、Svelte、プレーンな JS、React Native、iOS、Android を使って構築している場合は、いったん作業を止め、どのように進めたいかを尋ねてください。React のルールを別のクライアント SDK に独自に適用しないでください。

このスキルの使い方

構築するものを決めるとき

まず rules/feeds-vs-guides.md を確認してください。

• 構築しているサーフェスが、フィードではなく本当にガイドであることを確認します
• 方針を決める前に、選択表を確認します
• 答えが「両方」の場合は、アプリを一度だけ KnockProvider でラップし、各プロダクトのプロバイダーを必要な場所でレンダリングします

React アプリに初めてガイドを追加する場合

1. rules/setup-guide-providers-react.md を読みます
2. CLI コマンドを実行する前に、CLI が認証済みであることと、このセットアップで使用する Knock 環境を確認します。 まず knock whoami を実行します。「not authenticated」や「no user session」のようなエラーが表示された場合は、knock login を実行し、続行する前にユーザーにブラウザでの認証フローを完了してもらいます（CLI はセッションを保持するため、マシンごとに必要なのは一度だけです）。knock whoami が成功してから、knock environment list を実行し、ユーザーに環境を選んでもらいます（CLI のデフォルトは development ですが、実際の統合の多くは production を対象にします）。そのスラッグを <env-slug> として記憶し、以降の環境スコープ付き knock コマンドすべてに --environment <env-slug> を渡します。
3. チャンネルについてユーザーに尋ねる前に、Knock CLI を使って channelId を調べます。 knock channel list --json | jq -r '.[] | select(.key == "knock-guide") | .id' を実行します。チャンネルはアカウント単位のため、このコマンドに --environment は不要です。UUID が出力されたらそれを使います。ユーザーに確認したり、再度貼り付けてもらったりしないでください。CLI が何も返さない、またはエラーになった場合に限り、ユーザーに尋ねます。代替手段の優先順位については、ルールファイルの「channelId の取得方法」を参照してください。
4. 自動で調べられない値のみをユーザーに尋ねます。主に、選択した環境の公開 apiKey を尋ねます（また、user.id がアプリの認証コンテキストから取得されることを確認します）。apiKey と channelId をまとめて尋ねないでください。
5. ツリーの最上位に KnockProvider と KnockGuideProvider を配置します。
6. ターゲティングが依存する非同期データがある場合は、そのデータを取得してから readyToTarget を有効にします。
7. 終了する前に、実際にガイドをレンダリングできることを確認します。 knock guide list --environment <env-slug> --json を実行し、選択肢（key、name、各ステップの schema_key）をユーザーに示して、実在するガイドの実際の値を使って最初のコンポーネントを作成します。"changelog-card" のようなプレースホルダー文字列でスキャフォールドしないでください。コンテンツに型を付けるため、knock message-type get <schema_key> --environment <env-slug> --json でメッセージタイプのスキーマを取得します。環境にガイドがない場合は、Knock CLI を使ってテスト用のガイドを作成することを提案します（knock guide new → JSON を編集 → knock guide push --environment <env-slug>）。組み込みのメッセージタイプ（card、banner、modal）を使い、明らかなプレースホルダーコンテンツを設定します。ダッシュボードで手動設定されるのを待って作業を止めないでください。空の環境の場合の手順を含む詳細は、rules/rendering-guides-react.md →「最初のガイド：コードを書く前に CLI で実際のガイドを調べる」を参照してください。
8. ユーザー側で対応が必要な項目（pk_ キーの貼り付け、ダッシュボードでガイドを有効にする操作、開発サーバーの再起動など）は、明確に伝えます。何も言わずに、ユーザーが気づくのを待たないでください。

React で新しいガイドコンポーネントを作成する場合

1. rules/rendering-guides-react.md のワークフローに従います
2. 値を選ぶ前に、Knock CLI を使って対象のガイド（またはメッセージタイプ）を調べます。 ガイドの key とステップの schema_key は knock guide list --environment <env-slug> --json で、コンテンツスキーマは knock message-type get <schema_key> --environment <env-slug> --json で確認します。プレースホルダー文字列は避けてください。
3. 単一のガイドを表示する場合は useGuide を、一覧の場合は useGuides を選びます
4. 取得したメッセージタイプのスキーマに対応する TypeScript 型を定義します
5. markAsSeen、markAsInteracted、markAsArchived を組み込みます。カスタムコンポーネントでは、これらを自分で実装する必要があります

ガイドがレンダリングされない場合

1. rules/debugging-guides.md を開き、トリアージチェックリストを上から順に確認します
2. まずガイドツールバー（?knock_guide_toolbar=true）を有効にします。ほとんどの疑問は数秒で解決します
3. 詳しく調べる前に、サーバー側（ターゲティング／適格性）の問題とクライアント側（プロバイダー／コンポーネント）の問題を切り分けます

ルールファイルのリファレンス

• rules/feeds-vs-guides.md — フィードとガイドのどちらを選ぶか（フレームワークに依存しません）
• rules/setup-guide-providers-react.md — ガイド用の KnockProvider と KnockGuideProvider の設定（React）
• rules/rendering-guides-react.md — useGuide、useGuides、型付きコンテンツ、エンゲージメントのトラッキング（React）
• rules/debugging-guides.md — ツールバー、切り分けチェックリスト、テストのワークフロー（フレームワークに依存しません）

クイックリファレンス

以下の例は React 用です。その他のクライアント SDK については、先に進む前に Overview の冒頭にある注記をご覧ください。

プロバイダー（最小限の実用的なセットアップ — React）

<KnockProvider
  apiKey={process.env.NEXT_PUBLIC_KNOCK_API_KEY}
  user={{ id: currentUser.id }}
>
  <KnockGuideProvider
    channelId={process.env.NEXT_PUBLIC_KNOCK_GUIDE_CHANNEL_ID}
    readyToTarget
    listenForUpdates
  >
    {children}
  </KnockGuideProvider>
</KnockProvider>

各値の取得元

• まず認証し、次に環境を確認します — Knock は環境ごとにスコープが分かれています。CLI コマンドを実行する前に、knock whoami で CLI が認証済みであることを確認します。エラーが発生した場合は、knock login を実行し、ユーザーがブラウザーのフローを完了するまで待ちます。次に knock environment list を実行し、対象のスラッグ（production、development、…）をユーザーに確認します。それ以降の環境スコープの knock コマンドには、すべて --environment <env-slug> を指定します。CLI のデフォルトである development に頼らないでください。

• apiKey — Knock ダッシュボード → Platform → API keys → 選択した環境のタブにある公開 pk_... キー（先にダッシュボードの環境セレクターで環境を切り替えます。正しい環境のキーをコピーするようユーザーに伝えてください）

• user.id — 認証コンテキストの値です。バックエンドからユーザーを識別するときに使用する ID と一致している必要があります

• channelId — ガイドチャンネルのキーではなく、その UUID です。チャンネルはアカウントのスコープに属するため、knock channel list に --environment は不要です。ユーザーに尋ねる前に、必ず CLI での検索を試してください：

  knock channel list --json | jq -r '.[] | select(.key == "knock-guide") | .id'
  

  UUID が出力された場合は、そのまま使用してください。確認を求める必要はありません。デフォルトのガイドチャンネルキーは knock-guide（タイプは in_app_guide）です。CLI が何も返さないかエラーになった場合に限り、ダッシュボード（Settings → Integrations → Channels）を確認してください。手順の詳細は rules/setup-guide-providers-react.md をご覧ください。

フックの概要

• useGuide({ type }) — メッセージタイプで指定したガイドを1つ取得します
• useGuide({ key }) — キーで指定した特定のガイドを1つ取得します
• useGuides({ type }) — メッセージタイプで指定したガイドの配列を取得します
• useGuideContext() — 低レベルのクライアントアクセスを提供します

エンゲージメントメソッド

• step.markAsSeen() — インプレッション（step をキーにした useEffect から呼び出します）
• step.markAsInteracted() — 主要なアクション
• step.markAsArchived() — 却下。以降、このユーザーにはガイドが表示されなくなります

問題が発生したときの最初の確認事項

任意の URL に ?knock_guide_toolbar=true を追加してください。ツールバーには、すべてのガイド、アクティブなガイド、対象ユーザーが利用できるガイド、その他のガイドが除外された理由が表示されます。

ベストプラクティスのまとめ

1. 適切なプロダクトを選びます。 時系列のリストにはフィード、対象を絞った UI にはガイドを使用します。
2. プロバイダーはツリーの高い位置に一度だけマウントします。 認証の境界内で、ガイドを表示するルートより上に配置します。
3. プレースホルダーのユーザーは決して渡さないでください。 KnockProvider をマウントする前に、認証が完了するまで待ちます。
4. ターゲティングルールが依存する非同期データに合わせて readyToTarget を制御します。
5. コンテンツに型を付けます。 useGuide<T> は Knock のメッセージタイプのスキーマに対応させます。
6. エンゲージメントを必ず処理します。 カスタムコンポーネントでは、markAsSeen、markAsInteracted、markAsArchived をそれぞれ呼び出す必要があります。
7. まずツールバーを使います。 「ガイドが表示されない」という問題の多くは、数秒で原因がわかります。