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()'ye 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 sayfaya nasıl ekleyeceğinizi öğrenmek için yükleme kılavuzuna bakın.

Parametre kapsamı

Parametre değerlerini tek tek etkinliklere, belirli bir <TARGET_ID> gönderilen tüm etkinliklere veya tüm etkinliklere genel olarak uygulayabilirsiniz. Bu, event, config ve set komutları kullanılarak gerçekleştirilir.

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

// 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 öncelikli olur. config kapsamındaki parametreler ise set kullanılarak genel olarak kapsamı belirlenen parametrelere göre öncelikli olur.

// 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 eklemenizi sağlar. Bu ayar genellikle bir ürün için ürüne özel bir yapılandırmadır ancak hem Google Ads hem de Google Analytics'i kullanıyorsanız bu ayarı 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öndereceğ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.

  • GT-XXXXXX, G-XXXXXX veya AW-YYYYYY gibi bir etiket kimliği, 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 kimliklerle aynı görünebilir (ör. bir Google Analytics mülkü için G-XXXXXX veya bir 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, söz konusu <TARGET_ID> ile ilişkilendirilmiş Google etiketinin davranışını yapılandırır. Komut dosyasında yer alan etiket kimliği src genellikle Google etiketini yüklese de gtag('config') komutunda hesabınızla ilişkili geçerli bir etiket kimliği kullanabilirsiniz.

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

  • Verileri birden fazla hedefe gönderiyorsanız veya birden fazla etiket kullanıyorsanız src komut dosyasında yalnızca bir etiket kimliği içeren tek bir Google etiketi snippet'i eklemeniz gerekir. 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 etiketi Google Ads hesabına veri gönderecek şekilde yapılandırma işlemi gösterilmektedir:

gtag('config', 'TAG_ID');

Burada "TAG_ID", Google etiketinin etiket kimliğidir.

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

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

get

set komutuyla ayarlanan değerler dahil olmak üzere, gtag.js'dan ç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.

FieldName

Alan adı, gtag('set') komutuyla ayarladığınız bir özel 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

Bir Promise'e değer 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 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, aynı sayfadaki birden fazla etiket tarafından erişilebilmesi için kampanya parametrelerini paylaşabilirsiniz.

Aşağıdaki örnekte, bir Kara Cuma alışveriş etkinliği için kampanya adı ve kimliği ayarlama gösterilmektedir. set kullandığınız için GA4 etkinlik etiketleri veya Google Ads yeniden pazarlama etiketleri gibi diğer tüm etiketler 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 biri olmalıdır:

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

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

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 başlıklı makaleye bakın.

<consent_arg>, 'default' veya 'update' olmalıdır. 'default', kullanılacak varsayılan izin parametrelerini ayarlamak için, 'update' ise kullanıcı iznini belirttiğinde 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.