Measurement Protocol referansı

Bu sayfada, Measurement Protocol'ün taşıma mekanizması ve veri parametreleri açıklanmaktadır.

Ulaşım

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

Örnek bir POST isteği:

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

PAYLOAD_DATA ifadesini isteğin yükü ile değiştirin.

HTTP isteği alınırsa Measurement Protocol, 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 bir 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 özel. Aşırı spam'i önlemek için düzenli olarak güncellenmelidir.

firebase_app_id

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

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 küçük olmalıdır.

Anahtar Tür Açıklama

app_instance_id

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

Web client_id ile aynı değildir.

Firebase SDK'sı 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 cinsinden. Etkinliğin zamanını temsil eder. Yalnızca geçmişte gerçekleşen etkinlikleri kaydetmek için ayarlanmalıdır. user_property veya etkinlik zaman damgaları tarafından geçersiz kılınabilir. Etkinlikler 72 saate kadar geriye dönük olarak tarihlendirilebilir.

user_properties

 object İsteğe bağlı. Ölçüm için 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ı. İstek için izin ayarları. Daha fazla bilgi için izin bölümüne bakın.

non_personalized_ads

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

user_location

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

ip_override

 string İsteğe bağlı. Google Analytics'in istek için coğrafi bilgileri türetmek amacıyla kullandığı IP adresi.

device

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

validation_behavior

 string

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

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

events[]

 array Zorunludur. event öğe içeren bir dizi. İ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 karakter olmalıdır. Önerilen etkinlikler için Etkinlikler bölümüne bakın.

events[].params

 object İsteğe bağlı. Etkinliğin parametreleri. Etkinlik başına en fazla 25 parametre gönderilebilir. Her etkinlik için önerilen parametreler ve Ortak etkinlik parametreleri için Etkinlikler bölümüne bakın.

Parametre adları en fazla 40 karakter olmalıdır. Parametre değerleri, standart bir Google Analytics mülkü için en fazla 100 karakter, Google Analytics 360 mülkü için en fazla 500 karakterden oluşabilir.

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.

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

engagement_time_msec

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

timestamp_micros

 number Etkinlik için mikrosaniye cinsinden Unix epoch zaman damgası. 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 parametresini 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ı. İsteğin 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ı için kişiselleştirilmiş reklamcılık izni.

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ı şu şekildedir. Mümkün olduğunca çok sayıda özellik sağlayın. En az country_id ve region_id kullanmanızı öneririz.

Anahtar Tür Açıklama

city

 string İsteğe bağlı. Şehrin adı. Şehir ABD'deyse Google Analytics'in şehir adını bir ş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çiminde ülke. Örneğin, US, AU, ES, FR.

subcontinent_id

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

continent_id

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

Örnek bir user_location:

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

ip_override, user_location için bir alternatiftir. Bunun yerine ip_override gönderirseniz Google Analytics, coğrafi bilgileri IP adresinden alır. user_location gönderirseniz Google Analytics ip_override değerini yoksayar.

user_location veya ip_override göndermezseniz Google Analytics, app_instance_id kullanarak etiketleme etkinliklerinden coğrafi bilgileri alır.

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

Cihaz bilgileri

Cihaz bilgilerini göndermek için device alanını kullanın. device alanının yapısı şu şekildedir: Mümkün olduğunca çok sayıda özellik ekleyin. En az category kullanmanızı öneririz.

Anahtar Tür Açıklama

category

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

language

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

screen_resolution

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

operating_system

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

operating_system_version

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

model

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

brand

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

browser

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

browser_version

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

Aşağıdaki snippet'te device ayarlarının bir örneği 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"
}
İstekte device belirtilmezse Google Analytics, cihaz bilgilerini app_instance_id kullanarak etiketleme etkinliklerinden alır.

device, belirtmenizden 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 istek içeriklerini nasıl doğrulayacağını kontrol eder.

  • RELAXED doğrulaması yalnızca hatalı biçimlendirilmiş istekleri reddeder. Geçersiz alan adlarına veya doğru türde olmayan verilere sahip 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ğrulaması, 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 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 kullanın.

    İstekleri doğrularken ENFORCE_RECOMMENDATIONS değerini belirttiği için Etkinlik Oluşturucu'yu kullanarak da istekleri doğrulayabilirsiniz.

  • Measurement Protocol tarafından reddedilen verileri en aza indirmek için etkinlik gönderirken validation_behavior değerini 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

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 içine dahil edilebilir.
  • Öğe kapsamlı özel parametreler, items'e dahil edilebilir.

Bazı etkinliklerin önerilen parametreleri vardır. Desteklenen tüm etkinlikler için önerilen parametreleri görmek üzere etkinlikler bölümüne bakın.

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ı için 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_