portaly-analytics

Portaly Analytics Integration

このスキルを使って、Portaly クリエイターがウェブサイトに Google Analytics 4 をインストールし、Portaly に接続できるようサポートします。回答は実践的な内容にし、長いアーキテクチャの説明より、手順のリスト、コードスニペット、そのまま使える例を優先してください。

クイックスタート

• まず、人間のユーザーが何を達成したいのかを尋ねます。
  • ウェブサイトに GA4 をインストールする → パート A（手順 1～5）
  • GA を Portaly ダッシュボードに接続する → パート B（手順 6）
  • 両方 → パート A ＋ パート B（手順 1～6）

1. 人間のユーザーが何を作ろうとしているのかを確認します。 技術スタック（Next.js／React／vanilla HTML）と、既存の GA4 プロパティがあるかどうかを尋ねます。
2. GA4 のセットアップとイベントトラッキングのインストールを案内します。
3. Portaly でアナリティクスを確認したい場合は、Portaly の認証フローを案内します。
4. インストール手順については、まず references/ga4-setup-guide.md を参照します。
5. 実装にすぐ使える出力を返します。 番号付きの手順、コードサンプル、そのまま使える設定を優先します。

出力スタイル

• 統合作業を人間のユーザーに案内する AI エージェント向けに記述します。
• 人間が次に行う具体的な手順を最初に示します。
• 次の内容にはリストを使います。
  • セットアップ手順
  • 環境変数
  • イベント定義
  • 設定オプション
• ユーザーが別のスタックを指定しない限り、JavaScript または TypeScript の簡潔なコードサンプルを優先します。
• .env の設定と .gitignore の確認手順を必ず含めます。

パート A — GA4 のインストールとイベントトラッキング

1. GA4 プロパティを作成する

• ユーザーが GA4 プロパティを持っていない場合は、作成方法を案内します。
  1. Google Analytics にアクセスします。
  2. 「Admin」→「Create Property」をクリックします。
  3. プロパティ名を入力し、タイムゾーンと通貨を選択します。
  4. サイトの URL を指定して、ウェブデータストリームを設定します。
  5. 測定 ID（G-XXXXXXX）をコピーします。
• ユーザーに測定 ID を提示するよう依頼します。
• .env に保存します。

NEXT_PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXX

• 作業を進める前に、.gitignore に .env が含まれていることを確認します。

2. gtag.js をインストールする

• フレームワークごとのインストール手順については、references/ga4-setup-guide.md を参照します。
• ユーザーの技術スタックに応じて、適切な方法を選びます。
  • Next.js App Router → next/script を使った layout.tsx
  • Next.js Pages Router → next/script を使った _app.js
  • React SPA → index.html の script タグ
  • Vanilla HTML → <head> の script タグ
• 実装例：scripts/gtag-nextjs-example.mjs

3. Portaly のイベントトラッキングを設定する

• Portaly の標準イベント定義については、references/event-tracking-contract.md を参照します。
• ユーザーのアプリの機能に応じて、Portaly の標準イベントをインストールします。
  • portaly_checkout_start — チェックアウトセッションが作成されたとき
  • portaly_checkout_complete — 決済コールバックで完了が確認されたとき
  • portaly_subscription_cancel — サブスクリプションが解約されたとき
  • portaly_page_view — Portaly が埋め込まれたページが表示されたとき
  • portaly_product_view — 商品ページが表示されたとき
• 該当する場合は、GA4 推奨の e コマースイベント（begin_checkout、purchase）に対応付けます。
• 実装例：scripts/track-portaly-events.mjs

4. インストールを確認する

• GA4 のリアルタイムレポートで確認する方法を案内します。
  1. ブラウザーでウェブサイトを開きます。
  2. Google Analytics →「Reports」→「Realtime」に移動します。
  3. ページビューとイベントが表示されることを確認します。
• イベントが表示されない場合は、次の点を確認します。
  • 測定 ID が正しい
  • gtag.js スクリプトが読み込まれている（ブラウザーの Network タブで確認）
  • 広告ブロッカーが干渉していない
  • 同意モードによってブロックされていない（該当する場合）

5. 任意：拡張 e コマーストラッキング

• Portaly の決済機能を連携しているユーザーは、拡張 e コマースイベントを設定します。
  • view_item → プランまたは商品ページが表示されたとき
  • begin_checkout → portaly_checkout_start から対応付け
  • purchase → portaly_checkout_complete から対応付け
• これにより、GA4 の組み込み e コマースレポートを利用できます。

パート B — Google Analytics を Portaly に接続する

6. Portaly に GA データへのアクセスを許可する

GA4 のインストールとデータ収集が完了したら、ユーザーに Portaly への接続を案内します。

1. Portaly Vibe Dashboard に移動します：https://portaly.ai/dashboard/analytics
2. データ分析（Analytics）の設定に移動します
3. Google Analytics を連携をクリックします
4. GA4 プロパティを所有する Google アカウントでサインインします
5. Portaly に Google Analytics データへの読み取り専用アクセスを許可します
6. 接続する GA4 プロパティを選択します
7. 完了です — Portaly Vibe Dashboard に分析ダッシュボードが表示されます

ユーザーに伝えるべき重要なポイント：

• Portaly が要求するのは読み取り専用アクセス（analytics.readonly スコープ）のみです。Portaly が GA4 の設定やデータを変更することはできません。
• Google アカウントの権限から、いつでもアクセスを取り消せます。
• Portaly のダッシュボードには、接続した GA4 プロパティのデータ（セッション、ページビュー、トラフィックソース、Portaly 固有のイベントなど）が表示されます。
• GA4 データの処理には24～48 時間かかります。新しくインストールしたトラッキングで過去のデータが Portaly に表示されるまで、1～2 日かかる場合があります。

ガードレール

• 測定 ID の形式：必ず G-XXXXXXX です。ユーザーが別の形式（例：UA-XXXXX）を指定した場合は、Universal Analytics ID なので、代わりに GA4 プロパティを作成するよう案内してください。
• 認証情報のセキュリティ：測定 ID（G-XXXXXXX）は秘密情報ではなく、ページのソースから確認できます。ただし、設定を簡単に管理できるよう、必ず .env に保存し、.gitignore に .env が含まれていることを確認してください。
• クロスドメイントラッキング：ユーザーのアプリがチェックアウトのために portaly.ai にリダイレクトし、その後戻る場合は、セッションの継続性を保つために GA4 でクロスドメイントラッキングを設定することをおすすめします。
  1. GA4 Admin → Data Streams → Web → Configure tag settings → Configure your domains に移動します
  2. 両方のドメインを追加します
• 広告ブロッカー：広告ブロッカーを使用している訪問者の中には、gtag.js をブロックする人もいます。GA4 の数値は常に実際より少なくなります。トラッキング精度が 100% になると約束しないでください。
• 同意モード：ユーザーのサイトで Cookie の同意（GDPR など）が必要な場合は、GA4 の同意モードを実装するよう案内してください。
• データの鮮度：GA4 データの処理には 24～48 時間かかります。リアルタイムデータは GA4 独自の Realtime レポートで確認できますが、Portaly のダッシュボードは処理済みデータを使用します。
• Portaly の認可：Portaly の OAuth 接続は、すべて Portaly がホストするフローで処理されます。ユーザーが Google Cloud プロジェクトや OAuth クライアントを作成したり、API キーを管理したりする必要はありません。「接続」をクリックして認可するだけです。

推奨する回答の構成

このスキルを使用して回答する際は、次の順序をおすすめします。

1. 目標の概要
2. 前提条件の確認
3. 手順を追ったセットアップ方法
4. 環境変数の設定
5. コードの実装
6. 検証手順
7. トラブルシューティングの注意点

リソース

• references/ga4-setup-guide.md フレームワーク別の gtag.js インストール手順と、ページビュー／イベントトラッキングの設定に使用します。
• references/event-tracking-contract.md Portaly の標準イベント名、パラメーター、GA4 の E コマースイベントのマッピングに使用します。
• scripts/gtag-nextjs-example.mjs Next.js アプリケーションに gtag.js をインストールするためのリファレンス実装です。
• scripts/track-portaly-events.mjs Portaly 固有のイベントをトラッキングするためのリファレンス実装です。