knock-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 コマンドを実行する前に、認証を確認し、アカウントの環境を調べます。 まず knock whoami を実行します。「not authenticated」や「no user session」のようなエラーが発生した場合は、knock login を実行し、先に進む前にユーザーにブラウザでの手続きを完了してもらいます。次に knock environment list を実行します。環境が 1 つ返された場合は、それをデフォルト（新しいアカウントでは本番環境）として使用します。複数返された場合は、ユーザーに選択してもらいます。スラッグを <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 を使用する場合は、先に概要の冒頭にある注記を確認してください。

プロバイダー（最小限の実用的な設定 — 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 で認証を確認してください。エラーが発生した場合は、knock login を実行し、ブラウザでのフローが完了するまで待ちます。その後、knock environment list を実行します。環境が 1 つだけ返された場合は自動的に使用し、複数ある場合はユーザーに選択を求めてください。以降のすべての環境スコープのコマンドに --environment <env-slug> を渡してください。そうしない場合、CLI はアカウントのデフォルト環境を使用します。

• 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. まずツールバーを使います。 「ガイドが表示されない」という問題の多くは、数秒で解決できます。