Menggunakan Penasihat Analytics untuk membuat kueri dan menganalisis data Anda

Metode chat dari Data API memberikan akses terprogram ke Penasihat Analytics — asisten analisis yang didukung AI yang membantu Anda mengajukan kueri, menganalisis, dan mendiagnosis data Google Analytics menggunakan bahasa alami.

Meskipun tersedia secara interaktif dalam antarmuka pengguna Google Analytics, chat API memungkinkan developer, agen AI otonom, dan alat internal berinteraksi dengan Penasihat Analytics secara terprogram melalui HTTP.

Penting: Produk ini menggunakan AI dan mungkin menampilkan info yang tidak akurat. Aktivitas percakapan Anda dapat digunakan untuk meningkatkan kualitas produk, dan penggunaan Anda tunduk pada Persyaratan, Kebijakan Penggunaan AI, dan Kebijakan Privasi Google.

Ringkasan

Metode chat memungkinkan pertanyaan data ad hoc satu giliran dan sesi percakapan multi-giliran:

  1. Kueri sekali putaran: Ajukan pertanyaan analitis langsung (seperti, "Apa saja saluran traffic teratas kami minggu lalu?") dan terima jawaban dalam bahasa alami beserta tabel data terstruktur.
  2. Percakapan multi-putaran: Teruskan sessionId untuk mempertahankan histori percakapan dan mengajukan pertanyaan lanjutan diagnostik (seperti, "Mengapa traffic organik menurun pada periode tersebut?").
  3. Respons data terstruktur: Selain narasi teks, respons berisi blok table terstruktur dengan judul kolom dan baris.
  4. Pemantauan kuota Chat: Periksa kuota token Chat per hari dan per jam yang tersisa dengan menyetel returnPropertyQuota ke true.

Autentikasi

Panggilan ke metode chat memerlukan otorisasi OAuth 2.0 dengan cakupan berikut:

Sebelum memulai

  1. Instal dan lakukan inisialisasi gcloud CLI.

  2. Untuk membuat Kredensial Default Aplikasi dan memberikan cakupan yang diperlukan ke akun Anda, jalankan perintah berikut:

    gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.chatbot.read"

  3. Di UI Google Analytics, berikan akses ke properti Google Analytics untuk akun pengguna Anda.

  4. Konfigurasi variabel lingkungan Anda dengan memasukkan perintah berikut. Ganti PROJECT_ID dengan ID project Anda dan PROPERTY_ID dengan ID properti Google Analytics Anda. 

      export PROJECT_ID=PROJECT_ID
  export PROPERTY_ID=PROPERTY_ID

Contoh 1: Kueri sekali putaran dengan pelacakan kuota

Untuk memulai percakapan baru, buat ChatRequest yang berisi userQuery Anda. Tetapkan returnPropertyQuota ke true untuk memeriksa sisa saldo token Anda.

Skenario: Pendapatan dan Rasio Konversi menurut Perangkat

Anda ingin membandingkan pendapatan dan rasio konversi sesi di seluruh perangkat selama 30 hari terakhir.

Permintaan HTTP

curl -X POST \
  "https://analyticsdata.googleapis.com/v1alpha/properties/${PROPERTY_ID}:chat" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "userQuery": "Compare our revenue and conversion rate across mobile vs desktop over the last 30 days.",
    "returnPropertyQuota": true
  }'

Respons HTTP

Responsnya berisi:

  • sessionId yang baru ditetapkan yang dapat Anda gunakan untuk giliran tindak lanjut.
  • Daftar blocks yang berisi ringkasan bahasa alami (text) dan tabel terstruktur (table). Blok teks dapat berisi pemformatan Markdown seperti teks tebal, judul, dan link.
  • Detail propertyQuota properti.
{
  "sessionId": "692e9ab9-b338-4426-b006-a05f21ac7cd6",
  "blocks": [
    {
      "text": "Your report on revenue and conversion rates for mobile vs. desktop over the last 30 days (August 15 - September 13, 2026) is ready.\n\nHere is a summary of your revenue and conversion rate by device category:\n"
    },
   {
      "table": {
        "headers": [
          {
            "header": "Device Category",
            "dataType": "string"
          },
          {
            "header": "Total Revenue",
            "dataType": "string"
          },
          {
            "header": "User Conversion Rate",
            "dataType": "string"
          }
        ],
        "rows": [
          {
            "columns": [
              {
                "value": "Desktop"
              },
              {
                "value": "$17,412.62"
              },
              {
                "value": "99.9%"
              }
            ]
          },
          {
            "columns": [
              {
                "value": "Mobile"
              },
              {
                "value": "$15,309.41"
              },
              {
                "value": "99.46%"
              }
            ]
          }
      }
    },
    {
      "text": "**Revenue and Conversion Rate Trends:**\n\nRevenue from desktop devices saw a peak on August 18th, while mobile revenue peaked on August 30th. Conversion rates remained high and relatively stable for both desktop and mobile throughout the period."
    },
    {
      "text": "This product uses AI and may display inaccurate info. Your chat activity may be used to improve the product and your use is subject to Google's [Terms](https://policies.google.com/terms), [AI Use Policy](https://policies.google.com/terms/generative-ai/use-policy), and [Privacy Policy](https://policies.google.com/privacy). [Learn more about Chat AI Privacy](https://support.google.com/helpguide/answer/14185196)."
    }
  ],
   "propertyQuota": {
    "tokensPerDay": {
      "consumed": 26849,
      "remaining": 3723151
    },
    "tokensPerHour": {
      "consumed": 26849,
      "remaining": 473151
    }
  }
}

Contoh 2: Diagnostik percakapan bolak-balik

Untuk mengajukan pertanyaan lanjutan sambil mempertahankan konteks, sertakan sessionId yang ditampilkan oleh respons sebelumnya dalam permintaan Anda.

Skenario: Membandingkan dengan periode sebelumnya

Sebagai tindak lanjut dari perbandingan perangkat sebelumnya, Anda meminta Penasihat untuk membandingkan hasil dengan periode sebelumnya.

Permintaan HTTP

curl -X POST \
  "https://analyticsdata.googleapis.com/v1alpha/properties/${PROPERTY_ID}:chat" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "692e9ab9-b338-4426-b006-a05f21ac7cd6",
    "userQuery": "Compare results with the same period in the previous mounth."
  }'

Respons HTTP

Penasihat Analytics menggunakan memori sesi untuk mengorelasikan hasil dengan periode sebelumnya.

{
  "sessionId": "eb3284b2-49ce-4aed-b6d0-fdc15cb87b5f",
  "blocks": [
    {
      "text": "The following table provides a detailed comparison of total revenue and user conversion rate by device category for the two periods.\n"
    },
    {
      "table": {
        "headers": [
          {
            "header": "Device Category",
            "dataType": "string"
          },
          {
            "header": "Metric",
            "dataType": "string"
          },
          {
            "header": "Jul 16 - Aug 15, 2026",
            "dataType": "string"
          },
          {
            "header": "Aug 16 - Sep 14, 2026",
            "dataType": "string"
          }
        ],
        "rows": [
          {
            "columns": [
              {
                "value": "Desktop"
              },
              {
                "value": "Total Revenue"
              },
              {
                "value": "$17,412.62"
              },
              {
                "value": "$19,565.46"
              }
            ]
          },
          {
            "columns": [
              {
                "value": "Desktop"
              },
              {
                "value": "User Conversion Rate"
              },
              {
                "value": "1.90%"
              },
              {
                "value": "1.95%"
              }
            ]
          },
          {
            "columns": [
              {
                "value": "Mobile"
              },
              {
                "value": "Total Revenue"
              },
              {
                "value": "$13,997.19"
              },
              {
                "value": "$15,309.41"
              }
            ]
          },
          {
            "columns": [
              {
                "value": "Mobile"
              },
              {
                "value": "User Conversion Rate"
              },
              {
                "value": "1.95%"
              },
              {
                "value": "1.99%"
              }
            ]
          }
      }
    }
  ]
}

Struktur Respons & Blok Data

Objek ChatResponse menampilkan komponen terstruktur dalam array blocks:

Jenis Pemblokiran Kolom Deskripsi
Narrative Text blocks[].text Penjelasan yang dapat dibaca manusia dan poin-poin penting analisis tingkat tinggi.
Tabel Terstruktur blocks[].table Perincian data tabular yang berisi headers (nama dan jenis data) dan rows (nilai sel).

Jenis Data Header Tabel

Kolom di blocks[].table.headers mendeskripsikan jenis data semantik:

  • string: Nilai teks kategori (misalnya, "desktop", "/shop/apparel").
  • float: Bilangan floating point numerik.

Pengelolaan Kuota Chat

Permintaan Penasihat Analytics menggunakan token chat berdasarkan kompleksitas kueri. Status kuota saat ini ditampilkan di propertyQuota saat returnPropertyQuota adalah true:

Aplikasi Integrasi yang Disarankan

Metode properties.chat membuka beberapa arsitektur integrasi di seluruh tim dan alat:

Bot Chat & Kolaborasi Perusahaan

Hubungkan ruang kerja chat tim Anda langsung ke Google Analytics.

  • Sesi Berangkai: Menyimpan sessionId terhadap ID rangkaian pesan chat untuk memungkinkan anggota tim mengajukan pertanyaan lanjutan secara kolaboratif.
  • Rendering Kartu Informasi: Memformat blok respons table menjadi widget kartu interaktif.

Agen AI Otonom & Alat Model Context Protocol (MCP)

Lengkapi pengelola LLM (seperti Gemini, LangChain, atau Claude) dengan alat analisis GA:

  • Daripada memaksa LLM untuk membuat kueri runReport yang kompleks, agen LLM dapat memanggil metode chat dengan maksud bahasa alami.
  • Agen menerima ringkasan dengan faktualitas tinggi dan tabel terstruktur untuk disintesis menjadi rekomendasi pemasaran multisaluran.

Pemberitahuan & Rangkuman Eksekutif Otomatis

Buat layanan terjadwal yang menyelidiki anomali secara proaktif:

  • Cron job harian membuat kueri: "Summarize yesterday's key performance metrics and identify any anomalous drop in conversions." (Ringkas metrik performa utama kemarin dan identifikasi penurunan konversi yang tidak normal).
  • Jika anomali ditemukan, skrip akan otomatis memicu kueri lanjutan untuk mendiagnosis penyebab utama dan memposting ringkasan ke dasbor internal atau sistem CRM.