INTERNAL / SETUP GUIDE

YouTube Analytics API
セットアップ手順

insight-analysis-pro でチャンネル別 refresh token 方式の Analytics API を使うための初回セットアップ手順書。

00全体像

YouTube Analytics API はサービスアカウント非対応で、チャンネルオーナーの OAuth 同意が必須。なので「チャンネルごとに refresh token を1個作って、Bitwarden で共有」する設計にしている。

STEP	誰が	頻度	やること
A	mocha 全体で誰か1人	初回1回	Google Cloud で OAuth クライアントを作って Bitwarden に保管
B	チャンネルオーナー	チャンネル追加時	`yt_auth.py` を実行して refresh token を生成 → Bitwarden に保管
C	誰でも	都度	Bitwarden から token を取得して `yt_analytics.py` を実行

共有方法は Bitwarden 一択。 credentials/client_secret.json も tokens/<channel_id>.json も .gitignore 済みで git には乗らない。共有 Vault にファイル添付して受け渡しすること。

AOAuth クライアントを作る（mocha全体で1回）

2種類のOAuthクライアントを作る。後で Device Flow と Local Server Flow を使い分けるため、どちらも必要。

A-1. 共通の事前準備

Google Cloud Console で mocha-official プロジェクトを開く
「APIとサービス」→ YouTube Analytics API と YouTube Data API v3 を両方有効化
「OAuth 同意画面」が未設定なら設定する（外部 / アプリ名・サポートメール記入）

A-2. デスクトップアプリ用クライアント（Local Server Flow 用）

「認証情報」→「認証情報を作成」→「OAuth クライアント ID」
アプリケーションの種類: デスクトップアプリ を選択
JSON をダウンロードして credentials/client_secret.json として保存
Bitwarden の mocha 共有 Vault にアップロード（タイトル例: insight-analysis-pro / client_secret.json）

A-3. TV/Limited Input 用クライアント（Device Flow 用）

「認証情報」→「認証情報を作成」→「OAuth クライアント ID」
アプリケーションの種類: テレビと制限付き入力デバイス を選択
JSON をダウンロードして credentials/client_secret_device.json として保存
Bitwarden の mocha 共有 Vault にアップロード（タイトル例: insight-analysis-pro / client_secret_device.json）

OAuth 同意画面が「テスト」モードの場合、許可済みテストユーザーに各チャンネルオーナーの Google アカウントを追加しておくこと（最大 100 件）。それ以上必要 or 社外クライアントが多い場合は本番モードに切り替え → Google の審査が必要。

Bチャンネルを認証する（チャンネルオーナーが1回）

新しいチャンネルを追加するたびに、そのチャンネルのオーナー権限を持つ Google アカウントで認証する。2通りのフローから選べる。

フロー	こちらの動き	相手の動き	向き
B-1. Device Flow	モカ側のマシンで `yt_auth.py --device-flow` 実行 → URL+コードが表示される	URLを開いてコード入力 → Googleでログイン+許可	クリエイター本人・社外クライアント（推奨）
B-2. Local Server Flow	—	自分のPCにリポジトリをclone → CLI実行 → 自分のブラウザで認証	モカ社内 / エンジニア

B-1. Device Flow（推奨）

モカ側のマシンで実行する。相手にはURLと数字コードを送るだけでOK。

1. 認証コマンドを実行（モカ側）

python3 scripts/yt_auth.py \
  --channel-id UCxxxxxxxxxxxxxxxxxxxxxx \
  --label todoro-chan \
  --device-flow

実行すると以下のような案内がターミナルに出る:

================================================================
  チャンネル「todoro-chan」のオーナーに以下を送ってください:

  1. このURLを開く: https://www.google.com/device
  2. このコードを入力: ABCD-EFGH
  3. Googleアカウントでログインして「許可」をクリック

  有効期限: 30分
================================================================

[info] 相手の同意完了を待っています... (Ctrl+Cで中断)

2. URLとコードを相手に送る（Slack/DM/メールなど）

テンプレ例:

お疲れさまです、モカの〇〇です。
YouTubeチャンネルの分析データ取得のため、以下から許可をいただけますか？

1. このURLを開く: https://www.google.com/device
2. このコードを入力: ABCD-EFGH
3. チャンネルの管理権限を持つGoogleアカウントでログイン → 「許可」をタップ

スマホからでもOKです。30分以内に対応をお願いします。

3. 相手の同意完了を待つ

相手が同意するとモカ側のターミナルが自動で [ok] 同意を確認しました を表示し、tokens/UCxxx.json が生成される。

4. token を Bitwarden にアップロード

他メンバーが使えるよう、生成された JSON を Bitwarden の mocha 共有 Vault にアップロード。タイトル例: insight-analysis-pro / token / todoro-chan。

B-2. Local Server Flow（自分のマシンで完結する場合）

自分が認証するチャンネルの管理者でもある場合（モカ社内チャンネルなど）はこっちが簡単。

git clone git@github.com:mochainc/insight-analysis-pro.git
cd insight-analysis-pro
pip install -r requirements.txt

mkdir -p credentials
# Bitwarden の client_secret.json を credentials/client_secret.json として保存

python3 scripts/yt_auth.py \
  --channel-id UCxxxxxxxxxxxxxxxxxxxxxx \
  --label todoro-chan

ブラウザが自動で開くのでチャンネルオーナーのGoogleアカウントでログイン → 許可。成功すると tokens/UCxxx.json が生成される。あとは Bitwarden へ。

絶対に git commit しない。 tokens/ と credentials/ は .gitignore 済みだが、強制コミットしないように git status でも目視確認。

Cデータを取得する（誰でも何度でも）

1. Bitwarden から token を配置

mkdir -p tokens
# Bitwarden の "insight-analysis-pro / token / xxx" を
# tokens/UCxxxxxxxxxxxxxxxxxxxxxx.json として保存

2. 維持率カーブを取る（一番使う）

python3 scripts/yt_analytics.py retention \
  --channel-id UCxxxxxxxxxxxxxxxxxxxxxx \
  --video-id abcDEFghi12 \
  --out output/retention.json

100ポイント（0%, 1%, ..., 100%）の audienceWatchRatio と relativeRetentionPerformance が JSON で返ってくる。

3. 流入元

python3 scripts/yt_analytics.py traffic \
  --channel-id UCxxxxxxxxxxxxxxxxxxxxxx \
  --video-id abcDEFghi12

4. 登録者増減（チャンネル全体 / 日次）

python3 scripts/yt_analytics.py subscribers \
  --channel-id UCxxxxxxxxxxxxxxxxxxxxxx \
  --start 2026-04-01 --end 2026-04-30

5. 任意クエリ（生 API）

python3 scripts/yt_analytics.py raw \
  --channel-id UCxxxxxxxxxxxxxxxxxxxxxx \
  --metrics views,likes,comments \
  --dimensions day \
  --filters "video==abcDEFghi12"

CLI リファレンス

サブコマンド	用途	必須オプション
`retention`	視聴者維持率カーブ	`--channel-id` `--video-id`
`traffic`	流入元別の視聴数	`--channel-id` `--video-id`
`subscribers`	登録者増減（日次）	`--channel-id`
`raw`	任意 metrics/dimensions/filters	`--channel-id` `--metrics`

共通オプション: --start YYYY-MM-DD / --end YYYY-MM-DD / --out PATH。 --start 省略時は動画公開日（video-id があれば）か30日前にフォールバック。

セキュリティと運用ルール

refresh token = チャンネルの読み取り権限そのもの。漏れたら Google Cloud Console で OAuth クライアントを再発行 → 全 token 失効させる
tokens/ credentials/ は必ず .gitignore。 git status で見えていないこと確認
共有は Bitwarden 共有 Vault のみ。Slack DM / メール添付 / Google Drive は NG
token ファイルはローカル保存時にパーミッション 600（yt_auth.py が自動設定）
退職メンバーが出たら Bitwarden 共有 Vault のアクセス権を外す

トラブルシューティング

症状	原因	対処
`OAuthクライアントが見つかりません`	client_secret.json 未配置	Bitwarden から取得して `credentials/client_secret.json`（Local Flow）または `credentials/client_secret_device.json`（Device Flow）に置く
Device Flow で「タイムアウト」	30分以内に相手が同意しなかった	もう一度コマンド実行して新しいコードを発行
Device Flow で「ユーザーが認証を拒否」	相手が Google 同意画面で「拒否」をクリック	相手に再度依頼。アカウント間違いの可能性もあるので念のため確認
「認証アカウントの所有チャンネルと一致しません」	別アカウントでログインした	ブラウザの Google ログアウト → 正しいオーナーアカウントで再実行
`HttpError 403`	権限不足 / token 失効 / API未有効化	Cloud Console で API 有効化を確認 → `yt_auth.py --force` で再認証
維持率カーブが空配列	視聴回数が閾値未満 / ロング動画ではない	YT は再生数が一定以下のショートではカーブを返さない仕様。動画 ID とロング/ショート種別を確認
`tokenが既に存在`	既に認証済みのチャンネル	上書きする場合は `--force` を付ける（refresh token も再発行される）