Sunucu etiketi oluşturma

Sunucu tarafı etiketlemeye giriş başlıklı makalede, Etiket Yöneticisi'ndeki sunucu tarafı etiketlemeye genel bir bakış sunulmuştu. İ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 kapsayıcının geri kalanında kullanılmak üzere bu verileri uyarlar. Bu makalede, söz konusu verilerin sunucu tarafı etiketlerinde nasıl işleneceği açıklanmaktadır.

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

Sunucu kapsayıcılarında, özel yapılandırma gerektirmeden kullanıma hazır üç yerleşik etiket bulunur:

• Google Analytics
• HTTP İsteği

Verileri Google Analytics dışında bir yere 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. Ek etiketleri Topluluk Şablon Galerisi'nde bulabilir veya kendi etiketlerinizi yazabilirsiniz. Bu eğitimde, sunucu kapsayıcısı için kendi etiketlerinizi yazmayla ilgili temel bilgileri öğreneceksiniz.

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 tasarlarken kullanabileceğiniz en iyi uygulamaları öğrenin.
• Kullanıcı tarafından belirtilen veriler ile otomatik olarak toplanan veriler arasındaki farkı ve bu ayrımın neden önemli olduğunu öğrenin.
• Sunucu kapsayıcısında etiketin rolünü öğrenin. Etiketlerin yapması ve yapmaması gerekenleri anlama
• Etiket şablonunu Topluluk Şablon Galerisi'ne ne zaman gönderebileceğinizi öğrenin.

Ön koşullar

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

Baz Analytics etiketi

Bu eğitimde, ö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 aracılığıyla veri alan basit ve varsayımsal bir analiz hizmetidir. Aşağıdaki parametrelere sahiptir:

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 ad ve açıklama ekleyin.

Ardından, etiketinize farklı yapılandırma seçenekleri eklemek için şablon düzenleyicinin Alanlar bölümüne gidin. Bir sonraki soru açıkça şu: Hangi seçeneklere ihtiyacınız var? Etiketi oluşturmak için üç yöntemden birini seçebilirsiniz:

1. Toplam Yapılandırma: Her parametre için bir yapılandırma alanı ekleyin. Kullanıcının her şeyi açıkça 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ırmalar: Bazı parametreler için alanlar bulunur, bazıları için bulunmaz.

Her parametre için alan olması çok esnektir ve kullanıcıya etiket yapılandırması üzerinde tam kontrol sağlar. Ancak uygulamada bu durum genellikle çok fazla tekrarlanan işe yol açar. Özellikle, sayfanın URL'sini içeren Baz Analytics l parametresi gibi öğeler net ve evrenseldir. Etiket her yapılandırıldığında aynı, değişmeyen veri parçasını girmek bilgisayara bırakılması gereken bir iştir.

Belki de yanıt, yalnızca bir etkinlikten veri alan bir etikete sahip olmaktır. Kullanıcının yapması gereken bir şey olmadığından bu, yapılandırabileceği en basit etikettir. Diğer yandan, en kısıtlayıcı ve hassas seçenektir. Kullanıcılar, ihtiyaç duysalar bile etiketin davranışını değiştiremez. Örneğin, web sitelerinde ve Google Analytics'te bir etkinliğe purchase adını veriyor olabilirler ancak Baz Analytics bu etkinliğe buy adını veriyor olabilir. Alternatif olarak, etiketin gelen etkinlik verilerinin yapısıyla ilgili yaptığı varsayımlar gerçekte doğru olmayabilir. Her iki durumda da kullanıcı takılır.

Birçok konuda olduğu gibi, bu sorunun cevabı da iki uç nokta arasında bir yerdedir. Bazı veriler her zaman etkinlikten alınmalıdır. Diğer veriler kullanıcı tarafından yapılandırılmalıdır. Hangisinin hangi türde olduğuna nasıl karar veriyorsunuz? Bu soruyu yanıtlamak için kapsayıcıya gelen verilere daha yakından bakmamız gerekir.

Veriler nereden geliyor?

Google Analytics etiketinden bir sunucu kapsayıcısına gelen veriler kabaca iki kategoriye ayrılabilir: kullanıcı tarafından belirtilen veriler ve otomatik olarak toplanan veriler.

Kullanıcı tarafından belirtilen veriler, kullanıcının bir gtag.js event komutuna girdiği her şeydir. Örneğin, şöyle bir komut:

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

Bu işlem, sunucu kapsayıcısında aşağıdaki parametrelerle sonuçlanır:

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

Bu yeterince basit olsa da etiket açısından çalışmak çok zordur. Bu veriler kullanıcı tarafından girildiği için herhangi bir şey olabilir. Yukarıda belirtildiği gibi, kullanıcı yalnızca önerilen etkinlikleri ve parametreleri gönderiyor olabilir ancak bunu yapması zorunlu değildir. event_name parametresinin konumu (ancak değeri değil!) önemli bir istisnadır. Kullanıcının verilerinin biçimi veya yapısı hakkında herhangi bir garanti verilmez.

Neyse ki kapsayıcı yalnızca kullanıcı tarafından girilen verileri almaz. Ayrıca, tarayıcıdaki Google Analytics 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 aracılığıyla tarayıcı çerezi verileri de kullanılabilir.

Bunlar, yukarıda bahsettiğimiz otomatik olarak toplanan verileri oluşturur. Genel olarak, evrensel ve anlamsal olarak net verilerden oluşur. Tarayıcıdaki bir Google Analytics 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, hangi verilerin kullanıcı tarafından yapılandırılması ve hangi verilerin etikette belirtilmesi gerektiğine karar verirken kullanabileceğimiz faydalı bir araç sunar. Otomatik olarak toplanan veriler, doğrudan etkinlikten güvenli bir şekilde okunabilir. Diğer tüm ayarlar kullanıcı tarafından yapılandırılmalıdır.

Bu nedenle, Baz Analytics etiketinin parametrelerine tekrar göz atın.

• Ölçüm kimliği, id: Otomatik olarak toplanmadığı için etiketi yapılandırırken kullanıcı tarafından girilmesi gereken bir 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ı tarafından tanımlandığı için gerekirse adı geçersiz kılma seçeneği sunmak iyi bir fikirdir.
• Sayfa URL'si, l: Bu değer, her etkinlikte Google Analytics tarayıcı etiketi tarafından otomatik olarak toplanan page_location parametresinden alınabilir. Bu nedenle, kullanıcının değeri manuel olarak girmesini istememelisiniz.
• Kullanıcı kimliği, u: Baz Analytics sunucu etiketinde u parametresi ne kullanıcı tarafından belirtilir ne de sayfadaki etiket tarafından otomatik olarak toplanır. Bunun yerine, kullanıcıların web sitesine yapılan birden fazla ziyarette tanımlanabilmesi için bir tarayıcı çerezinde saklanır. Aşağıdaki uygulamada göreceğiniz gibi, çerezi ayarlamak için setCookie API'sini kullanan Baz Analytics sunucu etiketidir. Bu, çerezin nerede ve nasıl depolandığını bilen tek şeyin Baz Analytics etiketi olduğu anlamına gelir. l gibi, u parametresi otomatik olarak toplanmalıdır.

Etiket yapılandırmasını ayarlamayı tamamladığınızda yapılandırma şu şekilde görünmelidir:

Etiket uygulama

Etiketin yapılandırması tamamlandığına göre artık davranışını korumalı alana sahip JavaScript'te uygulamaya geçebilirsiniz.

Etiketin yapması gereken dört işlem vardır:

1. Etkinlik adını etiketin yapılandırmasından alın.
2. Sayfa URL'sini etkinliğin page_location mülkünden alın.
3. Kullanıcı kimliği hesaplama Etiket, kullanıcı kimliğini _bauid adlı çerezde arar. Bu çerez mevcut değilse etiket yeni bir değer hesaplar ve daha sonraki istekler için bu değeri saklar.
4. Bir URL oluşturun ve Baz Analytics toplama sunucusuna istekte bulunun.

Etiketin kapsayıcıya nasıl uyduğunu da düşünmekte fayda var. Farklı kapsayıcı bileşenleri farklı roller oynar. Bu nedenle, etiketin yapmadığı veya yapmaması gereken şeyler de vardır. Etiketiniz:

• Çalışıp çalışmaması gerektiğini anlamak için etkinliği incelememelidir. Tetikleyiciler tam da bu işe yarar.
• Kapsayıcı, runContainer API'siyle çalıştırılmamalıdır. Bu, müşterinin görevidir.
• Çerezler önemli bir istisnadır. Bu istisna dışında, istek veya yanıtla doğrudan etkileşime girmemesi gerekir. Bu, müşterinin de sorumluluğundadır.

Aşağıdakilerden herhangi birini yapan bir etiket şablonu yazmak, etiketinizi kullanan kullanıcılar 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, kapsayıcının nasıl davranması gerektiğiyle ilgili kullanıcı beklentilerini karşılamaz.

Tüm bunları göz önünde bulundurarak, aşağıda etiket uygulamasının korumalı alan JavaScript'teki açıklamalı bir sürümü 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 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;
}

Böylece etiket uygulanmış olur. 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 istekleri gönderir: https://www.example.com/*
• Çerez ayarlar: _bauid

Etiketiniz için de testler yazmanız gerekir. Şablon testi hakkında daha fazla bilgi edinmek 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, birçok basit hatanın sunucunuza ulaşmasını önleyebilirsiniz.

Etiketinizi Topluluk Şablon Galerisi'ne gönderme

Yeni bir etiket oluşturma, test etme ve dağıtma işlemlerinin tümünü tamamladığınız için bu bilgileri kendinize saklamanıza gerek yoktur. Yeni etiketinizin diğer kullanıcılar için de faydalı olacağını düşünüyorsanız Topluluk Şablon Galerisi'ne gönderebilirsiniz.

Sonuç

Bu eğitimde, bir sunucu kapsayıcısı için etiket yazmayla ilgili temel bilgileri öğrendiniz. Öğrendikleriniz:

• Etkinlik verilerini okumak, HTTP istekleri göndermek ve tarayıcıda çerez ayarlamak için hangi API'lerin kullanılacağı.
• Bir etiket için yapılandırma seçenekleri 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.
• Kapsayıcıdaki bir etiketin rolü; ne yapması ve ne yapmaması gerektiği.
• Etiket şablonlarını Topluluk Şablon Galerisi'ne ne zaman ve nasıl göndereceğiniz.