# Googleアナリティクスを連携する

Googleアナリティクス4（GA4）のプロパティに、Kafkaiの読み取り権限を付与します。連携すると、トラフィック、ページ、チャネル、キーイベントのデータを、AIエージェントからKafkai経由で読み取れるようになります。作業は、Kafkaiの読み取り用アドレス（メールアドレス）をプロパティのユーザーに追加するだけです。パスワードを共有する必要はなく、KafkaiがGoogleアナリティクスの設定を変更することもありません。

読み取り用アドレスは、[Google Search Consoleの連携](https://kafkai.com/ja/docs/google-search-console/)で使うものと同じです。

## 準備するもの

- 対象サイトのKafkaiプロジェクト
- GA4プロパティの**管理者**の役割。ユーザーを追加できるのは管理者だけです
- プロジェクトのドメインをURLに持つウェブデータストリーム

Kafkaiは、データストリームのURLでプロジェクトとプロパティを対応付けます。URLは、Googleアナリティクスの**管理** > **データ ストリーム**で確認できます。サブドメイン（`blog.hogehoge.jp`）のプロジェクトは、登録ドメイン（`hogehoge.jp`）のストリームにも対応します。

## 1. Kafkaiでドメインを認証する

Kafkaiアカウントの[ドメインの管理ページ](https://kafkai.com/ja/accounts/domains/)を開きます。ページに表示されたTXTレコードを、そのドメインのDNSに追加します。ドメインのDNSを編集できない場合（ホスティングサービスのサイトなど）は、同じページに表示されたメタタグを、サイトの `<head>` に追加します。どちらかを設置したら、**確認**を選択します。エージェントに「Kafkaiでドメインを認証して」と依頼することもできます。ドメイン認証は無料です。Search Consoleの連携でドメインを認証済みの場合、この手順は不要です。

ドメインを認証するまで、Kafkaiはそのドメインについて何も返しません。GA4のプロパティがあるかどうかも返しません。詳しくは、ツールリファレンスの[ドメイン認証](https://kafkai.com/ja/docs/tools/#ドメイン認証)をご覧ください。

## 2. Kafkaiの読み取り用アドレスをコピーする

[ドメインの管理ページ](https://kafkai.com/ja/accounts/domains/#connect-search-console)で、Kafkaiの読み取り用アドレスをコピーします。このページのスクリーンショットではアドレスの大半を隠しています。画像から入力するのではなく、アカウントの画面からコピーしてください。

## 3. プロパティのアクセス設定を開く

[Googleアナリティクス](https://analytics.google.com/)で、対象のプロパティを選択します。歯車アイコンの**管理**を選択し、**プロパティ**の欄にある**プロパティのアクセス管理**を選択します。**アカウントのアクセス管理**は選ばないでください。アカウント単位で権限を付与すると、アカウント内のすべてのプロパティが対象になります。

<img src="https://kafkai.com/static/images/docs/connect/ga4-01-admin-ja.webp" alt="Googleアナリティクスの管理画面。歯車の管理アイコンと、プロパティ欄のプロパティのアクセス管理が枠で囲まれている" width="800" loading="lazy">

## 4. 読み取り用アドレスを「閲覧者」で追加する

**＋**ボタンから**ユーザーを追加**を選択します。メールアドレスの欄にKafkaiの読み取り用アドレスを貼り付けます。役割の**閲覧者**にチェックを入れたら、**追加**を選択します。新しいユーザーへのメール通知は、オフにしてもかまいません。読み取り用アドレス宛てのメールを受け取る人はいません。

**閲覧者**は、Googleアナリティクスでもっとも低い役割です。Kafkaiができるのは、レポートの閲覧だけです。追加すると、ユーザー一覧に読み取り用アドレスが**閲覧者**で表示されます。

<img src="https://kafkai.com/static/images/docs/connect/ga4-02-property-access-ja.webp" alt="Googleアナリティクスのプロパティのアクセス管理画面。読み取り用アドレスの行が枠で囲まれ、役割は閲覧者になっている" width="800" loading="lazy">

## 5. エージェントにデータを依頼する

調査の実行は不要です。KafkaiはGoogleアナリティクスを呼び出しのたびに直接読み取るため、次の呼び出しでプロパティが見つかります。エージェントに「Kafkaiで直近30日間のGoogleアナリティクスのトラフィックを見せて」と依頼します。エージェントは `kafkai_get_ga_analytics_data` を呼び出します。

アドレスを追加する前にエージェントへデータを依頼していた場合は、Kafkaiがプロパティを探し直すまで最大10分かかります。

## 連携の状態を確認する

応答には常に `ga_analytics.status` が含まれます。

| ステータス | 意味 |
| --- | --- |
| `not_verified` | ドメインを認証していません。手順1を完了します。 |
| `not_connected` | ドメインに対応するプロパティが見つかりません。手順3と手順4、およびデータストリームのURLを確認します。 |
| `ambiguous` | このドメインのデータストリームを持つプロパティが複数あります。使用するプロパティのIDを、[お問い合わせ](https://kafkai.com/ja/contact/)からお知らせください。 |
| `unavailable` | この呼び出しでは、Googleアナリティクスから応答がありませんでした。1分ほど待ってから、もう一度依頼します。 |
| `ready` | データを利用できます。 |

`kafkai_get_ga_analytics_data` のレポートの種類と引数については、[ツールリファレンス](https://kafkai.com/ja/docs/tools/)をご覧ください。

## 数値を読むときの注意

- Googleアナリティクスは、データの処理に24〜48時間かかる場合があります。このため、直近の数日は数値が確定していないことがあります。ツールは、デフォルトで前日までの30日間を読み取ります。
- Googleアナリティクスは、プライバシーを保護するために件数の少ない行を非表示にします。この場合、応答には `subject_to_thresholding` が含まれます。
- 数値はSearch Consoleとは一致しません。Googleアナリティクスはすべての流入元のセッションを数えるのに対し、Search ConsoleはGoogle検索からのクリックを数えます。

## 権限を取り消す

Kafkaiによる読み取りを停止するには、Googleアナリティクスで**管理** > **プロパティのアクセス管理**を開きます。読み取り用アドレスの行のメニューから**アクセス権を削除**を選択します。削除した時点から、Kafkaiはプロパティを読み取れなくなります。
