Measurement Protocol referansı

Bu sayfada, Measurement Protocol'ün aktarım mekanizması ve veri parametreleri açıklanmaktadır.

Taşıma

Tüm veriler, HTTPS POST istekleri kullanılarak güvenli bir şekilde gönderilmelidir.

Aşağıdaki uç noktaya istek gönderin:

https://www.google-analytics.com/mp/collect

Verilerinizin AB'de toplanmasını istiyorsanız bunun yerine aşağıdaki uç noktayı kullanın:

https://region1.google-analytics.com/mp/collect

Aşağıda örnek bir POST isteği verilmiştir:

POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json
PAYLOAD_DATA

PAYLOAD_DATA yerine isteğin Payload'unu girin.

Measurement Protocol, HTTP isteği alındığında 2xx durum kodunu döndürür. Measurement Protocol, yük hatalı biçimlendirilmişse veya veriler yanlışsa ya da Google Analytics tarafından işlenmemişse hata kodu döndürmez.

Yük

Yük iki bölümden oluşur:

  1. Sorgu parametreleri.
  2. JSON POST gövdesi.

Sorgu parametreleri

Parametre Adı Açıklama

api_secret

 Zorunludur. Google Analytics kullanıcı arayüzündeki API gizli anahtarı.

Yönetici > Veri Akışları > Akışınızı seçin > Measurement Protocol > Oluştur bölümünde bulunur.

Kuruluşunuza özeldir. Aşırı spam'den kaçınmak için düzenli olarak güncellenmelidir.

firebase_app_id

 Zorunludur. Firebase uygulama kimliği. Firebase uygulamasının tanımlayıcısı.

Firebase konsolunda Proje Ayarları > Genel > Uygulamalarınız > Uygulama Kimliği bölümünde bulunur.

JSON POST gövdesi

JSON POST gövdesinin boyutu 130 KB'tan az olmalıdır.

Anahtar Tür Açıklama

app_instance_id

 string Zorunludur. Firebase uygulamasının belirli bir yüklemesinin benzersiz tanımlayıcısı.

Web client_id ile aynı değildir.

Firebase SDK kullanılarak alınmalıdır:

user_id

 string

İsteğe bağlı. Kullanıcı için benzersiz tanımlayıcı. Bu tanımlayıcı hakkında daha fazla bilgi için Platformlar arası analiz için User-ID başlıklı makaleyi inceleyin. Yalnızca UTF-8 karakterleri içerebilir.

timestamp_micros

 number

İsteğe bağlı. Unix zaman damgası, milisaniye değil mikrosaniye. Etkinliğin saatini gösterir. Yalnızca geçmişte gerçekleşen etkinlikleri kaydetmek için ayarlanmalıdır. user_property veya etkinlik zaman damgalarıyla geçersiz kılınabilir. Etkinlikler 72 saate kadar geriye dönük olarak eklenebilir.

user_properties

 object İsteğe bağlı. Ölçümle ilgili kullanıcı özellikleri. İstek başına en fazla 25 kullanıcı özelliği gönderilebilir. Kullanıcı özelliği adları en fazla 24 karakterden, kullanıcı özelliği değerleri ise en fazla 36 karakterden oluşmalıdır.

user_data

 object İsteğe bağlı. Kullanıcı tarafından sağlanan veriler.
object İsteğe bağlı. İstekle ilgili izin ayarları. Daha fazla bilgi için izin bölümünü inceleyin.

non_personalized_ads

 boolean İsteğe bağlıdır. Kullanıcı verilerinin kişiselleştirilmiş reklamlar için kullanılmaması gerektiğini belirtmek üzere true olarak ayarlayın.

user_location

 object İsteğe bağlı. İstekteki coğrafi bilgileri yapılandırılmış biçimde ayarlar.

ip_override

 string İsteğe bağlı. Google Analytics'in istek için coğrafi bilgileri elde etmek üzere kullandığı IP adresi.

device

 object İsteğe bağlı. İstekteki cihaz bilgilerini yapılandırılmış bir biçimde ayarlar.

validation_behavior

 string

İsteğe bağlı. İstek için doğrulama davranışını ayarlar.

RELAXED veya ENFORCE_RECOMMENDATIONS. Belirtilmezse varsayılan olarak RELAXED olur.

events[]

 array Zorunludur. event öğe dizisi. İstek başına en fazla 25 etkinlik gönderilebilir. Önerilen etkinlikler için etkinlikler referansına bakın.

events[].name

 string Zorunludur. Etkinliğin adı. Etkinlik adları en fazla 40 karakterden oluşmalıdır. Önerilen etkinlikler için Etkinlikler başlıklı makaleyi inceleyin.

events[].params

 object İsteğe bağlı. Etkinliğin parametreleri. Etkinlik başına en fazla 25 parametre gönderilebilir. Her etkinlik için önerilen parametreleri ve Ortak etkinlik parametrelerini öğrenmek için Etkinlikler başlıklı makaleyi inceleyin.

Parametre adları en fazla 40 karakterden oluşmalıdır. 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.

Sık kullanılan etkinlik parametreleri

Measurement Protocol'de aşağıdaki ortak etkinlik parametreleri bulunur:

Anahtar Tür Açıklama

session_id

 number Kullanıcı oturumunu tanımlayan pozitif bir sayı. Birkaç yaygın kullanım alanı için gereklidir. ^\d+$ normal ifadesiyle eşleşmelidir.

Firebase SDK kullanılarak alınmalıdır:

engagement_time_msec

 number Etkinliğin kullanıcı etkileşimi süresi (milisaniye cinsinden). Önceki etkinlikten bu yana geçen kullanıcı etkileşimi süresini yansıtan bir değer kullanın.

timestamp_micros

 number Etkinliğin Unix epoch zaman damgası (mikrosaniye cinsinden). Bu parametreyi kullanarak etkinliğin zaman damgasını geçersiz kılabilirsiniz.

consent özelliği, izin türlerini ve durumlarını yapılandırır. consent belirtmezseniz Google Analytics, istemci veya uygulama örneği için ilgili online etkileşimlerdeki izin ayarlarını kullanır.

Anahtar Tür Açıklama

ad_user_data

 string

İsteğe bağlı. İstek etkinliklerinden ve kullanıcı özelliklerinden elde edilen kullanıcı verilerinin reklam amacıyla Google'a gönderilmesi için izin.

GRANTED veya DENIED

ad_personalization

 string

İsteğe bağlı. Kullanıcının kişiselleştirilmiş reklamcılık için verdiği izin.

GRANTED veya DENIED

Coğrafi bilgiler

user_location ve ip_override özellikleri coğrafi bilgiler sağlar. user_location, ip_override politikasına göre daha önceliklidir.

user_location alanının yapısı aşağıda verilmiştir. Mümkün olduğunca çok sayıda özellik sağlayın. En az country_id ve region_id değerlerini kullanmanızı öneririz.

Anahtar Tür Açıklama

city

 string İsteğe bağlı. Şehrin adı. Şehir ABD'de bulunuyorsa Google Analytics'in şehir adını şehir kimliği ile doğru şekilde eşleyebilmesi için country_id ve region_id değerlerini de ayarlayın.

region_id

 string İsteğe bağlı. ISO 3166 ülke ve alt bölümü. Örneğin, US-CA, US-AR, CA-BC, GB-LND, CN-HK.

country_id

 string İsteğe bağlı. ISO 3166-1 alfa-2 biçimindeki ülke. Örneğin, US, AU, ES, FR.

subcontinent_id

 string İsteğe bağlı. UN M49 biçimindeki alt kıta. Örneğin, 011, 021, 030, 039.

continent_id

 string İsteğe bağlı. UN M49 biçimindeki kıta. Örneğin, 002, 019, 142, 150.

Aşağıda örnek bir user_location verilmiştir:

"user_location": {
  "city": "Mountain View",
  "region_id": "US-CA",
  "country_id": "US",
  "subcontinent_id": "021",
  "continent_id": "019"
}

ip_override, user_location'ye alternatif bir seçenektir. Bunun yerine ip_override gönderirseniz Google Analytics, coğrafi bilgileri IP adresinden türetir. user_location gönderirseniz Google Analytics, ip_override değerini yoksayar.

user_location veya ip_override göndermezseniz Google Analytics, app_instance_id kullanarak etkinlikleri etiketleyerek coğrafi bilgileri türetir.

Google Analytics, gönderilen coğrafi bilgilerden bağımsız olarak isteğe mülkün ayrıntılı konum verileri ayarlarını uygular.

Cihaz bilgileri

Cihaz bilgilerini göndermek için device alanını kullanın. device alanının yapısı aşağıda verilmiştir. Mümkün olduğunca çok sayıda özellik sağlayın. En az category öneririz.

Anahtar Tür Açıklama

category

 string İsteğe bağlıdır. Cihazın kategorisi. Örneğin, desktop, tablet, mobile, smart TV.

language

 string İsteğe bağlıdır. ISO 639-1 biçimindeki dil. Örneğin, en, en-US.

screen_resolution

 string İsteğe bağlıdır. Cihazın çözünürlüğü, WIDTHxHEIGHT biçiminde. Örneğin, 1280x2856, 1080x2340.

operating_system

 string İsteğe bağlıdır. İşletim sistemi veya platform. Örneğin, MacOS.

operating_system_version

 string İsteğe bağlıdır. İşletim sisteminin veya platformun sürümü. Örneğin, 13.5.

model

 string İsteğe bağlıdır. Cihazın modeli. Örneğin, Pixel 9 Pro, Samsung Galaxy S24.

brand

 string İsteğe bağlıdır. Cihazın markası. Örneğin, Google, Samsung.

browser

 string İsteğe bağlıdır. Tarayıcının markası veya türü. Örneğin, Chrome, Firefox.

browser_version

 string İsteğe bağlıdır. Tarayıcının sürümü. Örneğin, 136.0.7103.60, 5.0.

Aşağıdaki snippet'te device ayarlarıyla ilgili bir örnek gösterilmektedir:

"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"
}
Bir istekte device belirtilmezse Google Analytics, app_instance_id kullanılarak etiketlenen etkinliklerden cihaz bilgilerini türetir.

device, belirtip belirtmediğinizden bağımsız olarak Google Analytics, mülkün ayrıntılı cihaz verileri ayarlarını isteğe uygular.

Doğrulama davranışı

validation_behavior özelliği, Measurement Protocol'ün isteğin içeriğini nasıl doğruladığını kontrol eder.

  • RELAXED doğrulama yalnızca hatalı biçimlendirilmiş istekleri reddeder. Geçersiz alan adlarına sahip veya doğru türde olmayan veriler içeren etkinlikleri ve parametreleri kabul etmeye devam edebilir ancak sınırları aşan parametreleri yoksayar. Measurement Protocol varsayılan olarak RELAXED doğrulamayı kullanır.
  • ENFORCE_RECOMMENDATIONS doğrulama, doğru türde olmayan veya sınırları aşan parametreler içeren etkinlik ve öğe parametrelerini reddeder. Ayrıca ENFORCE_RECOMMENDATIONS, son 72 saat içinde olmayan bir zaman damgasına sahip etkinlikleri veya kullanıcı özelliklerini reddeder.

Aşağıdaki yaklaşımı öneririz:

  • İsteklerinizle ilgili olası sorunlar hakkında mümkün olduğunca fazla geri bildirim almak için etkinlikleri doğrularken ENFORCE_RECOMMENDATIONS seçeneğini kullanın.

    İstekleri doğrulamak için Etkinlik Oluşturucu'yu da kullanabilirsiniz. ENFORCE_RECOMMENDATIONS, istekleri doğrularken belirtilir.

  • Measurement Protocol tarafından reddedilen verileri en aza indirmek için etkinlik gönderirken validation_behavior belirtmeyin.

    Belirli bir istek gönderirken veri toplamadan ziyade katı doğrulamaya öncelik vermek istiyorsanız validation_behavior alanını ekleyin ve ENFORCE_RECOMMENDATIONS olarak ayarlayın.

Özel parametreler

Measurement Protocol yüküne özel kullanıcı kapsamlı, etkinlik kapsamlı ve öğe kapsamlı parametreler ekleyebilirsiniz.

  • Kullanıcı kapsamlı özel parametreler, user_properties'ye dahil edilebilir.
  • Etkinlik kapsamlı özel parametreler, events[].params içine dahil edilebilir.
  • Öğe kapsamlı özel parametreler, items'e dahil edilebilir.

Bazı etkinlikler için önerilen parametreler vardır. Desteklenen tüm etkinlikler için önerilen parametreleri etkinlikler bölümünde bulabilirsiniz.

Ayrılmış adlar

Bazı etkinlik, parametre ve kullanıcı özelliği adları ayrılmıştır ve kullanılamaz:

Ayrılmış etkinlik adları

Aşağıdaki etkinlik adları ayrılmıştır ve kullanılamaz:

  • ad_activeview
  • ad_click
  • ad_exposure
  • ad_query
  • ad_reward
  • adunit_exposure
  • app_clear_data
  • app_exception
  • app_install
  • app_remove
  • app_store_refund
  • app_update
  • app_upgrade
  • dynamic_link_app_open
  • dynamic_link_app_update
  • dynamic_link_first_open
  • error
  • firebase_campaign
  • firebase_in_app_message_action
  • firebase_in_app_message_dismiss
  • firebase_in_app_message_impression
  • first_open
  • first_visit
  • notification_dismiss
  • notification_foreground
  • notification_open
  • notification_receive
  • notification_send
  • os_update
  • session_start
  • user_engagement

Ayrıca ad_impression, in_app_purchase ve screen_view etkinliklerine yalnızca uygulama veri akışlarında izin verilir.

Ayrılmış parametre adları

Aşağıdaki parametre adları ayrılmıştır ve kullanılamaz:

  • firebase_conversion

Parametre adları şunlarla başlayamaz:

  • _ (underscore)
  • firebase_
  • ga_
  • google_
  • gtag.

Ayrılmış kullanıcı özelliği adları

Aşağıdaki kullanıcı özelliği adları ayrılmıştır ve kullanılamaz:

  • first_open_time
  • first_visit_time
  • last_deep_link_referrer
  • user_id
  • first_open_after_install

Ayrıca, kullanıcı özelliği adları şununla başlayamaz:

  • _ (underscore)
  • firebase_
  • ga_
  • google_