Measurement Protocol etkinliklerini Google Analytics'e gönderme

Bu kılavuzda, Google Analytics Measurement Protocol web ve uygulama veri akışı etkinliklerini bir Google Analytics sunucusuna nasıl gönderebileceğiniz açıklanmaktadır. Böylece Measurement Protocol etkinliklerini Google Analytics raporlarınızda görüntüleyebilirsiniz.

Measurement Protocol istekleri için gereken tanımlayıcılar ve parametreler, etkinlikleri bir web akışına mı yoksa uygulama veri akışına mı gönderdiğinize bağlıdır.

  • Web akışları (genellikle gtag.js veya Google Etiket Yöneticisi ile donatılır) için istek URL'sinde measurement_id ve JSON gövdesinde client_id kullanarak kullanıcı örneğini tanımlarsınız. client_id, web sitenizdeki Google Analytics etiketi tarafından oluşturulan kimlikle eşleşmelidir.
  • Uygulama akışları (Firebase SDK'sı ile donatılmış) için istek URL'sinde firebase_app_id ve JSON gövdesinde app_instance_id kullanırsınız. Bunlar, Firebase için Google Analytics SDK'sı tarafından sağlanır.

Bu kılavuzda her iki senaryo için de örnekler verilmiştir.

Akış türüne göre önemli istek bileşenleri

Bileşen Web akışı (gtag.js/GTM) Uygulama veri akışı (Firebase)
Veri akışı URL parametresi measurement_id firebase_app_id
API gizli anahtarı URL parametresi Zorunlu Zorunlu
Cihaz kimliği JSON gövde alanı client_id app_instance_id

Bu kılavuzda görmek istediğiniz platformu seçin:

Bu sekmede, Firebase için Google Analytics SDK'sını kullanarak bir uygulama veri akışındaki kullanıcı etkinliğiyle ilişkili etkinlikleri sunucunuzdan gönderme talimatları gösterilir. Bu isteklerde firebase_app_id ve app_instance_id kullanıldığını unutmayın.

Ön koşullar

Measurement Protocol'ü kullanarak etkinlik göndermek için Google Analytics mülkünüzden veya Firebase projenizden belirli tanımlayıcılar almanız gerekir.

API gizli anahtarı

api_secret, isteklerinizin kimliğini doğrulamak için kullanılır. Bu gizli anahtarın gizli tutulması çok önemlidir.

Yeni bir gizli anahtar oluşturmak için:

  1. Google Analytics'e gidip hesabınıza ve mülkünüze gidin.
  2. Sol altta Yönetici'yi tıklayın.
  3. Veri toplama ve değiştirme bölümünde Veri akışları'nı tıklayın.
  4. Web veya uygulama veri akışınızı seçin.
  5. Measurement Protocol API gizli anahtarları'nı tıklayın.
  6. Oluştur'u tıklayın.
  7. Gizli anahtar için bir takma ad girin ve Oluştur'u tıklayın.

  8. Gizli anahtar değerini kopyalayın.

Firebase uygulama kimliği

firebase_app_id, Firebase uygulamanızı tanımlar. app_instance_id ile aynı değildir.

Firebase Uygulama Kimliğinizi bulmak için:

  1. Projenizi Firebase konsolunda açın.
  2. Project Overview'ın (Projeye Genel Bakış) yanındaki ayarlar dişli simgesini tıklayın ve Project settings'i (Proje ayarları) seçin.
  3. Genel sekmesinde Uygulamalarınız bölümüne gidin.
  4. Belirli bir iOS veya Android uygulamasını seçin.
  5. Uygulama kimliği değerini kopyalayın.

İsteği biçimlendirme

Google Analytics Measurement Protocol yalnızca HTTP POST isteklerini destekler.

Etkinlik göndermek için aşağıdaki biçimi kullanın:

POST /mp/collect?firebase_app_id=<var>FIREBASE_APP_ID</var>&api_secret=<var>API_SECRET</var> HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json

PAYLOAD_DATA

İstek URL'si sorgu parametrelerinde şunları sağlamanız gerekir (bu değerleri bulma veya oluşturma hakkında ayrıntılı bilgi için Ön koşullar bölümüne bakın):

  • api_secret: İsteğin kimliğini doğrulamak için kullanılan API gizli anahtarı.
  • firebase_app_id: Uygulamanızın Firebase uygulama kimliği.

Measurement Protocol için JSON POST gövdesi biçiminde bir istek gövdesi sağlamanız gerekir. Aşağıda bununla ilgili bir örnek verilmiştir:

  {
   "app_instance_id": "APP_INSTANCE_ID",
   "events": [
      {
        "name": "login",
        "params": {
          "method": "Google",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      }
   ]
  }

Mobil uygulamanızın benzersiz bir yüklemesini tanımlamak için istek içeriğinde app_instance_id sağlamanız gerekir. Bunun, uygulamanın kendisini tanımlayan firebase_app_id değerinden farklı olduğunu unutmayın. app_instance_id ve Firebase SDK'sını kullanarak bu kimliği nasıl alacağınız hakkında daha fazla bilgi için app_instance_id referans dokümanlarını inceleyin.

session_start ayrılmış bir etkinlik adı olduğunda, yeni bir session_id oluşturulması durumunda session_start parametresinin gönderilmesine gerek kalmadan yeni oturum oluşturulur. Oturumların nasıl sayıldığını öğrenin.

Dene

Aynı anda birden fazla etkinlik göndermek için kullanabileceğiniz bir örnek aşağıda verilmiştir. Bu örnek, Google Analytics sunucunuza bir tutorial_begin etkinliği ve bir join_group etkinliği gönderir, user_location alanını kullanarak coğrafi bilgileri ve device alanını kullanarak cihaz bilgilerini içerir.

const firebaseAppId = "FIREBASE_APP_ID";
const apiSecret = "API_SECRET";

fetch(`https://www.google-analytics.com/mp/collect?firebase_app_id=${firebaseAppId}&api_secret=${apiSecret}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    app_instance_id: "APP_INSTANCE_ID",
    events: [
      {
        name: "tutorial_begin",
        params: {
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      },
      {
        name: "join_group",
        params: {
          "group_id": "G_12345",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 150
        }
      }
    ],
    user_location: {
      city: "Mountain View",
      region_id: "US-CA",
      country_id: "US",
      subcontinent_id: "021",
      continent_id: "019"
    },
    device: {
      category: "mobile",
      language: "en",
      screen_resolution: "1280x2856",
      operating_system: "Android",
      operating_system_version: "14",
      model: "Pixel 9 Pro",
      brand: "Google",
      browser: "Chrome",
      browser_version: "136.0.7103.60"
    }
  })
});

firebase_app_id biçimi platforma özeldir. Firebase yapılandırma dosyaları ve nesneleri bölümünde Uygulama kimliği'ne bakın.

Zaman damgasını geçersiz kılma

Measurement Protocol, istekteki her etkinlik ve kullanıcı özelliği için aşağıdaki listede bulduğu ilk zaman damgasını kullanır:

  1. Etkinliğin veya kullanıcı özelliğinin timestamp_micros.
  2. İsteğin timestamp_micros.
  3. Measurement Protocol'un isteği aldığı zaman.

Aşağıdaki örnekte, istekteki tüm etkinlikler ve kullanıcı özellikleri için geçerli olan istek düzeyinde bir zaman damgası gönderilmektedir. Sonuç olarak Measurement Protocol, tutorial_begin ve join_group etkinliklerine ve customer_tier kullanıcı özelliğine requestUnixEpochTimeInMicros zaman damgasını atar.

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin"
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM"
    }
  }
}

Aşağıdaki örnekte istek düzeyinde bir zaman damgası, etkinlik düzeyinde bir zaman damgası ve kullanıcı özelliği düzeyinde bir zaman damgası gönderilmektedir. Sonuç olarak Measurement Protocol aşağıdaki zaman damgalarını atar:

  • tutorial_begin etkinliği için tutorialBeginUnixEpochTimeInMicros
  • customer_tier kullanıcı özelliği için customerTierUnixEpochTimeInMicros
  • requestUnixEpochTimeInMicros için join_group etkinliği ve newsletter_reader kullanıcı özelliği.
{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin",
      "timestamp_micros": tutorialBeginUnixEpochTimeInMicros
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM",
      "timestamp_micros": customerTierUnixEpochTimeInMicros
    },
    "newsletter_reader": {
      "value": "true"
    }
  }
}

Geçmiş etkinlikler ve kullanıcı özellikleri için doğrulama davranışı

Etkinlikler ve kullanıcı özellikleri 72 saate kadar geriye dönük olarak tarihlendirilebilir. timestamp_micros değeri 72 saatten daha eskiyse Measurement Protocol, etkinlik veya kullanıcı özelliğini aşağıdaki şekilde kabul ya da reddeder:

  • validation_behavior ayarlanmazsa veya RELAXED olarak ayarlanırsa Measurement Protocol, etkinliği veya kullanıcı özelliğini kabul eder ancak zaman damgasını 72 saat öncesi olarak değiştirir.
  • validation_behavior, ENFORCE_RECOMMENDATIONS olarak ayarlanırsa Measurement Protocol, etkinliği veya kullanıcı özelliğini reddeder.

Measurement Protocol kullanılarak gönderilen ve Firebase için Google Analytics SDK'sı veya gtag.js tarafından toplanan etkinliklerle birleştirilmesi ya da işlenmesi amaçlanan etkinlikler, orijinal istemci tarafı etkinlik zaman damgasından sonraki 48 saat içinde Google Analytics tarafından alınmalıdır. Bu süreden sonra alınan etkinlikler, özellikle dönüşüm ilişkilendirme gibi amaçlar için beklendiği gibi işlenmeyebilir.

Sınırlamalar

Measurement Protocol etkinliklerini Google Analytics'e gönderme konusunda aşağıdaki sınırlamalar geçerlidir:

  • Her mülk için saatte en fazla 100 milyon dönüşüm dışı istek gönderebilirsiniz. İstekteki etkinliklerin hiçbiri Google Ads'de dönüşüm olan önemli bir etkinlik değilse bu istek, dönüşüm olmayan bir istektir. Bu sınırı aşarsanız Measurement Protocol, mülk için dönüşüm dışındaki tüm istekleri saatin geri kalanında sessizce yoksayar.

  • İstekler en fazla 25 etkinlik içerebilir.

  • Etkinlikler en fazla 25 parametreye sahip olabilir.

  • Etkinlikler en fazla 25 kullanıcı özelliğine sahip olabilir.

  • Kullanıcı özelliği adları en fazla 24 karakterden oluşmalıdır.

  • Kullanıcı özelliği değerleri en fazla 36 karakterden oluşmalıdır.

  • Etkinlik adı en fazla 40 karakterden oluşmalıdır. Yalnızca alfanümerik karakterler ve alt çizgiler içerebilir ve alfabetik karakterle başlaması gerekir.

  • Öğe parametreleri dahil olmak üzere parametre adları en fazla 40 karakterden oluşabilir. Yalnızca alfanümerik karakterler ve alt çizgiler içerebilir ve alfabetik karakterle başlaması gerekir.

  • Öğe parametresi değerleri de dahil olmak üzere parametre değerleri, standart bir Google Analytics mülkü için en fazla 100 karakter, Google Analytics 360 mülkü için ise en fazla 500 karakterden oluşabilir.

    Bu sınır, değerleri Google Etiket Yöneticisi'ndeki ilgili Analytics oturum kimliği ve Analytics oturum numarası yerleşik değişkenleri tarafından sağlandığında session_id ve session_number parametreleri için geçerli değildir.

  • Öğe parametreleri en fazla 10 özel parametreye sahip olabilir.

  • Yayın gövdesi 130 kB'tan küçük olmalıdır.

  • Google Analytics'e gönderilen uygulama Measurement Protocol etkinlikleri, Google Ads'de uygulama kullanıcıları için arama ağı kitlelerini doldurmaz.

  • Bazı etkinlik, parametre ve kullanıcı özelliği adları ayrılmıştır ve kullanılamaz. Ayrıntılar için Ayrılmış adlar bölümüne bakın.

Ayrılmış adlar

Measurement Protocol'de etkinlikler, parametreler veya kullanıcı özellikleri için kullanılamayan birkaç ayrılmış ad vardır.

Aşağıdaki etkinlik adları, kafa karışıklığına neden olan yaygın noktalardır:

Her kullanım alanının ek şartları için yaygın kullanım alanları bölümüne bakın.