Google etiketi API referansı

Google etiketi (gtag.js) API'si, aşağıdaki söz dizimine sahip tek bir işlevden (gtag()) oluşur:

gtag(<command>, <command parameters>);
  • <command>, aşağıdaki komutlardan biridir:
  • <command parameters>, gtag() parametresine iletebileceğiniz parametrelerdir. Komut parametreleri komuta göre değişir. Komut referansına bakın.

Komutlarınız Google etiketi snippet'inin altında göründüğü sürece gtag() komutlarını sayfanızın herhangi bir yerinde çağırabilirsiniz. Snippet'i bir sayfaya nasıl ekleyeceğinizi öğrenmek için kurulum kılavuzuna bakın.

Parametre kapsamı

Parametre değerlerini tek tek etkinlikler, belirli bir <TARGET_ID> öğesine gönderilen tüm etkinlikler veya genel olarak tüm etkinlikler için kapsamlandırabilirsiniz. Bu işlem, event, config ve set komutları kullanılarak gerçekleştirilir.

Bir kapsamda ayarlanan parametre değerleri, farklı bir kapsamda aynı parametre için ayarlanan değerleri değiştirmez. Aşağıdaki örnekte, config komutu, daha önce set komutuyla atanmış olan campaign_id için global değeri değiştirmez. Her iki komut da yürütüldükten sonra campaign_id değişkeninin global değeri hâlâ '1234' olur.

// Set global campaign ID
gtag('set', { 'campaign_id': '1234' });

// Set campaign ID for <TARGET_ID>
gtag('config','<TARGET_ID>', { 'campaign_id': 'ABCD' });

Parametre önceliği

Farklı kapsamlarda aynı parametreye farklı değerler atanırsa etkinlikler işlenirken yalnızca tek bir değer kullanılır. event kapsamındaki parametre değerleri, config kapsamındaki parametrelere göre önceliklidir. config parametreleri ise set kullanılarak genel kapsamlı hale getirilen parametrelere göre önceliklidir.

// Set campaign information at the global scope
gtag('set', { 'campaign_name': 'Black Friday Sale' });

// Set currency for <TARGET_ID1> to 'USD'
gtag('config','<TARGET_ID1>', { 'currency': 'USD' });

// Process a conversion event with currency: 'GBP'
gtag('event','conversion', { 'currency': 'GBP', 'send_to': '<TARGET_ID1>' });

// Process a conversion event with currency: 'EUR'
gtag('event','conversion');

// Process a conversion event with currency: 'USD'
gtag('event','conversion', { 'send_to': '<TARGET_ID1>' });

config

Hedeflere ek yapılandırma bilgileri eklemenize olanak tanır. Bu, genellikle bir ürüne özel yapılandırmadır ancak hem Google Ads hem de Google Analytics kullanıyorsanız bunu yalnızca bir kez yapılandırmanız gerekir.

gtag('config', '<TARGET_ID>', {<additional_config_info>});

<TARGET_ID> ile ilgili önemli noktalar:

  • gtag('config', <TARGET_ID>, ...) komutundaki <TARGET_ID>, gtag.js'nin etkinlik verilerini nereye göndermesi gerektiğini tanımlayan bir etiket kimliğidir. Bu, Google Analytics mülkü, Google Ads hesabı, Floodlight yapılandırması veya birden fazla hedefi olan bir Google etiketi gibi bir hedef olabilir.

  • Etiket kimliği (ör. GT-XXXXXX, G-XXXXXX veya AW-YYYYYY), Google etiketinizin tanımlayıcısıdır. Google etiketini yüklemek için bu kimliği web sitenizin koduna eklersiniz.

  • Tek bir Google etiketi (etiket kimliğiyle tanımlanır), birden fazla hedefe veri gönderecek şekilde yapılandırılabilir. Bazı etiket kimlikleri, hedef kimlikleriyle aynı görünebilir (ör. Google Analytics mülkü için G-XXXXXX veya Google Ads hesabı için AW-YYYYYY). Ancak config komutundaki <TARGET_ID>, sayfaya yüklenen Google etiketinin belirli bir örneğini ifade eder.

  • gtag('config', ...) komutu, belirli bir <TARGET_ID> ile ilişkili Google etiketinin davranışını yapılandırır. Komut dosyasında src yer alan etiket kimliği genellikle Google etiketini yükler. Ancak gtag('config') komutunda hesabınızla ilişkili herhangi bir geçerli etiket kimliğini kullanabilirsiniz.

  • Tek bir Google etiketi, genellikle etiket birleştirme nedeniyle birden fazla etiket kimliğiyle ilişkilendirilebilir. Google etiketini yüklemek için komut dosyası src parametresinde bu ilişkili kimliklerden herhangi biri kullanılabilir.

  • Birden fazla hedefe veri gönderiyorsanız veya birden fazla etiket kullanıyorsanız komut dosyasına src yalnızca bir etiket kimliği içeren tek bir Google etiketi snippet'i eklemeniz yeterlidir. Ardından, her ek etiket kimliği veya hedef için bir gtag('config') komutu eklersiniz.

<additional_config_info>, bir veya daha fazla parametre-değer çiftidir.

Bu örnekte, bir etiketin Google Ads hesabına veri gönderecek şekilde yapılandırılması gösterilmektedir:

gtag('config', 'TAG_ID');

"TAG_ID", Google etiketinin etiket kimliğidir.

Ek yapılandırma bilgilerinin nasıl gönderileceğini göstermek için, bir etiketi false değerini ileten bir send_page_view parametresi ve 'agency' değerini ileten bir groups parametresiyle Analytics hesabına veri gönderecek şekilde yapılandıran bir örnek aşağıda verilmiştir.

gtag('config', 'TAG_ID', {
  'send_page_view': false,
  'groups': 'agency'
});

get

set komutuyla ayarlanan değerler dahil olmak üzere, gtag.js'ten çeşitli değerleri almanızı sağlar.

gtag('get', '<target>', '<field_name>', callback)
Bağımsız Değişken Tür Örnek Açıklama
<target> string G-XXXXXXXXXX

Değerlerin getirileceği hedef.
<field_name> FieldName client_id Alınacak alanın adı.
callback Function (field) => console.log(field)

İstenen alanla birlikte çağrılacak işlev veya alanda değer yoksa undefined değeri.

FieldName

Alan adı, gtag('set') komutuyla ayarladığınız özel bir alanın adı veya aşağıdaki değerlerden biri olabilir:

Alan Adı Desteklenen hedefler
client_id
  • Google Analytics 4
session_id
  • Google Analytics 4
session_number
  • Google Analytics 4
gclid
  • Google Ads
  • Floodlight

Örnekler

Değeri Promise'e alma 

const gclidPromise = new Promise(resolve => {
  gtag('get', 'DC-XXXXXXXX', 'gclid', resolve)
});

gclidPromise.then((gclid) => {
  // Do something with gclid...
})

Measurement Protocol'e etkinlik gönderme 

gtag('get', 'G-XXXXXXXXXX', 'client_id', (clientID) => {
  sendOfflineEvent(clientID, "tutorial_begin")
});

function sendOfflineEvent(clientID, eventName, eventData) {
  // Send necessary data to your server...
}

Belirlediğiniz bir değeri alma 

gtag('set', {campaign_name: 'Spring_Sale'});

gtag('get', 'G-XXXXXXXXXX', 'campaign_name', (campaign_name) => {
  // Do something with currency value you set earlier.
})

set

set komutu, sayfadaki sonraki her etkinlikle ilişkilendirilecek parametreleri tanımlamanıza olanak tanır.

gtag('set', {<parameter-value-pair>, <parameter-value-pair>});

Örneğin, kampanya parametrelerini paylaşarak aynı sayfadaki birden fazla etiketin bu parametrelere erişmesini sağlayabilirsiniz.

Aşağıdaki örnekte, Efsane Cuma alışveriş etkinliği için kampanya adı ve kimliği ayarlanmaktadır. set kullandığınız için diğer tüm etiketler (ör. GA4 etkinlik etiketleri veya Google Ads yeniden pazarlama etiketleri) bu verilere erişebilir.

gtag('set', 'campaign', {
  'id': 'abc',
  'source': 'google',
  'name': 'black_friday_promotion',
  'term': 'running+shoes',
});

event

Etkinlik verilerini göndermek için event komutunu kullanın.

gtag('event', '<event_name>', {<event_params>});

<event_name> şunlardan biridir:

<event_params>, bir veya daha fazla parametre-değer çiftidir. Her çift virgülle ayrılır.

Aşağıdaki event komutu, iki parametreyle önerilen screen_view etkinliğini tetikler: app_name ve screen_name.

gtag('event', 'screen_view', {
  'app_name': 'myAppName',
  'screen_name': 'Home'
});

İzni yapılandırmak için consent komutunu kullanın.

gtag('consent', {<consent_arg>}, {<consent_params>});

Bu parametrelerin yapılandırdığı davranış hakkında daha fazla bilgi için Yardım Merkezi'ndeki izin bölümüne bakın.

<consent_arg>, 'default' veya 'update' olmalıdır. 'default', kullanılması gereken varsayılan izin parametrelerini ayarlamak için kullanılır. 'update' ise kullanıcı iznini belirttikten sonra bu parametreleri güncellemek için kullanılır.

Aşağıdaki <consent_params> desteklenir:

Alan Adı İzin Verilen Değerler Açıklama
ad_storage 'granted' | 'denied' Reklamcılıkla ilgili bilgilerin çerezler (web) veya cihaz tanımlayıcılar (uygulamalar) gibi yöntemlerle depolanmasını etkinleştirir.
ad_user_data 'granted' | 'denied' Kullanıcı verilerinin reklam amacıyla Google'a gönderilmesine yönelik izinleri belirler.
ad_personalization 'granted' | 'denied' Kişiselleştirilmiş reklamcılığa yönelik izni belirler.
analytics_storage 'granted' | 'denied' Analizle ilgili bilgilerin (ör. ziyaret süresi) çerezler (web) veya uygulama tanımlayıcıları (uygulamalar) gibi yöntemlerle depolanmasını etkinleştirir.
wait_for_update herhangi bir pozitif tam sayı İzin güncelleme çağrısı için beklenecek süreyi milisaniye cinsinden ayarlar.