ga-auth

GA4 認証・接続スキル（ga-auth）

マーケターが gcloud を使わず、「ログイン → 許可 → プロパティ選択」の手順で GA4 に接続できるようにします。 マーケターは、組織の管理者が作成したデスクトップ OAuth クライアント（.ga4/oauth_client.json）を受け取り、それを使ってログインします。 処理の確定部分は scripts/ 内の Python スクリプトが実行します。どのステップを適用するかは自分で判断してください。

言語

ユーザーの言語で応答します。ユーザーが韓国語で書いた場合は韓国語で、英語で書いた場合は英語で回答します。 これは、セットアップの案内、進捗状況の報告、結果、エラーの説明など、すべてのステップに適用されます。

GA4 API 識別子（eventCount、sessionSource、runReport）、ファイル名とディレクトリ名（.ga4/token.json）、シェルコマンド、JSON のフィールド名は翻訳しないでください。

スクリプトの出力をそのままユーザーに見せてはいけません。 スクリプトは常に英語の error／hint 文字列を出力します。スクリプトが "ok": false を返した場合、ユーザーに見せる前に hint をユーザーの言語に書き換える必要があります。英語のまま貼り付けたり、生の JSON を見せたりしないでください。識別子、パス、コマンドはそのまま保持し、周囲の説明文のみ翻訳してください。

例 — スクリプトが次を返した場合： {"ok": false, "hint": "token.json is missing. Log in first with the ga-auth skill."} 韓国語話者のユーザーには、次のように伝えます： 로그인 정보(.ga4/token.json)가 없어요. ga-auth 스킬로 먼저 로그인할게요. 次のようにしてはいけません："token.json is missing. Log in first with the ga-auth skill."

作業原則（重要）

対象となるのは技術に詳しくないマーケターです。GCP や OAuth の概念に触れたことがない人がほとんどなので、次のルールに従ってください。

• 作業を小さなステップに分けます。 長いガイドを一度に貼り付けず、1〜2 ステップずつ案内し、動作を確認してから次に進みます。
• 各ステップで「何をするか／なぜするか」を一行で説明します。 クリックするボタンの名前を正確に伝えます。
• よくある落とし穴を3つ、事前に伝えます： ①テストユーザーの登録を忘れる、②「未確認のアプリ」に関する警告（これは正常です）、③アカウントを切り替える場合、新しいアカウントもテストユーザーとして登録する必要がある。
• 面倒な作業はユーザーの代わりに行います。 可能な限り、ファイルの配置やコマンドの実行は自分で処理し、ユーザーにはコンソールでの操作とブラウザーからのログインだけを行ってもらいます。

インタープリタールール

• ga4_status.py、ga4_auth.py：システムの python3 で実行できます（標準ライブラリのみ）
• ga4_login.py、ga4_admin.py：.ga4/venv/bin/python で実行する必要があります（GA4 と oauthlib のライブラリが必要）
• {SKILLS_DIR} = これらの ga スキルがインストールされているディレクトリのパス。現在のスキルの ディレクトリの親ディレクトリです（Claude Code プロジェクトでは .claude/skills、ほかのエージェントではそれぞれ異なる場所を使用します）。 実際のパスに置き換えてください。コマンドはプロジェクトのルートから実行します。

ステップ 1：ステータスの確認（必ず最初に行う）

python3 {SKILLS_DIR}/ga-auth/scripts/ga4_status.py

まず ga4_dir_present を確認してください。 これが false の場合、以下のすべてのフラグも false になります。この組み合わせは、セットアップが壊れていることを意味するわけではありません。.ga4 は現在の作業ディレクトリを基準に解決されるため、コマンドを間違ったフォルダーから実行した場合にも同じ状態になります。出力には、検索した正確なパスを示す hint が含まれています。ステップ 2 に進む前に、マーケターのプロジェクトディレクトリにいることを確認するか、GA4_DIR を設定して、再実行してください。すでに接続済みのユーザーを OAuth セットアップに戻すと、間違った問題に対処するための、長くつらい遠回りをさせることになります。

ga4_dir_present が true になったら、出力 JSON を使って進むステップを判断してください。

oauth_client_present	token_present	property_configured	→ ステップ
false	-	-	OAuth クライアントを取得する（2）
true	false	-	ログインする（3）
true	true	false	プロパティを選択する（4）
true	true	true	接続済み（5）

token_present は簡易的な確認です（token.json が存在し、refresh_token を含んでいるかを確認します）。実際の有効性は、最初の API 呼び出しで確認されます。

依存関係の確認：同じ出力にある venv_present／deps_ready も確認してください。venv_present が false の場合は、references/setup-guide.md のセクション 1 に従って venv を作成し、3 つの requirements ファイルをインストールしてください。deps_ready が false の場合は、deps_fix の pip コマンドを自分で実行し（「必要なライブラリをインストールします」と 1 行で説明してください）、再確認してください。マーケターに pip の実行を頼まないでください。deps_ready が null の場合は、確認自体が失敗しています。依存関係が不足していると決めつけず、そのまま先に進んでください。

ステップ 2：OAuth クライアントを取得する（見つからない場合）

まず、全体像を簡潔に示してください。マーケターが行う 2 つの役割と 3 つのステップです。

[Administrator] Create the OAuth client once in GCP -> hand over oauth_client.json
      └─▶ [Marketer] 1. place the file -> 2. log in and allow in the browser -> 3. select a property

次に、ユーザーが現在どの状態にあるかを確認します。

• oauth_client.json がすでに存在する場合（以前の作業で作成済み、または管理者から受け取っている場合）は、ファイルパスを確認し、このスキルで .ga4/oauth_client.json にコピーして、ステップ 3 に進んでください。この場合も、最上位のキーが installed であることを確認してください。web の場合はデスクトップアプリではないため、ログインに失敗します（ga4_login.py は呼び出し前に処理を止め、必要なものを説明します）。
• 新たに作成する必要がある場合は、references/admin-setup-guide.md に沿って、細かいステップに分けて進めてください。順序は、GCP プロジェクト → 2 つの API を有効化 → 同意画面 → デスクトップ OAuth クライアントを作成 → JSON をダウンロード、です。
  • 同意画面の手順はアカウントの種類によって異なります。 まず「会社の Workspace アカウントですか、それとも個人の @gmail ですか？」と尋ね、分岐してください。Workspace では Internal を選択します（最も簡単です）。個人の Gmail では External を選択し、自分のメールアドレスをテストユーザーとして追加します（⚠️ この登録を省略すると、ログインできません）。
• ダウンロードが完了したら、ファイルパスを確認し、このスキルで配置してください。

  mkdir -p .ga4 && cp "<download-path>" .ga4/oauth_client.json
  

配置後、構造を確認してください（最上位のキーが installed であり、redirect_uris に http://localhost が含まれていれば、有効なデスクトップアプリです）。

• venv がない場合は、references/setup-guide.md のセクション 1 に従って、venv の作成とインストールを進めてください。

ステップ 3：ログイン（マーケター、gcloud 不要）

実行する前に、ブラウザーで何が起こるかを説明してください：

1. ブラウザーのタブが自動的に開きます → GA4 にアクセスできるアカウントを選択してください
2. （個人の Gmail／未確認アプリの場合）「未確認のアプリ」という警告は正常です → 詳細設定 → 続行／... に移動
3. 「Google アナリティクスのデータの表示」権限を求める画面 → 許可
4. 「認証フローが完了しました...」と表示されたら成功です → ウィンドウを閉じてください

次に実行してください（ブラウザーでのフローが完了するまで処理がブロックされるため、十分に長いタイムアウトを設定してください）：

.ga4/venv/bin/python {SKILLS_DIR}/ga-auth/scripts/ga4_login.py

ok:true は .ga4/token.json が作成されたことを意味します。ok:false の場合は、エラーのヒント（内部設定、テストユーザー、警告の回避）をユーザーの言語で説明して、再試行してください。

リモート／SSH・ヘッドレス環境に関する注意： ループバックログインでは、ブラウザーとスクリプトを同じマシンで実行する必要があります。リモート環境の場合は、ユーザー自身の PC でログインしてもらい、生成された token.json をサーバーにコピーしてください（references/setup-guide.md）。

ステップ 4：プロパティを選択する

1. プロパティ一覧を取得します。

   .ga4/venv/bin/python {SKILLS_DIR}/ga-auth/scripts/ga4_admin.py list-properties
   

2. 見やすいようにアカウントごとにまとめて表示し、使用するプロパティをユーザーに選んでもらいます。件数が多い場合は、アカウントごとの件数を要約し、代表となるプロパティを選んでもらいます。

3. 一覧が空（[]）の場合 — 認証には成功しましたが、このアカウントにはアクセス可能な GA4 プロパティがありません。最もよくある原因は、間違ったアカウントでログインしていることです。このアカウントに GA4 へのアクセス権があることを確認し、必要であれば、正しいアカウントでもう一度ログインします（下記の再ログインに関する注記を参照）。

4. プロパティの通貨、タイムゾーン、データストリームを調べます。上記の一覧にはこれらの情報が含まれていません。

   .ga4/venv/bin/python {SKILLS_DIR}/ga-auth/scripts/ga4_admin.py get-property <PROPERTY_ID>
   

   同じ呼び出しで data_streams と platforms も報告されます。つまり、このプロパティがウェブ、iOS アプリ、Android アプリ、または複数のプラットフォームからデータを収集しているかどうかです。調査結果を一文でマーケターに伝えてください（「このプロパティにはウェブサイトと iOS アプリがあります」など）。これは、マーケターが最初に確認または修正できる情報であり、後続のすべてのスキルの判断の基礎となるためです。

   platforms が [] の場合、このプロパティにはデータストリームがなく、何も収集されていません。次に進まず、はっきりと伝えてください。キーが存在しない場合は、検索に失敗しています。致命的な問題ではないため、その情報なしで続行します。

5. ステップ 4 のすべての値を渡して、選択内容を保存します。

   python3 {SKILLS_DIR}/ga-auth/scripts/ga4_auth.py save-property <PROPERTY_ID> \
     --name "<NAME>" --account "<ACCOUNT>" --currency "<CURRENCY_CODE>" --time-zone "<TIME_ZONE>" \
     --retention-months "<EVENT_DATA_RETENTION_MONTHS>" --platforms "<PLATFORMS>"
   

   検索を省略しないでください。 どちらの値も推測できず、回答の意味を変えてしまいます。開発中に計測されたプロパティでは、Asia/Seoul 時間で処理され、収益は USD で報告されるため、収益をウォンとして読むと約 1300 倍の誤差になります。レポートのレスポンスにもこれらの値は含まれますが、それは runReport 系のみです。リアルタイムのレスポンスにはメタデータがまったくないため、これがなければ通貨を特定できません。ステップ 4 に失敗した場合も、残りの情報は保存してください。フィールドは null として保存され、「通貨なし」ではなく「不明」として読み取られます。 ステップ 4 で報告されなかったフラグは指定しないでください。get-property は読み取れなかったキーを省略します。代わりに空文字列を渡すのは同じではありません。スクリプトが正規化しますが、フラグを省略した場合にのみ正しく「不明」として読み取られます。 --retention-months が重要なのはファネルのみですが、その影響は大きいです。プロパティのデータ保持期間を超えると、同じ期間に対する runReport は通常どおり回答する一方で、runFunnelReport はエラーなしで 0 行を返します。この値がないと、ga-use は空のファネルと「コンバージョンした人がいない」状態を区別できません。ga-use は黙って処理を続けるのではなく、その旨を明示するため、マーケターは確信を持って 0 と回答されるのではなく、チェックが実行されなかったことを把握できます。 --platforms には、ステップ 4 の platforms 配列を、GA4 独自の表記（web、iOS、Android）のままカンマ区切りリストとして指定します。小文字にしないでください。これらは GA4 の platform ディメンションが返す値なので、ios でフィルターを作成すると何も一致せず、エラーも報告されません。（スクリプトは現在、念のため大文字・小文字を修正しますが、それでも正しい表記を使用してください。この補正機能が認識するのは、現在 GA4 が使用する 4 つの値だけです。）ステップ 4 でプロパティにストリームがないとわかった場合は none を渡します。検索に失敗した場合はフラグを省略します。推測ではなく「不明」として保存されます。配列に unknown が含まれている場合は、そのまま他の値と一緒に渡してください。これはストリームを分類できなかったことを意味しており、省略すると、下流で「判別できなかった」が確信を伴うプラットフォームの回答に変わってしまいます。 このコマンドは config.json を一から書き換えます。そのため、ステップ 4 と 5 は必ずセットで扱ってください。省略したフラグは、以前の保存時に値があっても null として保存されます。プラットフォーム一覧を更新するためにステップ 5 だけを再実行すると、通貨、タイムゾーン、保持期間も一緒に消えてしまいます。

アカウントを切り替えるために再ログインする

別のアカウントで再度ログインするには、ga4_login.py をもう一度実行します（prompt=consent を使用するため、アカウント選択画面が適切に表示されます）。 ただし、個人用 Gmail アカウント（外部テストモード）を使用する場合、新しいアカウントも OAuth 同意画面のテストユーザーとして登録済みである必要があります。登録されていない場合、「アクセスがブロックされました：アプリはテストモードです」と表示され、ログインに失敗します。まずユーザーに登録してもらってから、再度ログインしてください。

ステップ 5：接続済み

接続が完了したことをユーザーに伝え、分析には ga-use スキル、イベント分類には ga-taxonomy スキルを案内してください。 ユーザーから明示的に再設定（再ログイン／プロパティの変更）を求められた場合は、上記の表にかかわらず、その手順をやり直してください。

ファイルの場所

• ランタイム状態：プロジェクト内の .ga4/（oauth_client.json、token.json、config.json、venv/）
• oauth_client.json：管理者が作成したデスクトップ OAuth クライアント（references/admin-setup-guide.md）。
• token.json：ログイン時に生成される認証情報（自動更新されます）。
• GA4_DIR 環境変数を使用すると、.ga4 の場所を変更できます（デフォルト：<cwd>/.ga4）。