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

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

読み取り用アドレスは、Google Search Consoleの連携で使うものと同じです。

準備するもの

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

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

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

Kafkaiアカウントのドメインの管理ページを開きます。ページに表示されたTXTレコードを、そのドメインのDNSに追加します。追加できたら、確認を選択します。エージェントに「Kafkaiでドメインを確認して」と依頼することもできます。ドメイン確認は無料です。Search Consoleの連携でドメインを確認済みの場合、この手順は不要です。

ドメインを確認するまで、Kafkaiはそのドメインについて何も返しません。GA4のプロパティがあるかどうかも返しません。詳しくは、ツールリファレンスのドメイン確認をご覧ください。

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

ドメインの管理ページで、Kafkaiの読み取り用アドレスをコピーします。このページのスクリーンショットではアドレスの大半を隠しています。画像から入力するのではなく、アカウントの画面からコピーしてください。

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

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

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

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

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

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を、お問い合わせからお知らせください。
`unavailable`	この呼び出しでは、Googleアナリティクスから応答がありませんでした。1分ほど待ってから、もう一度依頼します。
`ready`	データを利用できます。

kafkai_get_ga_analytics_data のレポートの種類と引数については、ツールリファレンスをご覧ください。

数値を読むときの注意

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

権限を取り消す

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