Verilerinizi sorgulamak ve analiz etmek için Google Analytics'teki Ask Advisor'ı programatik olarak kullanma

Data API'nin chat yöntemi, Google Analytics'te Ask Advisor'a programatik erişim sağlar. Ask Advisor, doğal dil kullanarak Google Analytics verilerinizi sorgulamanıza, analiz etmenize ve teşhis etmenize yardımcı olan yapay zeka destekli bir analiz asistanıdır.

Ask Advisor, Google Analytics kullanıcı arayüzünde etkileşimli olarak kullanılabilir. chat API ise geliştiricilerin, otonom yapay zeka ajanlarının ve dahili araçların HTTP üzerinden Ask Advisor ile programatik olarak etkileşim kurmasına olanak tanır.

Önemli: Bu ürün yapay zeka kullanıyor ve yanlış bilgiler gösterebilir. Sohbet etkinliğiniz, ürünü iyileştirmek için kullanılabilir. Bu ürünü kullanımınız Google'ın Şartları, Yapay Zeka Kullanım Politikası ve Gizlilik Politikası'na tabidir.

Genel Bakış

chat yöntemi, hem tek turlu özel veri sorularını hem de çok turlu sohbet oturumlarını etkinleştirir:

  1. Tek adımlı sorgular: "Geçen hafta en çok trafik alan kanallarımız hangileriydi?" gibi anlık analiz soruları sorabilir ve yapılandırılmış veri tablolarıyla birlikte doğal dilde yanıtlar alabilirsiniz.
  2. Çok adımlı sohbetler: Sohbet geçmişini korumak ve teşhise yönelik ek sorular sormak için (ör. "Bu dönemde organik trafik neden azaldı?") bir sessionId iletin.
  3. Yapılandırılmış veri yanıtları: Yanıtlar, metin anlatımlarının yanı sıra sütun başlıkları ve satırlar içeren yapılandırılmış table blokları içerir.
  4. Sohbet kotası izleme: returnPropertyQuota değerini true olarak ayarlayarak kalan günlük ve saatlik sohbet jetonu kotalarını inceleyin.

Kimlik doğrulama

chat yöntemine yapılan çağrılar, aşağıdaki kapsamda OAuth 2.0 yetkilendirmesi gerektirir:

Başlamadan önce

  1. gcloud CLI'yı yükleyin ve ilk kullanıma hazırlayın.

  2. Uygulama Varsayılan Kimlik Bilgileri'ni oluşturmak ve hesabınıza gerekli kapsamları vermek için aşağıdakileri çalıştırın:

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

  3. Google Analytics kullanıcı arayüzünde, kullanıcı hesabınıza bir Google Analytics mülküne erişim izni verin.

  4. Aşağıdakileri girerek ortam değişkenlerinizi yapılandırın. PROJECT_ID yerine projenizin kimliğini, PROPERTY_ID yerine ise Google Analytics mülkünüzün kimliğini yazın. 

      export PROJECT_ID=PROJECT_ID
  export PROPERTY_ID=PROPERTY_ID

1. örnek: Kota takibiyle tek adımlı sorgu

Yeni bir görüşme başlatmak için userQuery değerinizi içeren bir ChatRequest oluşturun. Kalan jeton bakiyenizi incelemek için returnPropertyQuota değerini true olarak ayarlayın.

Senaryo: Cihaza Göre Gelir ve Dönüşüm Oranı

Son 30 gün içinde cihazlar genelindeki geliri ve oturum dönüşüm oranını karşılaştırmak istiyorsunuz.

HTTP İsteği

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
  }'

HTTP Yanıtı

Yanıtta şunlar yer alıyor:

  • Takip sıralarında kullanabileceğiniz yeni atanmış bir sessionId.
  • Hem doğal dilde bir özet (text) hem de yapılandırılmış bir tablo (table) içeren blocks listesi. Metin blokları; kalın metin, başlıklar ve bağlantılar gibi Markdown biçimlendirmesi içerebilir.
  • Tesisin propertyQuota bilgileri.
{
  "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
    }
  }
}

2. örnek: Çok adımlı etkileşimli teşhis

Bağlamı koruyarak ek soru sormak için isteğinize önceki yanıt tarafından döndürülen sessionId değerini ekleyin.

Senaryo: Önceki dönemle karşılaştırma

Önceki cihaz karşılaştırmasının ardından, Danışman'dan sonuçları önceki dönemle karşılaştırmasını istersiniz.

HTTP İsteği

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."
  }'

HTTP Yanıtı

Ask Advisor, sonuçları önceki dönemle ilişkilendirmek için oturum belleğini kullanır.

{
  "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%"
              }
            ]
          }
      }
    }
  ]
}

Yanıt Yapısı ve Veri Blokları

ChatResponse nesnesi, blocks dizisindeki yapılandırılmış bileşenleri döndürür:

Engelleme Türü Alan Açıklama
Anlatı Metni blocks[].text Kullanıcılar tarafından okunabilir açıklama ve üst düzey analitik çıkarımlar.
Yapılandırılmış Tablo blocks[].table headers (adlar ve veri türleri) ve rows (hücre değerleri) içeren tablo şeklinde veri dökümü.

Tablo Başlığı Veri Türleri

blocks[].table.headers içindeki sütunlar, semantik veri türünü açıklar:

  • string: Kategorik metin değerleri (ör. "desktop", "/shop/apparel").
  • float: Sayısal kayan nokta sayıları.

Sohbet Kotası Yönetimi

Ask Advisor istekleri, sorgu karmaşıklığına göre sohbet jetonları tüketir. returnPropertyQuota, true olduğunda mevcut kota durumu propertyQuota içinde döndürülür:

  • tokensPerDay: Günlük jeton sınırı ve kalan bakiye.
  • tokensPerHour: Saatlik kayan zaman aralığı sıklık sınırlaması ve kalan bakiye.

Önerilen Entegrasyon Uygulamaları

properties.chat yöntemi, ekipler ve araçlar arasında çeşitli entegrasyon mimarilerinin kullanılmasını sağlar:

Kurumsal Sohbet ve Ortak Çalışma Botları

Ekip sohbeti çalışma alanınızı doğrudan Google Analytics'e bağlayın.

  • Mesaj dizili oturumlar: Ekip üyelerinin ortaklaşa ek sorular sormasına olanak tanımak için sessionId değerini sohbet mesaj dizisi kimliğine göre depolayın.
  • Zengin Kart Oluşturma: table yanıt bloklarını etkileşimli kart widget'larına dönüştürün.

Otonom Yapay Zeka Ajanları ve Model Bağlam Protokolü (MCP) Araçları

LLM düzenleyicileri (ör. Gemini, LangChain veya Claude) bir GA analiz aracıyla donatın:

  • LLM temsilcisi, LLM'yi karmaşık runReport sorguları oluşturmaya zorlamak yerine doğal dil amacı ile chat yöntemini çağırabilir.
  • Temsilci, çok kanallı pazarlama önerileri oluşturmak için yüksek doğruluk oranına sahip özetler ve yapılandırılmış tablolar alır.

Otomatik Yönetici Özetleri ve Uyarılar

Anormallikleri proaktif olarak inceleyen planlanmış hizmetler oluşturma:

  • Günlük bir cron işi şu sorguyu gönderir: "Dünkü temel performans metriklerini özetle ve dönüşümlerdeki anormal düşüşleri belirle."
  • Anormallik tespit edilirse komut dosyası, temel nedenleri teşhis etmek için otomatik olarak bir takip sorgusu tetikler ve dahili kontrol panellerine veya CRM sistemlerine bir özet gönderir.

Sonraki adımlar