Sunucu etiketi oluşturma

Sunucu tarafı etiketlemeye giriş bölümünde, Etiket Yöneticisi'ndeki sunucu tarafı etiketlemeye genel bir bakış sunulmaktadır. İstemcilerin ne olduğunu ve ne işe yaradığını öğrendiniz: İstemciler, kullanıcılarınızın cihazlarından etkinlik verilerini alır ve container'ın geri kalanı tarafından kullanılmak üzere uyarlar. Bu makalede, sunucu tarafı etiketlerde bu verilerin nasıl işleneceği açıklanmaktadır.

Bir sunucu kapsayıcısında etiketler, istemcilerinizden gelen etkinlik verilerini alır, dönüştürür ve toplanması ve analiz edilmesi için geri gönderir. Etiketler, verileri istediğiniz yere gönderebilir. Hedef, HTTP isteklerini kabul ettiği sürece bir sunucu kapsayıcısından veri de kabul edebilir.

Sunucu kapsayıcılarında, özel bir yapılandırma olmadan kullanıma hazır olan üç yerleşik etiket vardır:

• Google Analytics 4
• Google Analytics: Universal Analytics
• HTTP İsteği

Google Analytics'ten başka bir yere veri göndermek istiyorsanız veya HTTP İsteği etiketinin sağladığından daha fazla özelliğe ihtiyacınız varsa farklı bir etiket kullanmanız gerekir. Topluluk Şablon Galerisi'nde ek etiketler bulabilir veya kendi etiketlerinizi yazabilirsiniz. Bu eğitim, bir sunucu kapsayıcısı için kendi etiketlerinizi yazmayla ilgili temel bilgileri öğretir.

Hedefler

• Etkinlik verilerini okumak, HTTP istekleri göndermek ve tarayıcıda çerez ayarlamak için hangi API'lerin kullanılacağını öğrenin.
• Etiketinizin yapılandırma seçeneklerini tasarlamayla ilgili en iyi uygulamaları öğrenin.
• Kullanıcı tanımlı veriler ile otomatik olarak toplanan veriler arasındaki farkı ve bu ayrımın neden önemli olduğunu öğrenin.
• Sunucu kapsayıcısında bir etiketin rolünü öğrenin. Bir etiketin ne yapması ve yapmaması gerektiğini anlayın.
• Topluluk Şablon Galerisi'ne ne zaman etiket şablonu gönderebileceğinizi öğrenin.

Ön koşullar

• Dağıtılmış bir sunucu kapsayıcısı
• Etiket Yöneticisi, sunucu kapsayıcıları ve bunların istemciler, etiketler, tetikleyiciler ve değişkenler gibi temel kavramları hakkında bilgi sahibi olma
• Etiketler ve değişkenler için şablon yazma hakkındaki temel bilgilere aşinalık

Baz Analytics etiketi

Bu eğiticide, ölçüm verilerini Baz Analytics adlı bir hizmete gönderen bir etiket oluşturacaksınız.

Baz Analytics, https://example.com/baz_analytics adresine HTTP GET istekleri üzerinden veri alan basit ve varsayımsal bir analiz hizmetidir. Aşağıdaki parametrelere sahiptir:

Parametre	Örnek	Açıklama
id	BA-1234	Baz Analytics hesabınızın kimliği.
en	click	Etkinlik adı.
l	https://www.google.com/search?q=sgtm	URL'sini girin.
u	2384294892	İşlemi gerçekleştiren kullanıcının kimliği. Birden fazla işlemi tek bir kullanıcıya bağlamak için kullanılır.

Etiket yapılandırması

İlk olarak etiket şablonunu oluşturun. Kapsayıcınızın Şablonlar bölümüne gidin ve Etiket Şablonları bölümünde Yeni'yi tıklayın. Etiketinize bir ad ve açıklama ekleyin.

Ardından, etiketiniz için farklı yapılandırma seçenekleri eklemek üzere şablon düzenleyicinin Alanlar bölümüne gidin. Sıradaki soru şudur: Hangi seçeneklere ihtiyacınız var? Etiketi oluşturmak için seçebileceğiniz üç yol vardır:

1. Toplam Yapılandırma: Her parametre için bir yapılandırma alanı ekleyin. Kullanıcının her şeyi açık bir şekilde ayarlamasını zorunlu kılın.
2. Yapılandırma Yok: Etiketi yapılandırma seçeneği yoktur. Tüm veriler doğrudan etkinlikten alınır.
3. Bazı Yapılandırma: Bazı parametreler için alanları içerirken bazıları için alanları içermez.

Her parametre için alanların bulunması çok esnektir ve kullanıcıya etiket yapılandırması üzerinde tam kontrol sağlar. Ancak pratikte bu durum genellikle birçok işin yinelenmesine yol açar. Özellikle, sayfanın URL'sini içeren Baz Analytics l parametresi açık ve evrenseldir. Etiket her yapılandırıldığında aynı ve değişmeyen veri parçasını girmek, bilgisayarda yapılabilecek en iyi şeydir.

Belki de yanıt, yalnızca bir etkinlikten veri alan bir etikete sahip olmaktır. Gerçekte yapmaları gereken bir şey olmadığından, bu, kullanıcıların yapılandırabileceği en basit etikettir. Diğer yandan, aynı zamanda en kısıtlayıcı ve kırılgan seçenektir. Kullanıcılar gerektiğinde etiketin davranışını değiştiremez. Örneğin, kullanıcı web sitesinde ve Google Analytics'te bir etkinliği purchase olarak adlandırıyor ancak Baz Analytics bunu buy olarak adlandırıyor. Ya da etiketin, gelen etkinlik verilerinin yapısı hakkında yaptığı varsayımların gerçekte gerçeklikle eşleşmemesi olabilir. Her iki durumda da, kullanıcı takılıp kalır.

Birçok konuda olduğu gibi, bu iki uç noktanın arasında bir yerde yatıyor. Bazı verileri her zaman etkinlikten almak mantıklıdır. Diğer veriler kullanıcı tarafından yapılandırılmalıdır. Hangisinin hangisi olduğuna nasıl karar verirsiniz? Bu soruyu yanıtlamak için, kapsayıcıya gelen verileri daha yakından incelememiz gerekir.

Veriler nereden geliyor?

Google Analytics 4 etiketinden bir sunucu kapsayıcısına gelen veriler kabaca iki kategoriye ayrılabilir: Kullanıcı tanımlı veriler ve otomatik olarak toplanan veriler.

Kullanıcı tanımlı veriler, bir kullanıcının gtag.js event komutuna yerleştirdiği her şeydir. Örneğin, aşağıdaki gibi bir komut:

gtag('event', 'search', {
  search_term: 'beets',
});

Sunucu kapsayıcısında aşağıdaki parametrelerle sonuçlanır:

{
  event_name: 'search',
  search_term: 'beets',
}

Bu yeterince basittir, ancak etiket açısından çalışmak oldukça zordur. Bu veriler kullanıcı tarafından girildiği için herhangi bir değer olabilir. Belki de yukarıda olduğu gibi kullanıcı yalnızca önerilen etkinlikleri ve parametreleri gönderir ancak gönderme zorunluluğu yoktur. event_name parametresinin konumu (değeri değil) dışında, kullanıcı verilerinin biçim veya yapısıyla ilgili herhangi bir garanti verilmez.

Neyse ki, kapsayıcının alacağı tek veri kullanıcı tarafından girilen veriler değildir. Ayrıca, tarayıcıda Google Analytics 4 etiketi tarafından otomatik olarak toplanan bir dizi veri de alır. Bu kaynaklara aşağıdakiler dahildir:

• ip_override
• language
• page_location
• page_referrer
• page_title
• screen_resolution
• user_agent

Ayrıca, sunucu isteği bir web tarayıcısından geliyorsa getCookieValue API'si aracılığıyla kullanılabilen tarayıcı çerez verileri de olabilir.

Bunlar birlikte, yukarıda bahsettiğimiz otomatik olarak toplanan verileri oluşturur. Genel olarak, evrensel ve semantik olarak belirsiz verilerden oluşur. Tarayıcıdaki bir GA4 etiketinden istek geldiğinde bu veriler her zaman kullanılabilir ve her zaman aynı biçimde olur. Bu parametreler hakkında daha fazla bilgi için etkinlik referansına göz atın.

Bu sınıflandırma, kullanıcı tarafından hangi verilerin yapılandırılacağına ve etikette hangi verilerin belirtilmesi gerektiğine karar verirken kullanmamız gereken faydalı bir araç sunar. Otomatik olarak toplanan veriler doğrudan etkinlikten güvenle okunabilir. Diğer her şey kullanıcı tarafından yapılandırılmalıdır.

Bunu göz önünde bulundurarak, Baz Analytics etiketinin parametrelerine bir kez daha göz atın.

• Ölçüm Kimliği, id: Otomatik olarak toplanmadığı için bu, kullanıcının etiketi yapılandırırken girilmesi gereken değerin net bir örneğidir.
• Etkinlik adı, en: Yukarıda belirtildiği gibi, etkinlik adı her zaman doğrudan event_name parametresinden alınabilir. Ancak, değeri kullanıcı tanımlı olduğu için gerekirse adı geçersiz kılma imkanı sunmak iyi bir fikirdir.
• Sayfa URL'si, l: Bu değer, her etkinlikte Google Analytics GA4 tarayıcı etiketi tarafından otomatik olarak toplanan page_location parametresinden alınabilir. Bu nedenle, kullanıcının manuel olarak bir değer girmesini gerektirmemelisiniz.
• Kullanıcı Kimliği, u: Baz Analytics sunucu etiketinde u parametresi kullanıcı tarafından belirtilmez veya sayfadaki etiket tarafından otomatik olarak toplanmaz. Bunun yerine, bir tarayıcı çerezinde saklanır. Böylece, kullanıcılar web sitesine yapılan birden çok ziyarette tanımlanabilir. Aşağıdaki uygulamada göreceğiniz gibi, çerezi ayarlamak için setCookie API'yi kullanan Baz Analytics sunucu etiketi kullanılır. Yani Baz Analytics etiketi, çerezin nerede ve nasıl saklandığını bilen tek şeydir. l gibi u parametresi de otomatik olarak toplanmalıdır.

Etiket yapılandırmasını ayarladıktan sonra etiket şuna benzer bir görünümde olacaktır:

Etiket uygulama

Etiketin yapılandırılması kare şeklinde tamamlandığına göre, davranışını korumalı alana alınmış JavaScript'te uygulamaya geçmeye hazırsınız.

Etiketin dört şey yapması gerekir:

1. Etkinlik adını etiketin yapılandırmasından alın.
2. Etkinliğin page_location mülkünden sayfa URL'sini alın.
3. Bir kullanıcı kimliği hesaplayın. Etiket, kullanıcı kimliğini _bauid adlı bir çerezde arar. Çerez yoksa etiket yeni bir değer hesaplar ve sonraki istekler için saklar.
4. Bir URL oluşturun ve Baz Analytics koleksiyon sunucusuna bir istek gönderin.

Etiketin kapsayıcıya bir bütün olarak nasıl sığacağını düşünmek de işe yarar. Farklı kapsayıcı bileşenleri farklı roller oynar. Bu nedenle etiketin yapmaması veya yapmaması gereken şeyler de vardır. Etiketiniz:

• Çalıştırılması gerekip gerekmediğini belirlemek için etkinliği incelememelidir. Tetikleyicinin amacı budur.
• Kapsayıcı runContainer API ile çalıştırılmamalıdır. Bu müşterinin işi.
• Önemli olan çerezler hariç olmak üzere, istek veya yanıtla doğrudan etkileşimde bulunmaya çalışmamalıdır. Bu aynı zamanda müşterinin işi.

Bunlardan herhangi birini yapan bir etiket şablonu yazmak, etiketinizi kullanan kişiler için kafa karıştırıcı davranışlara neden olur. Örneğin, gelen isteğe yanıt gönderen bir etiket, istemcinin aynı işlemi yapmasını engeller. Bu, kullanıcıların container'ın nasıl davranması gerektiği konusundaki beklentilerini karşılar.

Tüm bunlar göz önünde bulundurularak aşağıda, etiketin korumalı alana alınmış JS'deki ek açıklamalı bir uygulaması verilmiştir.

const encodeUriComponent = require('encodeUriComponent');
const generateRandom = require('generateRandom');
const getCookieValues = require('getCookieValues');
const getEventData = require('getEventData');
const logToConsole = require('logToConsole');
const makeString = require('makeString');
const sendHttpGet = require('sendHttpGet');
const setCookie = require('setCookie');

const USER_ID_COOKIE = '_bauid';
const MAX_USER_ID = 1000000000;

// The event name is taken from either the tag's configuration or from the
// event. Configuration data comes into the sandboxed code as a predefined
// variable called 'data'.
const eventName = data.eventName || getEventData('event_name');

// page_location is automatically collected by the Google Analytics 4 tag.
// Therefore, it's safe to take it directly from event data rather than require
// the user to specify it. Use the getEventData API to retrieve a single data
// point from the event. There's also a getAllEventData API that returns the
// entire event.
const pageLocation = getEventData('page_location');
const userId = getUserId();

const url = 'https://www.example.com/baz_analytics?' +
    'id=' + encodeUriComponent(data.measurementId) +
    'en=' + encodeUriComponent(eventName) +
    (pageLocation ? 'l=' + encodeUriComponent(pageLocation) : '') +
    'u=' + userId;

// The sendHttpGet API takes a URL and returns a promise that resolves with the
// result once the request completes. You must call data.gtmOnSuccess() or
// data.gtmOnFailure() so that the container knows when the tag has finished
// executing.
sendHttpGet(url).then((result) => {
  if (result.statusCode >= 200 && result.statusCode < 300) {
    data.gtmOnSuccess();
  } else {
    data.gtmOnFailure();
  }
});

// The user ID is taken from a cookie, if present. If it's not present, a new ID
// is randomly generated and stored for later use.
//
// Generally speaking, tags should not interact directly with the request or
// response. This prevents different tags from conflicting with each other.
// Cookies, however, are an exception. Tags are the only container entities that
// know which cookies they need to read or write. Therefore, it's okay for tags
// to interact with them directly.
function getUserId() {
  const userId = getCookieValues(USER_ID_COOKIE)[0] || generateRandom(0, MAX_USER_ID);
  // The setCookie API adds a value to the 'cookie' header on the response.
  setCookie(USER_ID_COOKIE, makeString(userId), {
    'max-age': 3600 * 24 * 365 * 2,
    domain: 'auto',
    path: '/',
    httpOnly: true,
    secure: true,
  });

  return userId;
}

Bununla birlikte, etiket uygulanır. Etiketi kullanabilmek için API izinlerini doğru şekilde ayarlamanız gerekir. Şablon Düzenleyici'nin İzinler sekmesine gidin ve aşağıdaki izinleri belirtin:

• Çerez Değerlerini Okur: _bauid
• Etkinlik Verilerini Okur: event_name ve page_location
• HTTP İstekleri gönderir: https://www.example.com/*
• Çerez oluşturur: _bauid

Ayrıca etiketiniz için testler yazmanız gerekir. Şablon testi hakkında daha fazla bilgi için şablon geliştirici kılavuzunun testler bölümünü okuyun.

Son olarak, etiketinizi en az bir kez Kodu Çalıştır düğmesiyle çalıştırmayı unutmayın. Bu sayede sunucunuza yüklenecek basit birçok hatanın önüne geçilir.

Etiketinizi Topluluk Şablon Galerisi'ne gönderme

Yeni etiket oluşturma, test etme ve dağıtma işlemlerinin tamamını tamamladığınız için etiketi kendinize saklamanız gerekmez. Yeni etiketinizin diğer kullanıcılara faydalı olacağını düşünüyorsanız etiketi Topluluk Şablon Galerisi'ne göndermeyi düşünün.

Sonuç

Bu eğiticide, sunucu kapsayıcısı için etiket yazmanın temellerini öğrendiniz. Öğrendikleriniz:

• Etkinlik verilerini okumak, HTTP istekleri göndermek ve tarayıcıda çerezler ayarlamak için hangi API'lerin kullanılacağı.
• Bir etiket için yapılandırma seçeneklerini tasarlamayla ilgili en iyi uygulamalar.
• Kullanıcı tarafından belirtilen veriler ile otomatik olarak toplanan veriler arasındaki fark ve bu ayrımın neden önemli olduğu.
• Bir etiketin kapsayıcıdaki rolü; ne yapması ve yapmaması gerektiği.
• Etiket şablonlarının Topluluk Şablon Galerisi'ne ne zaman ve nasıl gönderileceği.