KOL Post Analytics
メンバーマニュアル

1. このシステムについて

KOL Post Analytics は、SNSタイアップ投稿 (X / Instagram / TikTok / YouTube) のパフォーマンスを多角的に分析し、広告主向けレポートを自動生成する社内ツールです。

主な機能

• 投稿パフォーマンス分析 — 再生数・エンゲージメント・コメント傾向を可視化
• クリエイティブスコア — クリエイターの普段の実績との比較
• AIコメント分類 — Gemini API で態度変容・ネガティブ等を自動判定
• 動画コンテンツ分析 — タテ型ショート動画の構成・形式を AI が解析
• Google検索リフト — ブランド検索の施策前後比較
• 案件検索コマンドパレット (⌘K) — 大量案件の中から即座に絞り込み・ブックマーク
• クリエイター履歴 stale 警告 — 7日以上古いキャッシュに自動警告 + まとめて再取得
• 共同編集者機能 — 最大2名まで case-level で編集権限を委譲 (BAN対策と休暇引継ぎ用)
• ハッシュタグ波及 — キャンペーンタグの広がりを定量化
• pptx自動生成 — 広告主向けレポートをワンクリックで出力

アクセス URL

役割 (ロール)

2. 初回ログイン

管理者から メアド + 一時パスワード を受け取ったら、初回ログインを行います。

3. パスワード変更

初回ログイン時は自動で変更画面が出ます。任意のタイミングで再変更したい場合は管理者にリセット依頼してください (任意で自分で変える UI は今後追加予定)。

変更画面での入力

• 現在のパスワード: 一時PW (または現在のPW)
• 新しいパスワード: 8文字以上、できれば 14文字以上
• 新しいパスワード (確認): 上と同じものをもう一度

強いパスワードの条件

4. パスワードを忘れたら

自分でリセットする機能はありません。管理者に依頼してください。

5. ダッシュボードの構造

ログイン後の画面は、上から順に下記の4ブロックで構成されます。

┌──────────────────────────────────────┐
│ 5-1. ヘッダー                            │
│  📊 ロゴ  | 🔄更新 | 🌙 ダーク | ⚙ jobs | 👤 user │
├──────────────────────────────────────┤
│ 5-2. 案件バー                            │
│  📁 案件:[選択▼] [+新規] [✏編集] [🗑削除]   │
├──────────────────────────────────────┤
│ 5-3. プラットフォームフィルタ              │
│  🌐 全 | 🐦 X | 📸 IG | 🎵 TT | ▶️ YT     │
│  📊 view_mode: 広告込 | オーガニックのみ      │
├──────────────────────────────────────┤
│ 5-4. タブ群 (機能切替)                   │
│  📑 資料作成 | 📈 全体サマリー | 🎯 投稿... │
├──────────────────────────────────────┤
│ メインコンテンツ (選択したタブの中身)         │
└──────────────────────────────────────┘

5-1. ヘッダー

5-2. 案件バー

分析対象の案件を選びます。1人のユーザーが複数案件を切り替えながら作業します。案件数が多い場合は下記の 案件検索コマンドパレット が便利です。

🔍 案件検索コマンドパレット (⌘K)

案件バーの案件名ボタンをクリック、または ⌘K (Mac) / Ctrl+K (Win) でキーボードだけで案件を素早く検索・切り替えできます。

• 検索: 「DMM」「佐貫」「2607」などの部分入力で絞り込み。半角/全角/【】_ - は無視して照合
• ↑↓ で選択: 検索結果の中を移動
• Enter で開く: 案件を切替
• ⭐ ブックマーク: 各行の右端の ☆ をクリック、または ⌘B / Ctrl+B で常用案件をピン留め。次回起動時に「⭐ ブックマーク」セクションに常時表示
• 🕐 最近開いた: 直近5件が自動記録され、パレットの上位に表示 (LRU)
• Esc で閉じる

5-3. プラットフォームフィルタ

表示するデータをプラットフォーム別に絞り込みます。「🌐 全プラットフォーム」で全表示。

view_mode トグル

• 広告込 (total) — 取得した再生数そのまま (デフォルト)
• オーガニックのみ (organic) — 「💰 広告配信設定」タブで入力した広告分を引いた値

切替えると全レポートが連動して再計算されます。

5-4. タブ群

主要機能の切替。詳細はセクション6で各タブを説明します。

5-5. ロールによる表示差

👥 共同編集者機能 (Delegates, 最大 2名)

案件バー右側の 👥 バッジ (0/2) をクリックして、他の operator を 共同編集者に指定 できます。指定された operator は、案件作成者以外でも以下ができるようになります。

• ✅ URL 追加/削除
• ✅ スクレイプ実行
• ✅ コメント分類実行
• ✅ 広告配信設定の編集
• ✅ 案件情報 (名前・説明) の編集
• ❌ 案件削除 / オーナー変更 / 共同編集者の追加・削除 (これは owner + admin のみ)

6. 各タブの詳細

6-1. 📑 資料作成

広告主提出用のレポート (pptx) を生成するメインタブ。R1〜R8 の各分析を統合します。

サブページ

6-2. 📈 全体サマリー

案件全体の数値概況を一覧で把握するためのタブ。

表示要素

• 統計カード: 総再生・総エンゲ・コメント数・CPV/CPE 等
• プラットフォーム別棒グラフ: X/IG/TT/YT の比較
• トップ投稿 TOP3: 各KPIで上位を表示
• センチメント円グラフ: ポジ/ネガ/中立の比率
• 日次推移: 投稿日からの累積
• クリエイティブスコア概要: PRcomparison のサマリ

6-3. 🎯 投稿パフォーマンス分析

投稿1つひとつのパフォーマンスを散布図で可視化 + コンテンツ分析機能。

📍 散布図 (投稿パフォーマンス マッピング)

• X軸/Y軸: 再生数 / エンゲージ数 / 態度変容率 / ネガ率 / クリエイティブスコア から選択可
• 1点 = 1投稿: 色はプラットフォーム別、アカウント名表示
• 点クリック: 選択トグル (黄色いリング)
• Shift+クリック: 投稿一覧へジャンプ
• クイック選択: Y軸上位3/5/10、右上象限、全YT 等

📋 コンテンツ分析 (R8)

選択した投稿群とその他を AI が比較分析し、「動画形式 / 構成 / インフルエンサー像 / 推奨秒数」をまとめた「次回オリエンシート」を出力します。

1. 散布図上で高パフォーマンス投稿を選択
2. 「📋 コンテンツ分析実行」ボタン
3. Gemini が動画を直接視聴 (3〜5分)
4. 結果が4セクション (折畳可) で表示
5. 「📋 全文コピー」でMarkdown化、オリエンに貼付

6-4. 💬 コメント分析

「🎯 投稿パフォーマンス分析」のドロップダウンから入れるサブタブ。

機能

• AIコメント分類: Gemini が brand_find / purchase_intent / question / negative_influencer 等に分類
• カテゴリ別 投稿×件数 マトリクス: どの投稿のコメントが何の傾向か可視化
• コメント抜粋: 各カテゴリの代表コメントを表示
• クリエイター返信検出: クリエイター本人のコメントを別表示

6-5. 📊 クリエイティブスコア分析

クリエイターの普段のオーガニック投稿との比較で、今回のタイアップが伸びたかを定量化。

クリエイティブスコアとは

クリエイティブスコア (CS) = 今回投稿の再生数 ÷ 過去N件のオーガニック平均

⚠️ 履歴 stale 警告 (7日以上古いキャッシュ)

クリエイター履歴は VPS 側にキャッシュされ、再取得ボタンでのみ更新されます。取得から 7日以上経過 したキャッシュには以下の警告が出ます:

• 「⚠️ 更新推奨 (N日前)」バッジ — データ取得状況テーブルの該当行が黄色ハイライト
• 再取得ボタンが黄色で目立つ表示に
• タブを開くとポップアップ警告: 「N名のクリエイター履歴が7日以上前です。今すぐ更新しますか?」→「まとめて再取得」でサーバ側 dispatcher が PF 別に順次実行 (IG=60秒/X=30秒/TT/YT=5秒間隔で BAN 回避)

放置すると 直近の PR 投稿が「N=0」で検出されず、PR比較が不正確になります。ケロッグ案件などでこの症状が発覚した経緯があるので必ず更新してください。

🔄 「未取得+古い履歴を一括取得」ボタン

従来は「未取得のみ」を取得していましたが、現在は 未取得 + 7日以上古いキャッシュを両方対象 にします。押した際の確認ダイアログに「TT クリエイター N名 順次取得 (目安 M分)」と表示されるので、順序性 (BAN 回避) を意識した設計になっています。

6-6. 📝 投稿一覧

全投稿をテーブル表示。検索・ソート可能。

機能

• キーワード検索 (アカウント名・本文)
• ソート: 再生数 / エンゲージ率 / 投稿日 / 等
• 各投稿カードに: サムネ + 再生数 + 主要KPI
• カードクリック → 該当投稿の元URLを開く

6-7. 💰 広告配信設定

各投稿の広告配信による再生数を手動入力するタブ。

運用方法

1. テーブルに全投稿のURLが並ぶ
2. 「広告再生数」欄に数値を入力 (案件終了後に広告主から取得)
3. 「保存」
4. ヘッダー横の view_mode トグルで「オーガニックのみ」に切替えると、保存した広告分が引かれた値で全レポート再計算

📱 Instagram 投稿種別による再生数表示ルール

Instagram は投稿種別により再生数の公開状況が違うため、テーブルでは以下のように表示されます:

6-8. 🔔 監視

ジョブキューの状況とエラー監視。

⚙️ ジョブキューパネル

5名同時にスクレイピングを押しても、bot検知回避のためプラットフォーム別の上限内でジョブが順次処理されます。

• ジョブ一覧: queued / running / done / failed / cancelled で絞込可
• キャンセル: queued (待機中) のみキャンセル可。running は不可
• 5秒毎自動更新

🔔 エラー監視 / Slack通知

スクレイパー失敗・Cookie Pool BAN等を自動記録。Slack Webhook URL を設定すれば重大エラーを即時通知。

6-9. 🛠️ ツール / URL管理

データ取得実行のタブ。最重要かつ最も注意が必要なタブ。

主な機能

• URL一括追加: テキストエリアにURL貼付 → プラットフォーム自動判別 → 追加
• 期間設定: 1d / 7d / 30d プリセット または カスタム日付
• 「今日のスクレイプ実行」: 期間内のURLを取得
• 「全URL再取得」: 強制的に全URLを再取得
• クリエイター履歴取得: CS算出用
• Cookie Pool 管理: IGのスクレイピングアカウント管理
• スナップショット: 日次の状態保存・比較

6-10. ⚙️ 設定 (admin専用)

メンバーの追加・削除・PWリセット。admin ロールのみ表示。

👥 メンバー管理

🌐 閲覧専用ドメイン

ドメイン (例: uuum.jp) を登録すると、そのドメインのユーザーは viewer ロールでログイン可能。※ 現在は手動で operators.json に viewer を追加する運用 (UI改修予定)。

7. よくある作業フロー

7-1. 新規案件 登録〜分析

7-2. 動画解析 (コンテンツ分析)

7-3. レポート pptx 自動生成

7-4. ハッシュタグ波及分析

1. 「📑 資料作成」→ サブページ「📈 ハッシュタグ波及分析」
2. ハッシュタグ入力 (例: ZOZOTOWN_EDUCATION)、ソース選択 (X / TikTok)
3. 「取得実行」
4. キャンペーン期間と施策前期間の投稿数比較グラフが表示

7-5. Google検索リフト

1. 「📑 資料作成」→ サブページ「🔍 Google検索リフト分析」
2. ブランドキーワード入力、ソース選択 (Web / YouTube)、期間 (デフォルト30日)
3. 取得 (5〜30秒) → 施策前後の平均検索数比較 + 日次グラフ

8. 運用上の注意

8-1. BAN対策とアカウント

並列処理の制限 (システムが自動制御)

• TT/IG/X は同時 1ジョブまで
• YT は同時 2ジョブまで
• 5人が同時に取得ボタン押しても、サーバが順番待ちで平準化
• 日次上限到達 → 翌日まで待機

8-1b. ⏰ 日次キャップ到達のアラート体制

BAN リスク対策で各プラットフォームに 1日あたりの取得上限 が設定されています。上限到達時のアラート機構を 2026-06 に整備:

※ 数値の真値は job_queue.py:42-56 の PLATFORM_DAILY_CAP / PER_ACCOUNT_DAILY_LIMIT / HARD_CEILING_PER_PLATFORM。横断ジョブ (動画解析・ハッシュタグ・レポート生成) は別枠で 1000/日。

キャップ到達時に何が起こるか

1. 🔴 全タブ最上部にバナー表示 — 「○○ が本日の取得上限に到達」と現状の説明
2. 📊 監視タブに詳細パネル — プラットフォーム別の 使用 / 上限、キュー残件数、関係案件名、再開予定時刻
3. 📋 次回作業指示の自動表示 — 「翌日 00:00 (サーバローカル時刻) 以降に自動再開予定。追加操作は不要です」
4. 📢 Slack 通知 (Slack Webhook 設定時) — 1 日 1 プラットフォームあたり 1 回の dedup あり。ただし dedup はプロセスメモリ管理のため、Worker / サーバを当日中に再起動すると同一プラットフォームの通知が再度飛ぶことがあります (job_queue.py:490 _cap_hit_notified_today)。
5. キューに積まれたジョブはそのまま残る — 翌日 0:00 (サーバローカル時刻) になると Worker が自動再開、追加操作不要

IG / X の動的キャップ (Cookie Pool 連動)

2026-06 から IG と X の上限は Cookie Pool の active アカウント数に応じて自動拡張 されます (job_queue.py _effective_daily_cap)。

HARD_CEILING_PER_PLATFORM=2000 (job_queue.py:56) は Pool 大量追加時の暴走防止。これを超えるアカを追加しても 2000 で頭打ちになります。さらに上げたい場合は admin に相談。

動的キャップ採用の IG / X では、監視タブのキャップ詳細パネル に「🔄 Pool アカ N × M/アカ = 合計 件/日 (動的)」が併記されます (dashboard.html:14380)。YouTube / TikTok は静的なのでこの行は出ません。

UI バナーの見え方

監視タブのキャップ詳細パネル

• 🟢 緑カード = 余裕あり、🔴 赤カード = 上限到達
• 進捗バーで使用率を可視化
• 到達時は該当案件名 + 残作業件数 + 再開予定時刻を明示
• 5秒毎自動更新

📌 既知の挙動 / 注意点 (2026-06 監査時点)

• プラットフォーム名は小文字限定 — cookie_pool 側の alias マップ (cookie_pool.py:34 _PLATFORM_ALIASES) は case-sensitive。外部スクリプト等から "Instagram" や "IG" を渡すと別ディレクトリ cookie_pool/Instagram/ を参照してしまい、Pool が空扱い → cap が静的フォールバック (200) に落ちます。呼び出しは必ず "instagram" / "x" で統一してください。
• storage_state ファイル欠落アカも active カウントに含まれる — cookie_pool の status 判定 (cookie_pool.py:117-129) は banned / limit_reached / cooldown のみで分岐し、storage_state_exists=False は考慮されません。そのため account_xxx.json を手動削除した直後は UI には ⚠ 表示が出るが、cap 計算上は active として N にカウントされたままになります。ファイルを消したら必ず該当アカウントを Pool UI から削除するか banned 化してください。
• cookie_pool が import 失敗した環境では静的フォールバック — job_queue.py:69-78 は try/except で包まれており、cookie_pool モジュール自体が読めない (VPS で playwright が無い等) ケースでも IG=200 / X=150 の静的キャップで動作します (クラッシュしません)。
• 横断ジョブ (動画解析・ハッシュタグ・レポート生成) は別枠 — platform=None のジョブは IG/X/TT/YT の cap に影響しません。専用の 1000/日 + 並列 3 で動きます。

8-2. APIコストとキャッシュ

キャッシュは _cache_videos / _cache_analysis / _cache_briefs に保存。同じ動画を2度解析しません。コスト節約のために、解析対象投稿はよく選んでください。

8-3. データ取り扱い

• プロジェクトデータ は VPS の projects/<案件名>/ に保存
• 毎日深夜に自動バックアップ (7日分保持) → /srv/comment-analyzer/backups/
• 退職者の Cookie Pool アカウントは 必ず削除依頼してください
• クライアント機密情報を含むため、URL を SNS等に投稿しない

8-4. 期間設定の落とし穴

正しい期間設定の運用

• 新規案件登録時に「7d / 30d プリセット」または カスタム日付で指定
• 1度設定したら、URLの追加・削除をしても期間は保持される
• 意図的に変更したい場合は「期間プリセット適用」で明示的に変更

8-5. 最近の仕様変更 (差分のみ、運用面で重要)

⓿. admin 向け運用 (admin ロールのみ)

⓿-1. 🔗 共有リンクの発行 (アカウント未発行者向け閲覧専用URL)

クライアントや社外関係者など システムのアカウントを持たない人 に、レポートを期限付きで閲覧してもらうための機能です。

発行手順

受け取り側の体験

• URL を開くと ログイン不要 でダッシュボードを閲覧可能
• 編集・削除・取得実行などの操作系ボタンは すべて非表示
• Cookie Pool 管理 / メンバー管理 / 設定タブ自体 が見えない
• ブラウザを閉じて開き直しても、有効期限内なら再入場可能

失効・期限切れ

• 共有リンク一覧で各 URL の 「失効」 ボタンを押すと即座に無効化 (受け取り側は次のアクセスで「リンク無効」画面)
• 有効期限が切れたものは自動で「期限切れ」表示
• 最終アクセス時刻 / アクセス回数 が表示されるので運用監視可能

⓿-2. 🍪 Cookie Pool 管理 (IG / X) — スクレイプ用サブアカ運用

IG と X のスクレイピングには **logged-in セッション** が必要で、BAN リスク回避のためサブアカウントを 1〜3 個 Pool 化してローテーションさせます。

📸 Instagram Pool の追加 (Mac 必須)

IG はログイン時の reCAPTCHA / SMS 認証が headless では通らないため、admin の Mac でローカル実行が必要:

cd "/Users/yuya.m/Desktop/Comment analyzer"
python3 server.py

rsync -avh --delete \
  "/Users/yuya.m/Desktop/Comment analyzer/cookie_pool/" \
  root@163.44.121.219:/srv/comment-analyzer/cookie_pool/

🐦 X (Twitter) Pool の追加 (本番ダッシュボードから直接)

X は headed ブラウザを使わず、ブラウザ DevTools から Cookie をコピーして登録する方式:

運用

• Cookie の有効期限 (X: 数ヶ月、IG: 数週間〜数ヶ月) が切れたら admin が新値で上書き
• BAN 検知時は該当アカウントが 🔴 BAN/エラー に自動切替 → 削除 → 新アカ追加
• メンバーには Cookie Pool 管理セクション自体が表示されない (admin-only UI)

⓿-3. 🔒 案件所有権の運用

2026-06 以降、案件は 作成者と admin だけが編集・削除可能 に変更されました。メンバー間の誤操作事故防止。

ルール

UI 表示

案件バー右側に所有者バッジが出ます:

• 🟢 🔓 あなたの案件 = 自分が作成 (緑バッジ)
• ⚪ 👤 hara_k (admin編集可) = admin が他人案件を表示中 (操作可)
• 🔴 🔒 hara_k = 他人案件で編集禁止 (✏️/🗑️ ボタンも disabled)
• ⚪ 🔓 作成者: 未設定 = 旧案件 (誰でも編集可、後方互換)

9. FAQ

Q. ログインできません

A. メアド・パスワードのコピペミスを確認 → 改善しなければ管理者に PWリセット依頼。

Q. スクレイピングを押したのに何も動かない

A. 「🔔 監視」タブでジョブキューを確認。queued (待機中) で順番待ち中かもしれません。プラットフォーム別の上限を超えた場合は翌日待ち。

Q. 投稿数が想定より少ない

A. 「💬 コメント分析」タブで「全投稿の AI分類済件数」を確認。IGはコメント取得失敗が稀にあるので、「🛠️ ツール」で再取得を試行。

Q. クリエイティブスコアが表示されない

A. 「🛠️ ツール」でクリエイター履歴を取得していない可能性。各クリエイターの直近10件オーガニック投稿が必要です。

Q. pptx の文章を AI に書き直してもらいたい

A. 「再生成」ボタンで再実行。ただしコストかかるので、できれば手動修正で済ませることを推奨。

Q. 過去の案件データを見たい

A. 案件バーのドロップダウンから過去案件を選択。削除していなければ全データ残っています。

Q. ブラウザを閉じたらログアウトされる?

A. 24時間は再ログイン不要。それ以降は再度ログイン。

Q. スマホで使える?

A. PC推奨ですが、スマホブラウザでも閲覧は可能。ただし散布図の操作・大きなテーブルは PC で。

10. 問い合わせ先

KOL Post Analytics メンバーマニュアル v1.0
本マニュアルへのフィードバックは管理者まで