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 web akışına mı yoksa uygulama veri akışına mı gönderdiğinize bağlıdır.

• Web akışları için (genellikle gtag.js veya Google Etiket Yöneticisi ile izlenir) kullanıcı örneğini tanımlamak üzere istek URL'sinde measurement_id, JSON gövdesinde ise client_id kullanırsınız. client_id web sitenizdeki Google Analytics etiketi tarafından oluşturulan kimlikle eşleşmelidir.
• Uygulama akışları (Firebase SDK ile izlenen) için istek URL'sinde firebase_app_id, JSON gövdesinde ise app_instance_id kullanırsınız. Bu değerler, Firebase için Google Analytics SDK'sı tarafından sağlanır.

Bu kılavuzda her iki senaryo için de örnekler verilmektedir.

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 rehberde görmek istediğiniz platformu seçin:

Firebase gtag.js

Bu sekmede, Firebase için Google Analytics SDK'sını kullanarak sunucunuzdan uygulama akışındaki kullanıcı etkinliğiyle ilişkili etkinlikleri gönderme talimatları gösterilir. Bu isteklerin firebase_app_id ve app_instance_id kullandığı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ı gizli tutmanız ç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 alttaki 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.

   Önemli: api_secret gizlidir. Web sitenizin veya uygulamanızın istemci tarafı kodunda bu kodu kullanmayın.

   • Güvenlik riski: api_secret'ın açığa çıkarılması, yetkisiz tarafların Google Analytics mülkünüze rastgele veya spam veriler göndermesine olanak tanır. Bu durum, raporlamanızın bozulmasına neden olabilir.
   • Doğru kullanım: Measurement Protocol, öncelikle sunucu tarafı veya güvenilir ortamlar (ör. çevrimdışı sistemler ya da sunucudan sunucuya iletişim) için tasarlanmıştır.
   • İstemci tarafı izleme: Etkinlikleri doğrudan bir web tarayıcısından göndermeniz gerekiyorsa Google etiketini (gtag.js) veya Google Etiket Yöneticisi'ni kullanın.
   • Chrome uzantıları: Manifest V3 Chrome uzantıları için gtag.js gibi uzaktan kod yükleyemezsiniz. Bu durumda, Measurement Protocol kullanılması önerilir. Chrome uzantılarında Google Analytics'i kullanma başlıklı makaleyi inceleyin.

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. Proje Genel Bakışı'nın yanındaki ayarlar dişli simgesini tıklayın ve Proje ayarları'nı 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.

Bir 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

İpucu: Verilerinizin AB'de toplanmasını istiyorsanız örnekteki HOST simgesini region1.google-analytics.com olarak değiştirin.

İstek URL'si sorgu parametrelerinde aşağıdakileri 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 gövdesinde 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 hakkında daha fazla bilgi edinmek ve Firebase SDK'sını kullanarak nasıl alacağınızı öğrenmek için app_instance_id referans belgelerine bakın.

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

Not: Aşağıdaki örneklerde fetch API'si kullanılmaktadır ve sunucu tarafında veya güvenilir ortamlarda (örneğin, Node.js ya da bir arka uç sunucusu) kullanılmak üzere tasarlanmıştır. Bu anahtarlar, istemci tarafı (tarayıcı) kodunda kullanılmamalıdır. Aksi takdirde api_secret açığa çıkar.

Aynı anda birden fazla etkinlik göndermek için kullanabileceğiniz bir örneği burada bulabilirsiniz. Bu örnekte, Google Analytics sunucunuza bir tutorial_begin etkinliği ve bir join_group etkinliği gönderilir, user_location alanı kullanılarak coğrafi bilgiler eklenir ve device alanı kullanılarak cihaz bilgileri eklenir.

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ündeki 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'ün isteği aldığı zaman.

Aşağıdaki örnek, istekteki tüm etkinlikler ve kullanıcı özellikleri için geçerli olan bir istek düzeyinde zaman damgası gönderir. Sonuç olarak Measurement Protocol, requestUnixEpochTimeInMicros zaman damgasını tutorial_begin ve join_group etkinliklerine ve customer_tier kullanıcı özelliğine 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önderilir. Sonuç olarak, Measurement Protocol aşağıdaki zaman damgalarını atar:

• tutorial_begin etkinliği için tutorialBeginUnixEpochTimeInMicros
• customerTierUnixEpochTimeInMicros kullanıcı özelliği için customer_tier
• requestUnixEpochTimeInMicros etkinliği ve newsletter_reader kullanıcı özelliği için.join_group

{
  "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 öncesine aitse Measurement Protocol, etkinliği veya kullanıcı özelliğini aşağıdaki şekilde kabul eder ya da reddeder:

• validation_behavior ayarlanmamışsa veya RELAXED olarak ayarlanmışsa Measurement Protocol, etkinliği veya kullanıcı özelliğini kabul eder ancak zaman damgasını 72 saat öncesiyle geçersiz kılar.
• 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 birlikte 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. Bundan sonra alınan etkinlikler, özellikle dönüşüm ilişkilendirmesi gibi amaçlar için beklendiği gibi işlenmeyebilir.

Sınırlamalar

Measurement Protocol etkinliklerinin Google Analytics'e gönderilmesiyle ilgili aşağıdaki sınırlamalar geçerlidir:

Not: 360 özelliklerinin sınırlamaları hakkında bilgi edinmek için Google Analytics 360 başlıklı makaleyi inceleyin.

• İ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 bir karakterle başlaması gerekir.

• Öğe parametresi değerleri 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 karakter olmalıdır.

  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ğlanan session_id ve session_number parametreleri için geçerli değildir.

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

• Gönderi gövdesi 130 KB'tan küçük olmalıdır.

• Google Analytics'e gönderilen uygulama Measurement Protocol etkinlikleri, Google Ads'deki uygulama kullanıcıları için arama 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 başlıklı makaleyi inceleyin.

Ayrılmış adlar

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

Aşağıdaki etkinlik adları sıkça karıştırılır:

• screen_view: Bu etkinliğe yalnızca uygulama yayınlarında izin verilir. Web yayınları için bunun yerine page_view kullanın.
• ad_impression: Bu etkinliğe yalnızca uygulama yayınlarında izin verilir.
• in_app_purchase: Bu etkinliğe yalnızca uygulama yayınlarında izin verilir. Web yayınları için bunun yerine purchase etkinliğini kullanın.

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