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 Yük'ünü girin.

Measurement Protocol, HTTP isteği alındığında 2xx durum kodunu döndürür. Yük hatalı biçimlendirilmişse veya veriler yanlışsa ya da Google Analytics tarafından işlenmemişse Measurement Protocol 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.

JSON POST gövdesi

Anahtar Tür Açıklama

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, tesisin saat dilimine göre en fazla 3 takvim günü geriye dönük olarak girilebilir.

user_properties

 object İsteğe bağlı. Ölçüm için kullanıcı özellikleri.

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ının 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ış bir 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. Geçerli tüm etkinlikler için etkinlikler referansına bakın.

events[].name

 string Zorunludur. Etkinliğin adı. Tüm seçenekler için Etkinlikler bölümüne bakın.

events[].params

 object İsteğe bağlı. Etkinliğin parametreleri. Her etkinlik için önerilen parametreler ve Ortak etkinlik parametreleri hakkında bilgi edinmek için Etkinlikler başlıklı makaleyi inceleyin.

Ortak 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.

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). Etkinliğin zaman damgasını geçersiz kılmak için bu parametreyi kullanın.

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 öğelerini 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, client_id.

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

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, mülkün saat diliminde 3 iş gününden daha eski bir zaman damgasına sahip tüm 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ğrular.

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

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

Özel parametreler

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

  • Kullanıcı kapsamlı özel parametreler, user_properties içine dahil edilebilir.
  • Etkinlik kapsamlı özel parametreler events[].params'e dahil edilebilir.
  • Öğe kapsamlı özel parametreler, items içine 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
  • in_app_purchase
  • notification_dismiss
  • notification_foreground
  • notification_open
  • notification_receive
  • notification_send
  • os_update
  • session_start
  • user_engagement

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_