Cách tạo thẻ máy chủ

Trong bài viết Giới thiệu về tính năng gắn thẻ phía máy chủ, bạn đã nắm được thông tin tổng quan về tính năng gắn thẻ phía máy chủ trong Trình quản lý thẻ. Bạn đã tìm hiểu về ứng dụng và chức năng của ứng dụng: Ứng dụng nhận dữ liệu sự kiện từ thiết bị của người dùng và điều chỉnh dữ liệu đó để sử dụng cho phần còn lại của vùng chứa. Bài viết này mô tả cách xử lý dữ liệu đó trong thẻ phía máy chủ.

Trong vùng chứa máy chủ, các thẻ sẽ nhận dữ liệu sự kiện đến từ các máy khách của bạn, chuyển đổi dữ liệu đó rồi gửi lại để thu thập và phân tích. Thẻ có thể gửi dữ liệu đến bất cứ nơi nào bạn muốn. Miễn là đích đến chấp nhận các yêu cầu HTTP, thì đích đến cũng có thể chấp nhận dữ liệu từ một vùng chứa phía máy chủ.

Vùng chứa phía máy chủ có 3 thẻ tích hợp sẵn, sẵn sàng sử dụng mà không cần cấu hình tuỳ chỉnh:

• Google Analytics
• Yêu cầu HTTP

Nếu muốn gửi dữ liệu đến một nơi khác ngoài Google Analytics hoặc cần nhiều tính năng hơn so với thẻ Yêu cầu HTTP, bạn sẽ cần sử dụng một thẻ khác. Bạn có thể tìm thấy các thẻ khác trong Thư viện mẫu cho cộng đồng hoặc bạn có thể tự viết thẻ. Hướng dẫn này sẽ hướng dẫn bạn những kiến thức cơ bản về cách viết thẻ của riêng bạn cho một vùng chứa máy chủ.

Mục tiêu

• Tìm hiểu những API cần dùng để đọc dữ liệu sự kiện, gửi yêu cầu HTTP và đặt cookie trong trình duyệt.
• Tìm hiểu các phương pháp hay nhất để thiết kế các lựa chọn cấu hình cho thẻ.
• Tìm hiểu sự khác biệt giữa dữ liệu do người dùng chỉ định và dữ liệu được thu thập tự động, cũng như lý do khiến sự khác biệt đó trở nên quan trọng.
• Tìm hiểu vai trò của thẻ trong vùng chứa phía máy chủ. Hiểu rõ những việc mà thẻ nên và không nên làm.
• Tìm hiểu thời điểm bạn nên cân nhắc việc gửi mẫu thẻ đến Thư viện mẫu cho cộng đồng.

Điều kiện tiên quyết

• Vùng chứa phía máy chủ đã triển khai
• Quen thuộc với Trình quản lý thẻ, vùng chứa máy chủ và các khái niệm cơ bản của vùng chứa máy chủ như ứng dụng, thẻ, trình kích hoạt và biến
• Làm quen với các khái niệm cơ bản về việc viết mẫu cho thẻ và biến

Thẻ Baz Analytics

Trong hướng dẫn này, bạn sẽ tạo một thẻ gửi dữ liệu đo lường đến một dịch vụ có tên là Baz Analytics.

Baz Analytics là một dịch vụ phân tích đơn giản, giả định, có thể nhận dữ liệu thông qua các yêu cầu HTTP GET đến https://example.com/baz_analytics. Phương thức này có các tham số sau:

Cấu hình thẻ

Việc đầu tiên cần làm là tạo mẫu thẻ. Chuyển đến mục Mẫu trong vùng chứa của bạn rồi nhấp vào Mới trong mục Mẫu thẻ. Thêm tên và nội dung mô tả cho thẻ.

Tiếp theo, hãy chuyển đến mục Trường của trình chỉnh sửa mẫu để thêm các lựa chọn cấu hình khác nhau cho thẻ của bạn. Câu hỏi tiếp theo là: bạn cần những lựa chọn nào? Bạn có thể chọn một trong ba cách sau để tạo thẻ:

1. Tổng số cấu hình: Thêm một trường cấu hình cho mỗi thông số. Yêu cầu người dùng đặt mọi thứ một cách rõ ràng.
2. Không có cấu hình: Không có lựa chọn nào để định cấu hình thẻ. Tất cả dữ liệu đều được lấy trực tiếp từ sự kiện.
3. Một số cấu hình: Có các trường cho một số tham số và không có các trường cho những tham số khác.

Việc có các trường cho mọi thông số rất linh hoạt và giúp người dùng kiểm soát hoàn toàn cấu hình thẻ của họ. Tuy nhiên, trên thực tế, điều này thường dẫn đến nhiều công việc trùng lặp. Cụ thể, những thông tin như tham số l của Baz Analytics (chứa URL của trang) là thông tin rõ ràng và phổ biến. Nhập cùng một phần dữ liệu không thay đổi mỗi khi thẻ được định cấu hình là việc tốt nhất nên để máy tính thực hiện.

Có lẽ câu trả lời là sử dụng một thẻ chỉ lấy dữ liệu từ một sự kiện. Đây là thẻ đơn giản nhất mà người dùng có thể định cấu hình, vì họ không cần làm gì cả. Mặt khác, đây cũng là lựa chọn hạn chế và dễ bị ảnh hưởng nhất. Người dùng không thể thay đổi hành vi của thẻ ngay cả khi cần. Ví dụ: có thể họ gọi một sự kiện là purchase trên trang web và trong Google Analytics, nhưng Baz Analytics lại gọi sự kiện đó là buy. Hoặc có thể các giả định mà thẻ đưa ra về cấu trúc của dữ liệu sự kiện đến không thực sự khớp với thực tế. Trong cả hai trường hợp, người dùng đều không thể tiếp tục.

Giống như nhiều thứ khác, câu trả lời nằm ở đâu đó giữa hai thái cực. Một số dữ liệu luôn có ý nghĩa khi lấy từ sự kiện. Người dùng phải định cấu hình dữ liệu khác. Làm cách nào để bạn phân biệt được hai loại này? Để trả lời câu hỏi đó, chúng ta cần xem xét kỹ hơn dữ liệu đang được đưa vào vùng chứa.

Dữ liệu đến từ đâu?

Dữ liệu đi vào vùng chứa phía máy chủ từ thẻ Google Analytics có thể được chia thành hai danh mục: Dữ liệu do người dùng chỉ định và dữ liệu được thu thập tự động.

Dữ liệu do người dùng chỉ định là tất cả những gì người dùng đưa vào lệnh eventgtag.js. Ví dụ: một lệnh như sau:

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

Sẽ dẫn đến các tham số sau trong vùng chứa phía máy chủ:

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

Điều đó khá đơn giản, nhưng từ góc độ của thẻ, rất khó để làm việc. Vì người dùng nhập dữ liệu này, nên dữ liệu có thể là bất kỳ thông tin nào. Có thể, như trên, người dùng chỉ gửi sự kiện và thông số được đề xuất, nhưng không có yêu cầu nào bắt buộc họ phải làm như vậy. Ngoại trừ vị trí (nhưng không phải giá trị!) của thông số event_name, không có gì đảm bảo về hình thức hoặc cấu trúc dữ liệu của người dùng.

Rất may là dữ liệu do người dùng nhập không phải là thứ duy nhất mà vùng chứa sẽ nhận được. Thẻ này cũng sẽ nhận được một loạt dữ liệu do thẻ Google Analytics tự động thu thập trong trình duyệt. Trong đó có:

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

Ngoài ra, nếu yêu cầu của máy chủ đến từ một trình duyệt web, thì cũng có thể có dữ liệu cookie của trình duyệt thông qua API getCookieValue.

Tất cả những dữ liệu này tạo nên dữ liệu được thu thập tự động mà chúng tôi đã đề cập ở trên. Nhìn chung, dữ liệu này bao gồm dữ liệu phổ biến và không mơ hồ về mặt ngữ nghĩa. Khi một yêu cầu đến từ thẻ Google Analytics trong trình duyệt, dữ liệu này sẽ luôn có sẵn và luôn có cùng định dạng. Để biết thêm thông tin về các thông số này, hãy xem tài liệu tham khảo về sự kiện.

Phân loại này cung cấp cho chúng ta một công cụ hữu ích để sử dụng khi quyết định người dùng nên định cấu hình dữ liệu nào và dữ liệu nào nên được chỉ định trong thẻ. Bạn có thể đọc trực tiếp dữ liệu được thu thập tự động từ sự kiện một cách an toàn. Mọi thứ khác đều do người dùng định cấu hình.

Hãy xem xét lại các tham số cho thẻ Baz Analytics.

• Mã đo lường, id: Vì không được thu thập tự động, nên đây là một ví dụ rõ ràng về giá trị mà người dùng nên nhập khi định cấu hình thẻ.
• Tên sự kiện, en: Như đã đề cập ở trên, bạn luôn có thể lấy trực tiếp tên sự kiện từ tham số event_name. Tuy nhiên, vì giá trị của nó do người dùng xác định, nên bạn nên cung cấp khả năng ghi đè tên nếu cần.
• URL trang, l: Giá trị này có thể được lấy từ tham số page_location. Tham số này được thẻ trình duyệt Google Analytics tự động thu thập trên mọi sự kiện. Do đó, bạn không nên yêu cầu người dùng nhập giá trị theo cách thủ công.
• Mã nhận dạng người dùng, u: Trong thẻ máy chủ Baz Analytics, tham số u không phải do người dùng chỉ định cũng như không được thẻ tự động thu thập trên trang. Thay vào đó, mã này được lưu trữ trong cookie của trình duyệt để người dùng có thể được xác định trong nhiều lượt truy cập vào trang web. Như bạn sẽ thấy trong quá trình triển khai bên dưới, đây là thẻ máy chủ Baz Analytics sử dụng API setCookie để đặt cookie. Điều này có nghĩa là thẻ Baz Analytics là thứ duy nhất biết nơi và cách lưu trữ cookie. Giống như l, tham số u sẽ được thu thập tự động.

Sau khi bạn thiết lập xong cấu hình thẻ, cấu hình đó sẽ có dạng như sau:

Triển khai thẻ

Giờ đây, bạn đã hoàn tất cấu hình của thẻ và sẵn sàng chuyển sang triển khai hành vi của thẻ trong JavaScript dạng hộp cát.

Thẻ này cần thực hiện 4 việc sau:

1. Lấy tên sự kiện từ cấu hình của thẻ.
2. Lấy URL trang từ thuộc tính page_location của sự kiện.
3. Tính toán mã nhận dạng người dùng. Thẻ này sẽ tìm mã nhận dạng người dùng trong một cookie có tên là _bauid. Nếu không có cookie đó, thẻ sẽ tính toán một giá trị mới và lưu trữ giá trị đó cho các yêu cầu sau.
4. Tạo một URL và đưa ra yêu cầu đến máy chủ thu thập dữ liệu của Baz Analytics.

Bạn cũng nên dành chút thời gian để suy nghĩ về cách thẻ phù hợp với vùng chứa nói chung. Các thành phần vùng chứa khác nhau đóng vai trò khác nhau, vì vậy cũng có những việc mà thẻ không làm hoặc không nên làm. Thẻ của bạn:

• Không nên kiểm tra sự kiện để tìm hiểu xem sự kiện có nên chạy hay không. Đó là mục đích của một điều kiện kích hoạt.
• Không nên chạy vùng chứa bằng API runContainer. Đó là việc của ứng dụng.
• Với ngoại lệ quan trọng là cookie, nó không nên cố gắng tương tác trực tiếp với yêu cầu hoặc phản hồi. Đó cũng là công việc của khách hàng.

Việc viết một mẫu thẻ thực hiện bất kỳ điều nào trong số này sẽ dẫn đến hành vi gây nhầm lẫn cho người dùng thẻ của bạn. Ví dụ: thẻ gửi phản hồi cho yêu cầu đến sẽ ngăn máy khách làm điều tương tự. Điều đó sẽ phá vỡ kỳ vọng của người dùng về cách vùng chứa hoạt động.

Với tất cả những điều đó, dưới đây là một bản triển khai được chú thích của thẻ trong JS hộp cát.

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;
}

Sau đó, thẻ sẽ được triển khai. Bạn cần thiết lập đúng các quyền API thì mới có thể sử dụng thẻ này. Chuyển đến thẻ Quyền của Trình chỉnh sửa mẫu rồi chỉ định các quyền sau:

• Đọc giá trị cookie: _bauid
• Đọc dữ liệu sự kiện: event_name và page_location
• Gửi yêu cầu HTTP: https://www.example.com/*
• Đặt cookie: _bauid

Bạn cũng nên viết các bài kiểm thử cho thẻ của mình. Để đọc thêm về kiểm thử mẫu, hãy đọc phần kiểm thử trong hướng dẫn dành cho nhà phát triển mẫu.

Cuối cùng, đừng quên thử chạy thẻ bằng nút Run Code (Chạy mã) ít nhất một lần. Việc này sẽ ngăn chặn nhiều lỗi đơn giản xuất hiện trên máy chủ của bạn.

Gửi thẻ của bạn đến Thư viện mẫu cho cộng đồng

Vì bạn đã thực hiện tất cả các bước tạo, kiểm thử và triển khai thẻ mới, nên không có lý do gì để giữ thẻ đó cho riêng mình. Nếu bạn cho rằng thẻ mới của mình sẽ hữu ích cho người khác, hãy cân nhắc việc gửi thẻ đó đến Thư viện mẫu cho cộng đồng.

Kết luận

Trong hướng dẫn này, bạn đã tìm hiểu những kiến thức cơ bản về cách viết thẻ cho một vùng chứa máy chủ. Bạn đã tìm hiểu:

• API nào cần dùng để đọc dữ liệu sự kiện, gửi yêu cầu HTTP và đặt cookie trên trình duyệt.
• Các phương pháp hay nhất để thiết kế các lựa chọn cấu hình cho một thẻ.
• Sự khác biệt giữa dữ liệu do người dùng chỉ định và dữ liệu được thu thập tự động, cũng như lý do khiến sự khác biệt đó trở nên quan trọng.
• Vai trò của thẻ trong vùng chứa; những việc thẻ nên và không nên làm.
• Thời điểm và cách gửi mẫu thẻ đến Thư viện mẫu cho cộng đồng.