Trang này được dịch bởi Cloud Translation API.

API mẫu tuỳ chỉnh

Core API

Các API này hoạt động với JavaScript dạng hộp cát để tạo mẫu tuỳ chỉnh trong Trình quản lý thẻ của Google. Mỗi API được thêm bằng một câu lệnh require(), ví dụ:

const myAPI = require('myAPI');

`addConsentListener`

Đăng ký một hàm trình nghe để thực thi khi trạng thái của loại sự đồng ý được chỉ định thay đổi.

Trình nghe đã cho sẽ được gọi mỗi khi trạng thái cho loại đồng ý được chỉ định thay đổi từ bị từ chối thành được đồng ý hoặc từ được đồng ý thành bị từ chối. Loại yêu cầu đồng ý không có trạng thái được coi là đã cho phép, vì vậy, trình nghe sẽ không được gọi nếu loại yêu cầu đồng ý chưa đặt được cập nhật thành đã cho phép. Các hàm của trình nghe sẽ chịu trách nhiệm đảm bảo mã của chúng chạy số lần thích hợp.

Ví dụ:

const isConsentGranted = require('isConsentGranted');
const addConsentListener = require('addConsentListener');

if (!isConsentGranted('ad_storage')) {
  let wasCalled = false;
  addConsentListener('ad_storage', (consentType, granted) => {
    if (wasCalled) return;
    wasCalled = true;

    const cookies = getMyCookies();
    sendFullPixel(cookies);
  });
}

Cú pháp

addConsentListener(consentType, listener)

Tham số

Thông số	Loại	Mô tả
`consentType`	string	Loại sự đồng ý để theo dõi các thay đổi về trạng thái.
`listener`	hàm	Hàm sẽ chạy khi trạng thái của loại đồng ý đã chỉ định thay đổi.

Khi được gọi, trình nghe sẽ được truyền loại đồng ý đang thay đổi và giá trị mới của loại đồng ý đó:

Thông số	Loại	Mô tả
`consentType`	string	Loại đồng ý đang được thay đổi.
`granted`	boolean	Một giá trị boolean là true nếu loại đồng ý được chỉ định đang được thay đổi thành đã cấp.

Các quyền liên quan

Quyền access_consent có quyền đọc đối với loại sự đồng ý.

`addEventCallback`

API addEventCallback cho phép bạn đăng ký một hàm gọi lại sẽ được gọi ở cuối một sự kiện. Lệnh gọi lại sẽ được gọi khi tất cả các thẻ cho sự kiện đã thực thi hoặc nếu đạt đến thời gian chờ sự kiện trên trang. Lệnh gọi lại được truyền hai giá trị, mã nhận dạng của vùng chứa gọi hàm và một đối tượng chứa thông tin về sự kiện.

Cú pháp

addEventCallback(callback)

Tham số

Thông số	Loại	Mô tả
`callback`	hàm	Hàm sẽ được gọi ở cuối sự kiện.

Đối tượng eventData chứa dữ liệu sau:

Tên khóa	Loại	Mô tả
`tags`	Mảng	Một mảng gồm các đối tượng dữ liệu thẻ. Mọi thẻ đã kích hoạt trong sự kiện sẽ có một mục trong mảng này. Đối tượng dữ liệu thẻ chứa mã nhận dạng của thẻ (`id`), trạng thái thực thi (`status`) và thời gian thực thi (`executionTime`). Dữ liệu thẻ cũng sẽ bao gồm siêu dữ liệu thẻ bổ sung đã được định cấu hình trên thẻ.

Ví dụ

addEventCallback(function(ctid, eventData) {
  logToConsole('Tag count for container ' + ctid + ': ' + eventData['tags'].length);
});

Các quyền liên quan

read_event_metadata

`aliasInWindow`

API aliasInWindow cho phép bạn tạo một bí danh (ví dụ: window.foo = window.bar), giúp hỗ trợ một số thẻ nhất định yêu cầu bí danh. Chỉ định giá trị trong đối tượng window tìm thấy tại fromPath cho khoá trong đối tượng window tại toPath. Trả về true nếu thành công, nếu không thì trả về false.

Cú pháp

aliasInWindow(toPath, fromPath)

Tham số

Thông số	Loại	Mô tả
`toPath`	string	Đường dẫn được phân tách bằng dấu chấm vào đối tượng `window` mà giá trị sẽ được sao chép vào. Tất cả các thành phần trong đường dẫn cho đến thành phần cuối cùng đều phải tồn tại trong đối tượng `window`.
`fromPath`	string	Đường dẫn được phân tách bằng dấu chấm vào `window` đến giá trị cần sao chép. Nếu giá trị không tồn tại, thao tác sẽ không thành công.

Ví dụ

aliasInWindow('foo.bar', 'baz.qux')

Các quyền liên quan

access_globals là bắt buộc đối với cả toPath và fromPath; toPath yêu cầu quyền ghi, fromPath yêu cầu quyền đọc.

`callInWindow`

Cho phép bạn gọi các hàm từ một đường dẫn ngoài đối tượng window, theo cách do chính sách kiểm soát. Gọi hàm tại đường dẫn đã cho trong window bằng các đối số đã cho và trả về giá trị. Nếu kiểu trả về không thể được ánh xạ trực tiếp đến một kiểu được hỗ trợ trong JavaScript có hộp cát, thì undefined sẽ được trả về. Tám loại được hỗ trợ trong JavaScript có hộp cát là null, undefined, boolean, number, string, Array, Object và function. Nếu đường dẫn đã cho không tồn tại hoặc không tham chiếu đến một hàm, thì undefined sẽ được trả về.

Cú pháp

callInWindow(pathToFunction, argument [, argument2,... argumentN])

Tham số

Thông số	Loại	Mô tả
`pathToFunction`	string	Đường dẫn được phân tách bằng dấu chấm đến hàm trong `window` để gọi.
`args`	*	Đối số sẽ được truyền vào hàm.

Các quyền liên quan

access_globals khi đã bật quyền execute.

`callLater`

Lên lịch gọi một hàm để thực hiện không đồng bộ. Hàm này sẽ được gọi sau khi mã hiện tại trả về. Điều này tương đương với setTimeout(<function>, 0).

Cú pháp

callLater(function)

Tham số

Thông số	Loại	Mô tả
`function`	hàm	Hàm cần gọi.

`copyFromDataLayer`

Trả về giá trị hiện được chỉ định cho khoá đã cho trong lớp dữ liệu: Giá trị tìm thấy tại khoá đã cho nếu đó là kiểu nguyên thuỷ, hàm hoặc đối tượng theo nghĩa đen, hoặc undefined nếu không.

Cú pháp

copyFromDataLayer(key[, dataLayerVersion])

Tham số

Thông số	Loại	Mô tả
`key`	string	Khoá ở định dạng "a.b.c".
`dataLayerVersion`	number	Phiên bản lớp dữ liệu (không bắt buộc). Giá trị mặc định là 2. Bạn không nên sử dụng giá trị 1.

Các quyền liên quan

read_data_layer

`copyFromWindow`

Sao chép một biến từ đối tượng window. Nếu giá trị trong window không thể được ánh xạ trực tiếp đến một loại được hỗ trợ trong JavaScript có hộp cát, thì undefined sẽ được trả về. 8 loại được hỗ trợ trong JavaScript có hộp cát là null, undefined, boolean, number, string, Array, Object và function. Trả về giá trị đã tìm nạp (và được chuyển đổi).

Cú pháp

copyFromWindow(key)

Tham số

Thông số	Loại	Mô tả
`key`	string	Khoá trong `window` để sao chép giá trị.

Các quyền liên quan

access_globals

`createArgumentsQueue`

Tạo một hàng đợi được điền sẵn các đối tượng đối số, để hỗ trợ các giải pháp thẻ yêu cầu hàng đợi này.

Tạo một hàm trong phạm vi toàn cục (tức là window), bằng cách sử dụng đối số fnKey (cùng ngữ nghĩa với createQueue). Sau khi hàm được tạo, API này sẽ tạo một mảng trong window (nếu mảng đó chưa tồn tại) bằng cách sử dụng đối số arrayKey.

Khi hàm được tạo trong fnKey được gọi, hàm này sẽ đẩy đối tượng đối số của hàm đó vào mảng được tạo trong arrayKey. Giá trị trả về của API là hàm được tạo trong fnKey.

Hàm này yêu cầu chế độ cài đặt đọc và ghi cho fnKey và arrayKey trên quyền access_globals.

Ví dụ:

const gtag = createArgumentsQueue('gtag', 'dataLayer');
gtag('set', {'currency': 'USD'});

Cú pháp

createArgumentsQueue(fnKey, arrayKey)

Tham số

Thông số	Loại	Mô tả
`fnKey`	string	Đường dẫn trong `window` nơi hàm được đặt, nếu đường dẫn đó chưa tồn tại. Đối số này hỗ trợ ký hiệu dấu chấm tiêu chuẩn. Nếu đường dẫn của khoá không tồn tại, thì một ngoại lệ sẽ được gửi. Tức là nếu `fnKey` là `'one.two'`, thì thao tác này sẽ gửi một ngoại lệ.
`arrayKey`	string	Đường dẫn trong `window` nơi mảng được đặt, nếu đường dẫn đó chưa tồn tại. Đối số này hỗ trợ ký hiệu dấu chấm tiêu chuẩn. Nếu đường dẫn của khoá không tồn tại, thì một ngoại lệ sẽ được gửi. Tức là nếu `arrayKey` là `'one.two'` và không có đối tượng chung nào có tên là `'one'`, thì đối tượng này sẽ tạo ra một ngoại lệ.

Các quyền liên quan

access_globals

`createQueue`

Tạo một mảng trong window (nếu chưa có) và trả về một hàm sẽ đẩy các giá trị vào mảng đó.

Hàm này yêu cầu chế độ cài đặt đọc và ghi cho arrayKey đối với quyền access_globals.

Ví dụ:

const dataLayerPush = createQueue('dataLayer');
dataLayerPush({'currency': 'USD'}, {'event': 'myConversion'});

Cú pháp

createQueue(arrayKey)

Tham số

Thông số	Loại	Mô tả
`arrayKey`	string	Khoá trong `window` nơi mảng được đặt, nếu khoá đó chưa tồn tại. Đối số này hỗ trợ ký hiệu dấu chấm tiêu chuẩn. Nếu đường dẫn của khoá không tồn tại, thì một ngoại lệ sẽ được gửi. Ví dụ: nếu `arrayKey` là `'one.two'` và không có đối tượng chung nào có tên là `'one'`, thì thao tác này sẽ tạo ra một ngoại lệ.

Các quyền liên quan

access_globals

`decodeUri`

Giải mã mọi ký tự được mã hoá trong URI đã cho. Trả về một string biểu thị URI đã giải mã. Trả về undefined khi được cung cấp dữ liệu đầu vào không hợp lệ.

Ví dụ:

const decode = require('decodeUri');

const decodedUrl = decode(data.encodedUrl);
if (decodedUrl) {
  // ...
}

Cú pháp

decodeUri(encoded_uri)

Tham số

Thông số	Loại	Mô tả
`encoded_uri`	string	Một URI đã được mã hoá bằng `encodeUri()` hoặc bằng các phương tiện khác.

Các quyền liên quan

Không có.

`decodeUriComponent`

Giải mã mọi ký tự được mã hoá trong thành phần URI được cung cấp. Trả về một string biểu thị thành phần URI đã giải mã. Trả về undefined khi được cung cấp dữ liệu đầu vào không hợp lệ.

Ví dụ:

const decode = require('decodeUriComponent');

const decodedUrl = decode(data.encodedUrl);
if (decodedUrl) {
  // ...
}

Cú pháp

decodeUriComponent(encoded_uri_component)

Tham số

Thông số	Loại	Mô tả
`encoded_uri_component`	string	Một thành phần URI đã được mã hoá bằng `encodeUriComponent()` hoặc bằng các phương tiện khác.

Các quyền liên quan

Không có.

`encodeUri`

Trả về một Giá trị nhận dạng tài nguyên đồng nhất (URI) được mã hoá bằng cách thoát các ký tự đặc biệt. Trả về một string biểu thị chuỗi được cung cấp được mã hoá dưới dạng một URI. Trả về undefined khi được cung cấp dữ liệu đầu vào không hợp lệ (một thành phần thay thế đơn lẻ).

Ví dụ:

sendPixel('https://www.example.com/' + encodeUri(pathInput));

Cú pháp

encodeUri(uri)

Tham số

Thông số	Loại	Mô tả
`uri`	string	Một URI hoàn chỉnh.

Các quyền liên quan

Không có.

`encodeUriComponent`

Ví dụ:

sendPixel('https://www.example.com/?' + encodeUriComponent(queryInput));

Cú pháp

encodeUriComponent(str)

Tham số

Thông số	Loại	Mô tả
`str`	string	Một thành phần của URI.

Các quyền liên quan

Không có.

`fromBase64`

API fromBase64 cho phép bạn giải mã các chuỗi từ biểu thị base64 của chúng. Trả về undefined khi được cung cấp thông tin đầu vào không hợp lệ.

Cú pháp

fromBase64(base64EncodedString)

Tham số

Thông số	Loại	Mô tả
`base64EncodedString`	string	Chuỗi được mã hoá Base64.

Ví dụ

const fromBase64 = require('fromBase64');

const greeting = fromBase64('aGVsbG8=');
if (greeting === 'hello') {
  // ...
}

Các quyền liên quan

Không có

`generateRandom`

Trả về một số (số nguyên) ngẫu nhiên trong dải ô đã cho.

Cú pháp

generateRandom(min, max)

Tham số

Thông số	Loại	Mô tả
`min`	number	Giá trị tiềm năng tối thiểu của số nguyên được trả về.
`max`	number	Giá trị tiềm năng tối đa của số nguyên được trả về.

Các quyền liên quan

Không có.

`getContainerVersion`

Trả về một đối tượng chứa dữ liệu về vùng chứa hiện tại. Đối tượng được trả về có các trường sau:

{
  containerId: string,
  debugMode: boolean,
  environmentName: string,
  environmentMode: boolean,
  previewMode: boolean,
  version: string,
}

Ví dụ

const getContainerVersion = require('getContainerVersion');
const sendPixel = require('sendPixel');

if (query('read_container_data')) {
  const cv = getContainerVersion();

  const pixelUrl = 'https://pixel.com/' +
    '?version=' + cv.version +
    '&envName=' + cv.environmentName +
    '&ctid=' + cv.containerId +
    '&debugMode=' + cv.debugMode +
    '&previewMode=' + cv.previewMode;
  if (query('send_pixel', pixelUrl)) {
    sendPixel(pixelUrl);
  }
}

Cú pháp

getContainerVersion();

Các quyền liên quan

read_container_data

`getCookieValues`

Trả về giá trị của tất cả cookie có tên đã cho.

Cú pháp

getCookieValues(name[, decode])

Tham số

Thông số	Loại	Mô tả
`name`	string	Tên của cookie.
`decode`	boolean	Kiểm soát việc các giá trị cookie có được giải mã bằng `decodeURIComponent()` của JavaScript hay không. Giá trị mặc định là `true`.

Các quyền liên quan

get_cookies

`getQueryParameters`

Trả về tham số đầu tiên hoặc tất cả tham số cho queryKey của URL hiện tại. Trả về giá trị đầu tiên từ queryKey hoặc một mảng giá trị từ queryKey.

Cú pháp

getQueryParameters(queryKey[, retrieveAll])

Tham số

Thông số	Loại	Mô tả
`queryKey`	string	Khoá để đọc từ các tham số truy vấn.
`retrieveAll`	boolean	Có truy xuất tất cả các giá trị hay không.

Ví dụ: nếu URL hiện tại là https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo, thì:

getQueryParameters('var') == 'foo'
getQueryParameters('var', false) == 'foo'
getQueryParameters('var', null) == 'foo'
getQueryParameters('var', true) == ['foo', 'foo2', 'foo']

Các quyền liên quan

get_url phải cho phép thành phần query và phải chỉ định queryKey trong các khoá truy vấn được phép (hoặc cho phép mọi khoá truy vấn).

`getReferrerQueryParameters`

API getReferrerQueryParameters hoạt động giống như getQueryParameters, ngoại trừ việc API này hoạt động trên giá trị liên kết giới thiệu thay vì URL hiện tại. Trả về tham số đầu tiên hoặc tất cả các tham số cho queryKey của đơn vị giới thiệu nhất định. Trả về giá trị đầu tiên từ queryKey hoặc một mảng giá trị từ queryKey.

Cú pháp

getReferrerQueryParameters(queryKey[, retrieveAll])

Tham số

Thông số	Loại	Mô tả
`queryKey`	string	Khoá để đọc từ các tham số truy vấn.
`retrieveAll`	boolean	Có truy xuất tất cả các giá trị hay không.

Ví dụ: nếu URL của đơn vị giới thiệu là https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo, thì:

getReferrerQueryParameters('var') == 'foo'
getReferrerQueryParameters('var', false) == 'foo'
getReferrerQueryParameters('var', null) == 'foo'
getReferrerQueryParameters('var', true) == ['foo', 'foo2', 'foo']

Các quyền liên quan

get_referrer phải cho phép thành phần query và phải chỉ định queryKey trong các khoá truy vấn được phép (hoặc cho phép mọi khoá truy vấn).

`getReferrerUrl`

Với một loại thành phần, API sẽ đọc đối tượng tài liệu cho giá trị liên kết giới thiệu và trả về một chuỗi đại diện cho một phần của giá trị liên kết giới thiệu. Nếu bạn không chỉ định thành phần nào, thì URL đầy đủ của đường liên kết giới thiệu sẽ được trả về.

Cú pháp

getReferrerUrl([component])

Tham số

Thông số	Loại	Mô tả
`component`	string	Thành phần cần trả về từ URL. Có thể là một trong những trạng thái sau đây: `protocol`, `host`, `port`, `path`, `query`, `extension`. Nếu `component` là `undefined`, `null` hoặc không khớp với một trong các thành phần này, thì toàn bộ URL sẽ được trả về.

Các quyền liên quan

get_referrer phải cho phép thành phần query và phải chỉ định queryKey trong các khoá truy vấn được phép (hoặc cho phép mọi khoá truy vấn).

`getTimestamp`

Không dùng nữa. Ưu tiên getTimestampMillis.

Trả về một số biểu thị thời gian hiện tại tính bằng mili giây kể từ thời gian bắt đầu của hệ thống Unix, do Date.now() trả về.

Cú pháp

getTimestamp();

Các quyền liên quan

Không có.

`getTimestampMillis`

Trả về một số biểu thị thời gian hiện tại tính bằng mili giây kể từ thời gian bắt đầu của hệ thống Unix, do Date.now() trả về.

Cú pháp

getTimestampMillis();

Các quyền liên quan

Không có.

`getType`

Trả về một chuỗi mô tả loại của giá trị đã cho. Không giống như typeof, getType phân biệt giữa array và object.

Cú pháp

getType(data.someField)

Lưu ý

Bảng sau đây liệt kê các chuỗi được trả về cho từng giá trị đầu vào.

Giá trị cột nhập	Kết quả
`undefined`	'undefined'
`null`	"null"
`true`	"boolean"
`12`	'number'
`'string'`	'string'
`{ a: 3 }`	'object'
`[ 1, 3 ]`	'array'
`(x) => x + 1`	'function'

Các quyền liên quan

Không có.

`getUrl`

Trả về một chuỗi biểu thị toàn bộ hoặc một phần của URL hiện tại, cho trước một loại thành phần và một số tham số cấu hình.

Cú pháp

getUrl(component)

Tham số

Thông số	Loại	Mô tả
`component`	string	Thành phần cần trả về từ URL. Phải là một trong các giá trị: `protocol`, `host`, `port`, `path`, `query`, `extension`, `fragment`. Nếu thành phần là `undefined`, `null` hoặc không khớp với một trong các thành phần này, thì toàn bộ giá trị `href` sẽ được trả về.

Các quyền liên quan

get_url

`gtagSet`

Đẩy một lệnh đặt gtag vào lớp dữ liệu để được xử lý sớm nhất có thể sau khi sự kiện hiện tại và mọi thẻ mà sự kiện đó đã kích hoạt hoàn tất quá trình xử lý (hoặc đạt đến thời gian chờ xử lý thẻ). Bản cập nhật này chắc chắn sẽ được xử lý trong vùng chứa này trước mọi mục trong hàng đợi của hàng đợi lớp dữ liệu.

Ví dụ: nếu được gọi bằng một thẻ kích hoạt trên Hoạt động tiến hành lấy sự đồng ý, thì nội dung cập nhật sẽ được áp dụng trước khi sự kiện Khởi chạy được xử lý. Ví dụ: ads_data_redaction được đặt thành true hoặc false hoặc url_passthrough được đặt thành true hoặc false.

Ví dụ:

const gtagSet = require('gtagSet');

gtagSet({
  'ads_data_redaction': true,
  'url_passthrough': true,
});

Cú pháp

gtagSet(object)

Tham số

Thông số	Loại	Mô tả
`Object`	object	Một đối tượng cập nhật trạng thái chung cho các thuộc tính chứa đối tượng đó.

Các quyền liên quan

write_data_layer kiểm tra quyền ghi vào dataLayer cho tất cả các khoá được chỉ định. Nếu đầu vào cho gtagSet là một đối tượng thuần tuý, thì API sẽ kiểm tra quyền ghi đối với tất cả các khoá được làm phẳng bên trong đối tượng đó, ví dụ: đối với gtagSet({foo: {bar: 'baz'}}), API sẽ kiểm tra quyền ghi đối với foo.bar.

Nếu đầu vào cho gtagSet là một khoá và một số giá trị đối tượng không phải văn bản thuần tuý, thì API sẽ kiểm tra quyền ghi vào khoá đó, ví dụ: đối với gtagSet('abc', true) , API sẽ kiểm tra quyền ghi vào 'abc'.

Xin lưu ý rằng nếu có một chu kỳ trong đối tượng đầu vào, thì chỉ các khoá trước khi đạt đến cùng một đối tượng sẽ được kiểm tra.

`injectHiddenIframe`

Thêm một iframe ẩn vào trang.

Các lệnh gọi lại được cung cấp dưới dạng các thực thể hàm và được bao bọc trong các hàm JavaScript gọi qua các lệnh gọi lại đó.

Cú pháp

injectHiddenIframe(url, onSuccess)

Tham số

Thông số	Loại	Mô tả
`url`	string	URL sẽ được dùng làm giá trị của thuộc tính `src` của iframe.
`onSuccess`	hàm	Được gọi khi khung tải thành công.

Các quyền liên quan

inject_hidden_iframe

`injectScript`

Thêm một thẻ tập lệnh vào trang để tải URL đã cho một cách không đồng bộ. Các lệnh gọi lại được cung cấp dưới dạng các phiên bản hàm và được bao bọc trong các hàm JavaScript gọi qua các phiên bản đó.

Cú pháp

injectScript(url, onSuccess, onFailure[, cacheToken])

Tham số

Thông số	Loại	Mô tả
`url`	string	Địa chỉ của tập lệnh cần được chèn.
`onSuccess`	hàm	Được gọi khi tập lệnh tải thành công.
`onFailure`	hàm	Được gọi khi tập lệnh không tải được.
`cacheToken`	string	Chuỗi không bắt buộc dùng để cho biết URL đã cho cần được lưu vào bộ nhớ đệm. Nếu bạn chỉ định giá trị này, thì chỉ một phần tử tập lệnh sẽ được tạo để yêu cầu JavaScript. Mọi nỗ lực tải thêm sẽ dẫn đến việc các phương thức `onSuccess` và `onFailure` đã cho được xếp hàng cho đến khi tập lệnh tải xong.

Các quyền liên quan

inject_script

`isConsentGranted`

Trả về true nếu bạn đã cấp loại đồng ý được chỉ định.

Sự đồng ý cho một loại đồng ý cụ thể được coi là đã được cấp nếu loại đồng ý đó được đặt thành "đã cấp" hoặc chưa được đặt. Nếu bạn đặt loại đồng ý thành bất kỳ giá trị nào khác, thì loại đồng ý đó sẽ được coi là không được cấp.

Giao diện người dùng Trình quản lý thẻ cho chế độ cài đặt thẻ sẽ cung cấp một lựa chọn để luôn kích hoạt. Nếu một thẻ có chế độ luôn kích hoạt sử dụng API này, thì sự đồng ý sẽ được coi là đã cấp và true sẽ được trả về, bất kể trạng thái đồng ý thực tế.

Ví dụ:

const isConsentGranted = require('isConsentGranted');

if (isConsentGranted('ad_storage')) {
  sendFullPixel();
} else {
  sendPixelWithoutCookies();
}

Cú pháp

isConsentGranted(consentType)

Tham số

Thông số	Loại	Mô tả
`consentType`	string	Loại đồng ý cần kiểm tra trạng thái.

Các quyền liên quan

Quyền access_consent có quyền đọc đối với loại sự đồng ý.

`JSON`

Trả về một đối tượng cung cấp các hàm JSON.

Hàm parse() phân tích cú pháp một chuỗi JSON để tạo giá trị hoặc đối tượng được mô tả bằng chuỗi đó. Nếu không phân tích cú pháp được giá trị (ví dụ: JSON bị lỗi), hàm sẽ trả về undefined. Nếu giá trị đầu vào không phải là một chuỗi, thì đầu vào sẽ được chuyển đổi thành một chuỗi.

Hàm stringify() chuyển đổi dữ liệu đầu vào thành một chuỗi JSON. Nếu không phân tích cú pháp được giá trị (ví dụ: đối tượng có một chu kỳ), phương thức sẽ trả về undefined.

Cú pháp

JSON.parse(stringInput)
JSON.stringify(value);

Tham số

JSON.parse

Thông số	Loại	Mô tả
stringInput	any	Giá trị cần chuyển đổi. Nếu giá trị không phải là một chuỗi, thì đầu vào sẽ được chuyển đổi thành một chuỗi.

JSON.stringify

Thông số	Loại	Mô tả
value	any	Giá trị cần chuyển đổi.

Ví dụ

const JSON = require('JSON');

// The JSON input string is converted to an object.
const object = JSON.parse('{"foo":"bar"}');

// The input object is converted to a JSON string.
const str = JSON.stringify({foo: 'bar'});

`localStorage`

Trả về một đối tượng có các phương thức để truy cập vào bộ nhớ cục bộ.

Cú pháp

const localStorage = require('localStorage');

// Requires read access for the key. Returns null if the key does not exist.
localStorage.getItem(key);

// Requires write access for the key. Returns true if successful.
localStorage.setItem(key, value);

// Requires write access for the key.
localStorage.removeItem(key);

Các quyền liên quan

access_local_storage

Ví dụ

const localStorage = require('localStorage');
if (localStorage) {
  const value = localStorage.getItem('my_key');
  if (value) {
    const success = localStorage.setItem('my_key', 'new_value');
    if (success) {
      localStorage.removeItem('my_key');
    }
  }
}

`logToConsole`

Ghi nhật ký các đối số vào bảng điều khiển trình duyệt.

Cú pháp

logToConsole(obj1 [, obj2,... objN])

Tham số

Thông số	Loại	Mô tả
`obj1 [, obj2,... objN]`	any	Đối số

Các quyền liên quan

logging

`makeInteger`

Chuyển đổi giá trị đã cho thành number (số nguyên).

Cú pháp

makeInteger(value)

Tham số

Thông số	Loại	Mô tả
`value`	any	Giá trị cần chuyển đổi.

Các quyền liên quan

Không có.

`makeNumber`

Chuyển đổi giá trị đã cho thành số.

Cú pháp

makeNumber(value)

Tham số

Thông số	Loại	Mô tả
`value`	any	Giá trị cần chuyển đổi.

Các quyền liên quan

Không có.

`makeString`

Trả về giá trị đã cho dưới dạng chuỗi.

Cú pháp

makeString(value)

Tham số

Thông số	Loại	Mô tả
`value`	any	Giá trị cần chuyển đổi.

Các quyền liên quan

Không có.

`makeTableMap`

Chuyển đổi một đối tượng bảng đơn giản có hai cột thành một Map. Thao tác này được dùng để thay đổi một trường mẫu SIMPLE_TABLE có 2 cột thành một định dạng dễ quản lý hơn.

Ví dụ: hàm này có thể chuyển đổi một đối tượng bảng:

[
  {'key': 'k1', 'value': 'v1'},
  {'key': 'k2', 'value': 'v2'}
]

vào Bản đồ:

{
  'k1': 'v1',
  'k2': 'v2'
}

Trả về một Đối tượng: Map đã chuyển đổi nếu các cặp khoá-giá trị đã được thêm vào đối tượng đó, hoặc null nếu không.

Cú pháp

makeTableMap(tableObj, keyColumnName, valueColumnName)

Tham số

Thông số	Loại	Mô tả
`tableObj`	List (Danh sách)	Đối tượng bảng cần chuyển đổi. Đây là danh sách các bản đồ, trong đó mỗi `Map` đại diện cho một hàng trong bảng. Mỗi tên thuộc tính trong một đối tượng hàng là tên cột và giá trị thuộc tính là giá trị cột trong hàng.
`keyColumnName`	string	Tên của cột có các giá trị sẽ trở thành khoá trong `Map` đã chuyển đổi.
`valueColumnName`	string	Tên của cột có các giá trị sẽ trở thành giá trị trong `Map` đã chuyển đổi.

Các quyền liên quan

Không có.

`Math`

Một đối tượng cung cấp các hàm Math.

Cú pháp

const Math = require('Math');

// Retrieve the absolute value.
const absolute = Math.abs(-3);

// Round the input down to the nearest integer.
const roundedDown = Math.floor(3.6);

// Round the input up to the nearest integer.
const roundedUp = Math.ceil(2.2);

// Round the input to the nearest integer.
const rounded = Math.round(3.1);

// Return the largest argument.
const biggest = Math.max(1, 3);

// Return the smallest argument.
const smallest = Math.min(3, 5);

// Return the first argument raised to the power of the second argument.
const powerful = Math.pow(3, 1);

// Return the square root of the argument.
const unsquared = Math.sqrt(9);

Tham số

Các tham số của hàm toán học được chuyển đổi thành số.

Các quyền liên quan

Không có.

`Object`

Trả về một đối tượng cung cấp các phương thức Object.

Phương thức keys() cung cấp hành vi Object.keys() của Thư viện chuẩn. Hàm này trả về một mảng gồm các tên thuộc tính có thể liệt kê của một đối tượng nhất định theo cùng thứ tự mà vòng lặp for...in... sẽ trả về. Nếu giá trị đầu vào không phải là một đối tượng, thì giá trị đó sẽ được chuyển đổi thành một đối tượng.

Phương thức values() cung cấp hành vi Object.values() của Thư viện chuẩn. Hàm này trả về một mảng gồm các giá trị thuộc tính có thể liệt kê của một đối tượng nhất định theo cùng thứ tự mà vòng lặp for...in... sẽ trả về. Nếu giá trị đầu vào không phải là một đối tượng, thì giá trị đó sẽ bị ép buộc thành một đối tượng.

Phương thức entries() cung cấp hành vi Object.entries() của Thư viện chuẩn. Hàm này trả về một mảng gồm các cặp thuộc tính có thể liệt kê của một đối tượng nhất định theo cùng thứ tự mà vòng lặp for...in... sẽ trả về.[key, value] Nếu giá trị đầu vào không phải là một đối tượng, thì giá trị đó sẽ được chuyển đổi thành một đối tượng.

Phương thức freeze() cung cấp hành vi Object.freeze() của Thư viện chuẩn. Bạn không thể thay đổi đối tượng bị đóng băng nữa; việc đóng băng đối tượng sẽ ngăn các thuộc tính mới được thêm vào, các thuộc tính hiện có bị xoá và các giá trị của các thuộc tính hiện có bị thay đổi. freeze() trả về chính đối tượng đã được truyền vào. Đối số nguyên thuỷ hoặc đối số rỗng sẽ được coi như thể đó là một đối tượng cố định và sẽ được trả về.

Phương thức delete() cung cấp hành vi toán tử xoá của Thư viện chuẩn. Thao tác này sẽ xoá khoá đã cho khỏi đối tượng, trừ phi đối tượng đó bị đóng băng. Giống như toán tử xoá Thư viện chuẩn, toán tử này trả về true nếu giá trị đầu vào đầu tiên (objectInput) là một đối tượng không bị đóng băng ngay cả khi giá trị đầu vào thứ hai (keyToDelete) chỉ định một khoá không tồn tại. Hàm này trả về false trong tất cả các trường hợp khác. Tuy nhiên, toán tử này khác với toán tử xoá Thư viện chuẩn ở những điểm sau:

keyToDelete không thể là một chuỗi phân cách bằng dấu chấm chỉ định một khoá lồng nhau.
Bạn không thể dùng delete() để xoá các phần tử khỏi một mảng.
Bạn không thể dùng delete() để xoá bất kỳ thuộc tính nào khỏi phạm vi chung.

Cú pháp

Object.keys(objectInput)
Object.values(objectInput)
Object.entries(objectInput)
Object.freeze(objectInput)
Object.delete(objectInput, keyToDelete)

Tham số

Object.keys

Thông số	Loại	Mô tả
objectInput	any	Đối tượng có các khoá cần liệt kê. Nếu đầu vào không phải là một đối tượng, thì đầu vào đó sẽ bị ép buộc thành một đối tượng.

Object.values

Thông số	Loại	Mô tả
objectInput	any	Đối tượng có các giá trị cần liệt kê. Nếu đầu vào không phải là một đối tượng, thì đầu vào đó sẽ được chuyển đổi thành một đối tượng.

Object.entries

Thông số	Loại	Mô tả
objectInput	any	Đối tượng có các cặp khoá/giá trị cần liệt kê. Nếu đầu vào không phải là một đối tượng, thì đầu vào đó sẽ bị ép buộc thành một đối tượng.

Object.freeze

Thông số	Loại	Mô tả
objectInput	any	Đối tượng cần cố định. Nếu đầu vào không phải là một đối tượng, thì đầu vào đó sẽ được coi là một đối tượng cố định.

Object.delete

Thông số	Loại	Mô tả
objectInput	any	Đối tượng có khoá cần xoá.
keyToDelete	string	Khoá cấp cao nhất cần xoá.

Ví dụ

const Object = require('Object');

// The keys of an object are enumerated in an array.
const keys = Object.keys({foo: 'bar'});

// The values of an object are enumerated in an array.
const values = Object.values({foo: 'bar'});

// The key/value pairs of an object are enumerated in an array.
const entries = Object.entries({foo: 'bar'});

// The input object is frozen.
const frozen = Object.freeze({foo: 'bar'});

// The key is removed from the input object.
const obj1 = {deleteme: 'value'};
Object.delete(obj1, 'deleteme');
// Only a top-level key can be specified as the key to delete.
const obj2 = {nested: {key: 'value'}};
Object.delete(obj2, 'nested.key'); // This has no effect.
Object.delete(obj2.nested, 'key'); // This deletes the nested key.

`parseUrl`

Trả về một đối tượng chứa tất cả các thành phần của một URL nhất định, tương tự như đối tượng URL.

API này sẽ trả về undefined cho mọi URL có định dạng không hợp lệ. Đối với các URL có định dạng phù hợp, những trường không có trong chuỗi URL sẽ có giá trị là một chuỗi trống hoặc trong trường hợp searchParams, một đối tượng trống.

Đối tượng được trả về sẽ có các trường sau:

{
  href: string,
  origin: string,
  protocol: string,
  username: string,
  password: string,
  host: string,
  hostname: string,
  port: string,
  pathname: string,
  search: string,
  searchParams: Object<string, (string|Array)>,
  hash: string,
}

Ví dụ

const parseUrl = require('parseUrl');

const urlObject = parseUrl('https://abc:xyz@example.com:8080/foo?param=val%2Cue#bar');

Cú pháp

parseUrl(url);

Tham số

Thông số	Loại	Mô tả
`url`	string	URL đầy đủ sẽ được phân tích cú pháp.

Các quyền liên quan

Không có.

`queryPermission`

Truy vấn các quyền được phép và bị hạn chế. Trả về một boolean: true nếu quyền được cấp, false nếu không.

Cú pháp

queryPermission(permission, functionArgs*)

Tham số

Thông số	Loại	Mô tả
`permission`	string	Tên của quyền.
`functionArgs`	any	Đối số hàm sẽ khác nhau tuỳ theo quyền được truy vấn. Xem phần Đối số của hàm bên dưới.

Đối số của hàm

sendPixel, injectScript, injectHiddenIframe: Tham số thứ hai phải là một chuỗi URL.

writeGlobals, readGlobals: Tham số thứ hai phải là khoá đang được ghi hoặc đọc.

readUrl: Bạn không cần thêm đối số nào để truy vấn xem toàn bộ URL có thể đọc được hay không. Để truy vấn xem một thành phần nhất định có thể đọc được hay không, hãy truyền tên thành phần đó làm đối số thứ hai:

if (queryPermission('readUrl','port')) {
  // read the port
}

Để kiểm tra xem một khoá truy vấn cụ thể có thể đọc được hay không, hãy truyền khoá truy vấn làm tham số thứ ba:

if (queryPermission('readUrl','query','key')) {
  getUrlComponent(...);
}

Các quyền liên quan

Không có.

`readAnalyticsStorage`

Truy xuất dữ liệu được lưu trữ cho hoạt động phân tích và trả về một đối tượng có client_id và sessions.

client_id: Một chuỗi đại diện cho mã ứng dụng khách dùng cho hoạt động phân tích.
sessions: Một mảng các đối tượng chứa thông tin về các phiên hiện tại. Mỗi đối tượng bao gồm:
- measurement_id: Một chuỗi đại diện cho mã nhận dạng đo lường của Đích đến Analytics.
- session_id: Một chuỗi biểu thị dấu thời gian xác định phiên hiện tại.
- session_number: Một số đại diện cho số lượng phiên mà một người dùng đã bắt đầu tính đến phiên hiện tại.

Cú pháp

const readAnalyticsStorage = require('readAnalyticsStorage');

const cookieOptions = {
  cookie_prefix: "xyz",
  cookie_domain: "google.com",
  cookie_path: "/",
};

readAnalyticsStorage(cookieOptions);

Tham số

Thông số	Loại	Mô tả
`cookieOptions`	object	Không bắt buộc Các lựa chọn để đọc cookie bằng `cookie_prefix`, `cookie_domain` hoặc `cookie_path` cụ thể.

Các quyền liên quan

read_analytics_storage

Ví dụ

const readAnalyticsStorage = require('readAnalyticsStorage');

const analyticsStorageData = readAnalyticsStorage();

sendOfflineEvent(analyticsStorageData.client_id, "tutorial_begin");

`readCharacterSet`

Trả về giá trị của document.characterSet.

Cú pháp

readCharacterSet()

Tham số

Không có.

Các quyền liên quan

read_character_set

`readTitle`

Trả về giá trị của document.title.

Cú pháp

readTitle()

Tham số

Không có.

Các quyền liên quan

read_title

`require`

Nhập một hàm tích hợp sẵn theo tên. Trả về một hàm hoặc một đối tượng có thể được gọi từ chương trình của bạn. Trả về undefined khi trình duyệt không hỗ trợ hàm tích hợp.

Cú pháp

require(name)

Tham số

Thông số	Loại	Mô tả
`name`	string	Tên của hàm cần nhập.

Ví dụ

const getUrl = require('getUrl');
const url = getUrl();

Các quyền liên quan

Không có.

`sendPixel`

Gửi yêu cầu GET đến một điểm cuối URL đã chỉ định.

Cú pháp

sendPixel(url, onSuccess, onFailure)

Tham số

Thông số	Loại	Mô tả
`url`	string	Nơi gửi pixel.
`onSuccess`	hàm	Được gọi khi pixel tải thành công. Lưu ý: ngay cả khi yêu cầu gửi thành công, các trình duyệt có thể yêu cầu phản hồi hình ảnh hợp lệ để chạy onSuccess.
`onFailure`	hàm	Được gọi khi pixel không tải được. Lưu ý: ngay cả khi yêu cầu gửi thành công, onFailure vẫn có thể chạy nếu máy chủ không trả về phản hồi hình ảnh hợp lệ.

Các quyền liên quan

send_pixel

`setCookie`

Đặt hoặc xoá cookie có tên, giá trị và lựa chọn được chỉ định.

Cú pháp

setCookie(name, value[, options, encode])

Tham số

Thông số	Loại	Mô tả
`name`	string	Tên của cookie.
`value`	string	Giá trị của cookie.
`options`	object	Chỉ định các thuộc tính Miền, Đường dẫn, Hết hạn, Tuổi tối đa, Bảo mật và SameSite. (Xem phần Lựa chọn bên dưới.)
`encode`	boolean	Kiểm soát việc giá trị cookie có được mã hoá bằng `encodeURIComponent()` của JavaScript hay không. Mặc định là `true`.

Tuỳ chọn

Miền: do thuộc tính options['domain'] đặt, nếu có. Đặt giá trị này thành 'auto' để cố gắng ghi cookie bằng miền rộng nhất có thể, dựa trên vị trí của tài liệu. Nếu không thành công, hệ thống sẽ thử các miền con hẹp hơn liên tiếp. Nếu tất cả những cách đó đều không thành công, thì nó sẽ cố gắng ghi cookie mà không có miền. Nếu bạn không đặt giá trị, thì thao tác này sẽ cố gắng ghi cookie mà không chỉ định miền. Lưu ý: khi một cookie không có miền được chỉ định được ghi vào document.cookie, tác nhân người dùng sẽ mặc định miền của cookie thành máy chủ lưu trữ của vị trí tài liệu hiện tại.
Đường dẫn: do options['path'] đặt, nếu có. Khi một cookie không có đường dẫn được chỉ định được ghi vào document.cookie, tác nhân người dùng sẽ đặt đường dẫn của cookie thành đường dẫn của vị trí tài liệu hiện tại theo mặc định.
Max-Age: do options['max-age'] đặt, nếu có.
Hết hạn: do options['expires'] đặt, nếu có. Nếu có, đây phải là một chuỗi ngày được định dạng theo giờ UTC. Bạn có thể dùng Date.toUTCString() để định dạng Date cho tham số này.
Bảo mật: do options['secure'] đặt, nếu có.
SameSite: do options['samesite'] đặt, nếu có.

Các quyền liên quan

set_cookies

`setDefaultConsentState`

Đẩy một bản cập nhật mặc định về sự đồng ý vào lớp dữ liệu để được xử lý sớm nhất có thể sau khi sự kiện hiện tại và mọi thẻ mà sự kiện đó đã kích hoạt hoàn tất quá trình xử lý (hoặc đạt đến thời gian chờ xử lý thẻ). Bản cập nhật này chắc chắn sẽ được xử lý trong vùng chứa này trước mọi mục trong hàng đợi ở lớp dữ liệu. Tìm hiểu thêm về sự đồng ý.

Ví dụ:

const setDefaultConsentState = require('setDefaultConsentState');

setDefaultConsentState({
  'ad_storage': 'denied',
  'analytics_storage': 'granted',
  'third_party_storage': 'denied',
  'region': ['US-CA'],
  'wait_for_update': 500
});

Cú pháp

setDefaultConsentState(consentSettings)

Tham số

Thông số	Loại	Mô tả
`consentSettings`	object	Một đối tượng xác định trạng thái mặc định cho các loại đồng ý được chỉ định.

Đối tượng consentSettings là một mối liên kết của các chuỗi loại đồng ý tuỳ ý với một trong các chuỗi 'granted' hoặc 'denied'. Thuộc tính này hỗ trợ các giá trị sau:

Tên khóa	Loại	Mô tả
`consentType`	string	Bạn có thể đặt giá trị cho từng loại sự đồng ý thành "granted" hoặc "denied". Mọi giá trị khác "granted" sẽ được coi là "denied". Việc đặt giá trị thành "undefined" sẽ không ảnh hưởng đến giá trị trước đó.
`region`	Mảng	Một mảng mã khu vực không bắt buộc, chỉ định khu vực mà chế độ cài đặt về trạng thái đồng ý áp dụng. Mã khu vực được biểu thị bằng quốc gia và/hoặc tiểu bang ở định dạng ISO 3166-2.
`wait_for_update`	number	Chỉ định giá trị mili giây để kiểm soát thời gian chờ trước khi dữ liệu được gửi. Được dùng với các công cụ có sự đồng ý tải không đồng bộ.

Các quyền liên quan

access_consent có quyền ghi đối với tất cả các loại đồng ý trong đối tượng consentSettings.

`setInWindow`

Đặt giá trị đã cho trong window tại khoá đã cho. Theo mặc định, phương thức này sẽ không đặt giá trị trong window nếu đã có giá trị. Đặt overrideExisting thành true để đặt giá trị trong window bất kể có giá trị hiện tại hay không. Trả về một boolean: true nếu giá trị được đặt thành công và false nếu không.

Cú pháp

setInWindow(key, value, overrideExisting)

Tham số

Thông số	Loại	Mô tả
`key`	string	Khoá trong `window` để đặt giá trị tại đó.
`value`	*	Giá trị cần đặt trong `window`.
`overrideExisting`	boolean	Cờ cho biết giá trị phải được đặt trong `window`, bất kể có giá trị ở đó hay không.

Các quyền liên quan

access_globals

`sha256`

Tính toán thông báo SHA-256 của dữ liệu đầu vào và gọi một lệnh gọi lại với thông báo được mã hoá theo chuẩn base64, trừ phi đối tượng options chỉ định một phương thức mã hoá đầu ra khác.

Ví dụ:

sha256('inputString', (digest) => {
  sendPixel('https://example.com/collect?id=' + digest);
  data.gtmOnSuccess();
}, data.gtmOnFailure);

sha256('inputString', (digest) => {
  sendPixel('https://example.com/collect?id=' + digest);
  data.gtmOnSuccess();
}, data.gtmOnFailure, {outputEncoding: 'hex'});

Cú pháp

sha256(input, onSuccess, onFailure = undefined, options = undefined)

Tham số

Thông số	Loại	Mô tả
`input`	string	Chuỗi cần tính hàm băm.
`onSuccess`	hàm	Được gọi bằng bản tóm tắt kết quả, được mã hoá bằng base64, trừ phi đối tượng `options` chỉ định một phương thức mã hoá đầu ra khác.
`onFailure`	hàm	Được gọi nếu xảy ra lỗi trong khi tính toán thông báo hoặc nếu trình duyệt không có hỗ trợ gốc cho sha256. Lệnh gọi lại được gọi bằng một đối tượng chứa tên của lỗi và thông báo.
`options`	object	Đối tượng Không bắt buộc để chỉ định phương thức mã hoá đầu ra. Nếu được chỉ định, đối tượng phải chứa khoá `outputEncoding` có giá trị là một trong các giá trị `base64` hoặc `hex`.

Các quyền liên quan

Không có.

`templateStorage`

Trả về một đối tượng có các phương thức để truy cập vào bộ nhớ mẫu. Bộ nhớ mẫu cho phép chia sẻ dữ liệu giữa các lần thực thi của một mẫu duy nhất. Dữ liệu được lưu trữ trong bộ nhớ mẫu sẽ tồn tại trong suốt thời gian tồn tại của trang.

Cú pháp

const templateStorage = require('templateStorage');

templateStorage.getItem(key);

templateStorage.setItem(key, value);

templateStorage.removeItem(key);

// Deletes all stored values for the template.
templateStorage.clear();

Các quyền liên quan

access_template_storage

Ví dụ

const templateStorage = require('templateStorage');
const sendPixel = require('sendPixel');

// Ensure sendPixel is called only once per page.
if (templateStorage.getItem('alreadyRan')) {
  data.gtmOnSuccess();
  return;
}

templateStorage.setItem('alreadyRan', true);

sendPixel(
  data.oncePerPagePixelUrl,
  data.gtmOnSuccess,
  () => {
    templateStorage.setItem('alreadyRan', false);
    data.gtmOnFailure();
  });

`toBase64`

API toBase64 cho phép bạn mã hoá một chuỗi thành một biểu thức base64.

Cú pháp

toBase64(input)

Tham số

Thông số	Loại	Mô tả
`input`	string	Chuỗi cần mã hoá.

Ví dụ

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

Các quyền liên quan

Không có

`updateConsentState`

Đẩy thông tin cập nhật về sự đồng ý vào lớp dữ liệu để được xử lý sớm nhất có thể sau khi sự kiện hiện tại và mọi thẻ mà sự kiện đó đã kích hoạt hoàn tất quá trình xử lý (hoặc đạt đến thời gian chờ xử lý thẻ). Bản cập nhật này chắc chắn sẽ được xử lý trong vùng chứa này trước mọi mục trong hàng đợi trong lớp dữ liệu. Tìm hiểu thêm về sự đồng ý.

Ví dụ:

const updateConsentState = require('updateConsentState');

updateConsentState({
  'ad_storage': 'granted',
  'analytics_storage': 'denied',
  'third_party_storage': 'granted',
});

Cú pháp

updateConsentState(consentSettings)

Tham số

Thông số	Loại	Mô tả
`consentSettings`	object	Một đối tượng cập nhật trạng thái cho các loại đồng ý được chỉ định.

Tên khóa	Loại	Mô tả
`consentType`	string	Bạn có thể đặt giá trị cho từng loại yêu cầu đồng ý thành "granted" hoặc "denied". Mọi giá trị không phải là "granted" sẽ được coi là "denied". Việc đặt giá trị thành "undefined" sẽ không ảnh hưởng đến giá trị trước đó của biến.

Các quyền liên quan

access_consent có quyền ghi đối với tất cả các loại đồng ý trong đối tượng consentSettings.

API kiểm thử

Các API này hoạt động với các thử nghiệm JavaScript trong hộp cát để tạo các thử nghiệm cho mẫu tuỳ chỉnh trong Trình quản lý thẻ của Google. Các API kiểm thử này không cần câu lệnh require(). Tìm hiểu thêm về các thử nghiệm mẫu tuỳ chỉnh.

`assertApi`

Trả về một đối tượng so khớp có thể dùng để đưa ra các khẳng định một cách trôi chảy về API đã cho.

Cú pháp

assertApi(apiName)

Tham số

Thông số	Loại	Mô tả
`apiName`	string	Tên của API cần kiểm tra; chuỗi giống như chuỗi được truyền đến `require()`.

Matchers

Subject.wasCalled()
Subject.wasNotCalled()
Subject.wasCalledWith(...expected)
Subject.wasNotCalledWith(...expected)

Ví dụ

assertApi('sendPixel').wasCalled();
assertApi('getUrl').wasNotCalled();
assertApi('makeNumber').wasCalledWith('8');
assertApi('setInWindow').wasNotCalledWith('myVar', 'theWrongValue');

`assertThat`

API assertThat được mô hình hoá theo thư viện [Truth] của Google. Hàm này trả về một đối tượng có thể dùng để đưa ra các khẳng định một cách trôi chảy về giá trị của một đối tượng. Lỗi xác nhận sẽ ngay lập tức dừng kiểm thử và đánh dấu là không thành công. Tuy nhiên, lỗi trong một kiểm thử sẽ không ảnh hưởng đến các trường hợp kiểm thử khác.

Cú pháp

assertThat(actual, opt_message)

Tham số

Thông số	Loại	Mô tả
`actual`	any	Giá trị cần dùng trong các quy trình kiểm tra linh hoạt.
`opt_message`	string	Thông báo không bắt buộc để in nếu xác nhận không thành công.

Matchers

Matcher	Mô tả
`isUndefined()`	Xác nhận rằng chủ đề là `undefined`.
`isDefined()`	Xác nhận rằng đối tượng không phải là `undefined`.
`isNull()`	Xác nhận rằng chủ đề là `null`.
`isNotNull()`	Xác nhận rằng đối tượng không phải là `null`.
`isFalse()`	Xác nhận rằng chủ đề là `false`.
`isTrue()`	Xác nhận rằng chủ đề là `true`.
`isFalsy()`	Xác nhận rằng chủ đề là sai. Các giá trị sai là `undefined`, `null`, `false`, `NaN`, 0 và "" (chuỗi trống).
`isTruthy()`	Xác nhận rằng chủ đề là đúng. Các giá trị sai là `undefined`, `null`, `false`, `NaN`, 0 và "" (chuỗi trống).
`isNaN()`	Xác nhận rằng chủ đề là giá trị NaN.
`isNotNaN()`	Xác nhận rằng đối tượng là bất kỳ giá trị nào ngoài NaN.
`isInfinity()`	Xác nhận rằng đối tượng là vô cực dương hoặc vô cực âm.
`isNotInfinity()`	Xác nhận rằng đối tượng là bất kỳ giá trị nào ngoài vô cực dương hoặc âm.
`isEqualTo(expected)`	Xác nhận rằng đối tượng bằng với giá trị đã cho. Đây là một phép so sánh giá trị chứ không phải phép so sánh tham chiếu. Nội dung của các đối tượng và mảng được so sánh một cách đệ quy.
`isNotEqualTo(expected)`	Xác nhận rằng đối tượng không bằng giá trị đã cho. Đây là một phép so sánh giá trị chứ không phải phép so sánh tham chiếu. Nội dung của các đối tượng và mảng được so sánh một cách đệ quy.
`isAnyOf(...expected)`	Xác nhận rằng đối tượng bằng một trong các giá trị đã cho. Đây là một phép so sánh giá trị chứ không phải phép so sánh tham chiếu. Nội dung của các đối tượng và mảng được so sánh một cách đệ quy.
`isNoneOf(...expected)`	Xác nhận rằng đối tượng không bằng bất kỳ giá trị nào đã cho. Đây là một phép so sánh giá trị chứ không phải phép so sánh tham chiếu. Nội dung của các đối tượng và mảng được so sánh một cách đệ quy.
`isStrictlyEqualTo(expected)`	Xác nhận rằng đối tượng hoàn toàn bằng (`===`) giá trị đã cho.
`isNotStrictlyEqualTo(expected)`	Xác nhận rằng đối tượng không hoàn toàn bằng (`!==`) giá trị đã cho.
`isGreaterThan(expected)`	Xác nhận rằng đối tượng lớn hơn (`>`) giá trị đã cho trong một phép so sánh có thứ tự.
`isGreaterThanOrEqualTo(expected)`	Xác nhận rằng đối tượng lớn hơn hoặc bằng (`>=`) giá trị đã cho trong một phép so sánh có thứ tự.
`isLessThan(expected)`	Xác nhận rằng đối tượng nhỏ hơn (`<`) giá trị đã cho trong một phép so sánh có thứ tự.
`isLessThanOrEqualTo(expected)`	Xác nhận rằng đối tượng nhỏ hơn hoặc bằng (`<=`) giá trị đã cho trong một phép so sánh có thứ tự.
`contains(...expected)`	Xác nhận rằng đối tượng là một mảng hoặc chuỗi chứa tất cả các giá trị đã cho theo bất kỳ thứ tự nào. Đây là một phép so sánh giá trị, không phải phép so sánh tham chiếu. Nội dung của các đối tượng và mảng được so sánh một cách đệ quy.
`doesNotContain(...expected)`	Xác nhận rằng đối tượng là một mảng hoặc chuỗi không chứa giá trị nào trong số các giá trị đã cho. Đây là một phép so sánh giá trị chứ không phải phép so sánh tham chiếu. Nội dung của các đối tượng và mảng được so sánh một cách đệ quy.
`containsExactly(...expected)`	Xác nhận rằng đối tượng là một mảng chứa tất cả các giá trị đã cho theo bất kỳ thứ tự nào và không có giá trị nào khác. Đây là một phép so sánh giá trị chứ không phải phép so sánh tham chiếu. Nội dung của các đối tượng và mảng được so sánh một cách đệ quy.
`doesNotContainExactly(...expected)`	Xác nhận rằng đối tượng là một mảng chứa một tập hợp các giá trị khác với các giá trị đã cho theo bất kỳ thứ tự nào. Đây là một phép so sánh giá trị chứ không phải phép so sánh tham chiếu. Nội dung của các đối tượng và mảng được so sánh một cách đệ quy.
`hasLength(expected)`	Xác nhận rằng đối tượng là một mảng hoặc chuỗi có độ dài nhất định. Câu khẳng định luôn thất bại nếu giá trị không phải là một mảng hoặc chuỗi.
`isEmpty()`	Xác nhận rằng đối tượng là một mảng hoặc chuỗi trống (độ dài = 0). Câu lệnh luôn thất bại nếu giá trị không phải là một mảng hoặc chuỗi.
`isNotEmpty()`	Xác nhận rằng đối tượng là một mảng hoặc chuỗi không trống (độ dài > 0). Câu khẳng định luôn thất bại nếu giá trị không phải là một mảng hoặc chuỗi.
`isArray()`	Xác nhận rằng loại của đối tượng là một mảng.
`isBoolean()`	Xác nhận rằng loại của đối tượng là boolean.
`isFunction()`	Xác nhận rằng kiểu của đối tượng là một hàm.
`isNumber()`	Xác nhận rằng loại của đối tượng là một số.
`isObject()`	Xác nhận rằng loại của đối tượng là một đối tượng.
`isString()`	Xác nhận rằng loại chủ đề là một chuỗi.

Ví dụ

assertThat(undefined).isUndefined();
assertThat(id, 'ID must be defined').isDefined();
assertThat(null).isNull();
assertThat(undefined).isNotNull();
assertThat(true).isTrue();
assertThat(false).isFalse();
assertThat(1).isTruthy();
assertThat('').isFalsy();
assertThat(1/0).isInfinity();
assertThat(0).isNotInfinity();
assertThat(-'foo').isNaN();
assertThat(100).isNotNaN();
assertThat(sentUrl).isEqualTo('https://endpoint.example.com/?account=12345');
assertThat(category).isNotEqualTo('premium');
assertThat(5).isAnyOf(1, 2, 3, 4, 5);
assertThat(42).isNoneOf('the question', undefined, 41.9);
assertThat('value').isStrictlyEqualTo('value');
assertThat('4').isNotStrictlyEqualTo(4);
assertThat(['a', 'b', 'c']).contains('a', 'c');
assertThat(['x', 'y', 'z']).doesNotContain('f');
assertThat(['1', '2', '3']).containsExactly('3', '2', '1');
assertThat(['4', '5']).doesNotContainExactly('4');
assertThat('a string').hasLength(8);
assertThat([]).isEmpty();
assertThat('another string').isNotEmpty();

`fail`

Ngay lập tức khiến bài kiểm thử hiện tại không thành công và in thông báo đã cho (nếu có).

Cú pháp

fail(opt_message);

Tham số

Thông số	Loại	Mô tả
`opt_message`	string	Văn bản thông báo lỗi không bắt buộc.

Ví dụ

fail('This test has failed.');

`mock`

API mock cho phép bạn ghi đè hành vi của các API trong hộp cát. Bạn có thể sử dụng API mô phỏng trong mã mẫu, nhưng API này chỉ hoạt động ở chế độ thử nghiệm. Các đối tượng mô phỏng sẽ được đặt lại trước khi mỗi lượt kiểm thử được chạy.

Cú pháp

mock(apiName, returnValue);

Tham số

Thông số	Loại	Mô tả
`apiName`	string	Tên của API cần mô phỏng; cùng một chuỗi như được truyền đến `require()`
`returnValue`	any	Giá trị cần trả về cho API hoặc một hàm được gọi thay cho API. Nếu `returnValue` là một hàm, thì hàm đó sẽ được gọi thay cho Sandboxed API; nếu `returnValue` không phải là một hàm, thì giá trị đó sẽ được trả về thay cho Sandboxed API.

Ví dụ

mock('encodeUri', "https://endpoint.example.com/?account=12345");
mock('sendPixel', function(url, onSuccess, onFailure) {
    onSuccess();
});

`mockObject`

API mockObject cho phép bạn ghi đè hành vi của các API trong hộp cát trả về một đối tượng. Bạn có thể sử dụng API này trong mã mẫu, nhưng API này chỉ hoạt động ở chế độ kiểm thử. Các đối tượng mô phỏng sẽ được đặt lại trước khi mỗi lượt kiểm thử được chạy.

Cú pháp

mockObject(apiName, objectMock);

Tham số

Thông số	Loại	Mô tả
`apiName`	string	Tên của API cần mô phỏng; cùng một chuỗi như được truyền đến `require()`
`objectMock`	object	Giá trị cần trả về cho API hoặc một hàm được gọi thay cho API. Phải là một đối tượng.

Ví dụ

const storage = {};
mockObject('localStorage', {
  setItem: (key, value) => {storage[key] = value;},
  getItem: (key) => storage[key],
});

`runCode`

Chạy mã cho mẫu, tức là nội dung của thẻ Code (Mã), trong môi trường kiểm thử hiện tại với một đối tượng dữ liệu đầu vào nhất định.

Cú pháp

runCode(data)

Tham số

Thông số	Loại	Mô tả
`data`	object	Đối tượng dữ liệu sẽ được dùng trong kiểm thử.

Giá trị trả về

Trả về giá trị của một biến cho các mẫu biến; trả về undefined cho tất cả các loại mẫu khác.

Ví dụ

runCode({field1: 123, field2: 'value'});

API mẫu tuỳ chỉnh Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Core API

addConsentListener

addEventCallback

aliasInWindow

callInWindow

callLater

copyFromDataLayer

copyFromWindow

createArgumentsQueue

createQueue

decodeUri

decodeUriComponent

encodeUri

encodeUriComponent

fromBase64

generateRandom

getContainerVersion

getCookieValues

getQueryParameters

getReferrerQueryParameters

getReferrerUrl

getTimestamp

getTimestampMillis

getType

getUrl

gtagSet

injectHiddenIframe

injectScript

isConsentGranted

JSON

localStorage

logToConsole

makeInteger

makeNumber

makeString

makeTableMap

Math

Object

parseUrl

queryPermission

readAnalyticsStorage

readCharacterSet

readTitle

require

sendPixel

setCookie

setDefaultConsentState

setInWindow

sha256

templateStorage

toBase64

updateConsentState

API kiểm thử

assertApi

assertThat

fail

mock

mockObject

runCode

API mẫu tuỳ chỉnh

`addConsentListener`

`addEventCallback`

`aliasInWindow`

`callInWindow`

`callLater`

`copyFromDataLayer`

`copyFromWindow`

`createArgumentsQueue`

`createQueue`

`decodeUri`

`decodeUriComponent`

`encodeUri`

`encodeUriComponent`

`fromBase64`

`generateRandom`

`getContainerVersion`

`getCookieValues`

`getQueryParameters`

`getReferrerQueryParameters`

`getReferrerUrl`

`getTimestamp`

`getTimestampMillis`

`getType`

`getUrl`

`gtagSet`

`injectHiddenIframe`

`injectScript`

`isConsentGranted`

`JSON`

`localStorage`

`logToConsole`

`makeInteger`

`makeNumber`

`makeString`

`makeTableMap`

`Math`

`Object`

`parseUrl`

`queryPermission`

`readAnalyticsStorage`

`readCharacterSet`

`readTitle`

`require`

`sendPixel`

`setCookie`

`setDefaultConsentState`

`setInWindow`

`sha256`

`templateStorage`

`toBase64`

`updateConsentState`

`assertApi`

`assertThat`

`fail`

`mock`

`mockObject`

`runCode`