API mẫu tuỳ chỉnh

Core API (API Lõi)

Các API này hoạt động với JavaScript dạng hộp cát để tạo các mẫu tuỳ chỉnh trong Trình quản lý thẻ của Google. Mỗi API được thêm 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 đồng ý đã chỉ định thay đổi.

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

Thông số

Thông số Loại Nội dung mô tả
consentType string Loại đồng ý để theo dõi những 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 chuyển loại đồng ý đang được thay đổi và giá trị mới của loại đồng ý đó:

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

Các quyền được liên kết

Quyền access_consent có quyền đọc cho loại đồng ý.

addEventCallback

API addEventCallback cho phép bạn đăng ký một hàm callback sẽ được gọi khi kết thúc 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 hết thời gian chờ sự kiện trên trang. Lệnh gọi lại được chuyển hai giá trị, mã 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)

Thông số

Thông số Loại Nội dung mô tả
callback hàm Hàm sẽ gọi khi sự kiện kết thúc.

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

Tên khóa Loại Nội dung mô tả
tags Mảng Một mảng các đối tượng dữ liệu thẻ. Mỗi thẻ được kích hoạt trong sự kiện sẽ có một mục nhập trong mảng này. Đối tượng dữ liệu thẻ chứa mã thẻ (id), trạng thái thực thi (status) và thời gian thực thi của thẻ (executionTime). Dữ liệu thẻ cũng sẽ bao gồm siêu dữ liệu bổ sung về thẻ đã đượ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 được liên kết

read_event_metadata

aliasInWindow

API aliasInWindow cho phép bạn tạo một bí danh (ví dụ: window.foo = window.bar) để hỗ trợ một số thẻ nhất định yêu cầu bí danh. Gán giá trị trong đối tượng window có 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)

Thông số

Thông số Loại Nội dung mô tả
toPath string Một đường dẫn được phân tách bằng dấu chấm vào đối tượng window nơi bạn sẽ sao chép giá trị vào. Mọi thành phần trong đường dẫn đến thành phần cuối cùng đều phải tồn tại trong đối tượng window.
fromPath string Một đườ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ị này không tồn tại, thì thao tác sẽ không thành công.

Ví dụ

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

Các quyền được liên kết

access_globals là bắt buộc cho 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 ra khỏi đối tượng window, theo cách được kiểm soát chính sách. 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 không thể liên kết trực tiếp loại dữ liệu trả về với một loại được hỗ trợ trong JavaScript hộp cát, thì undefined sẽ được trả về. Tám loại được hỗ trợ trong JavaScript dạng 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, undefined sẽ được trả về.

Cú pháp

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

Thông số

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

Các quyền được liên kết

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

callLater

Lên lịch cho một lệnh gọi đến một hàm diễn ra không đồng bộ. Hàm này sẽ được gọi sau khi mã hiện tại trả về. Giá trị này tương đương với setTimeout(<function>, 0).

Cú pháp

callLater(function)

Thông số

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

copyFromDataLayer

Trả về giá trị hiện được gán cho khoá nhất định trong lớp dữ liệu: Giá trị được tìm thấy tại khoá đã cho nếu đó là loại, hàm hoặc đối tượng nguyên gốc hoặc undefined.

Cú pháp

copyFromDataLayer(key[, dataLayerVersion])

Thông số

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

Các quyền được liên kết

read_data_layer

copyFromWindow

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

Cú pháp

copyFromWindow(key)

Thông số

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

Các quyền được liên kết

access_globals

createArgumentsQueue

Tạo một hàng đợi chứa các đối tượng đối số, để hỗ trợ các giải pháp thẻ cần đối số đó.

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

Khi gọi hàm được tạo trong fnKey, hàm này sẽ đẩy đối tượng của nó 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 đối với 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)

Thông số

Thông số Loại Nội dung mô tả
fnKey string Đường dẫn trong window nơi hàm được đặt, nếu hàm 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ì hệ thống sẽ gửi một ngoại lệ. Nghĩa là nếu fnKey là 'one.two' thì hệ thống sẽ gửi một ngoại lệ.
arrayKey string Đường dẫn trong window nơi mảng được đặt, nếu mảng đó 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ì hệ thống sẽ gửi một ngoại lệ. Nghĩa là, nếu arrayKey là 'one.two' và không có đối tượng toàn cục nào có tên 'one', thì hệ thống sẽ gửi ra một ngoại lệ.

Các quyền được liên kết

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 trên quyền access_globals.

Ví dụ:

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

Cú pháp

createQueue(arrayKey)

Thông số

Thông số Loại Nội dung mô tả
arrayKey string Khoá trong window nơi mảng được đặt, nếu mảng 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ì hệ thống sẽ gửi một ngoại lệ. Ví dụ: nếu arrayKey là 'one.two' và không có đối tượng toàn cục nào có tên là 'one', thì thao tác này sẽ gửi một ngoại lệ.

Các quyền được liên kết

access_globals

decodeUri

Giải mã mọi ký tự mã hoá trong URI được cung cấp. Trả về một chuỗi đại diện cho URI đã giải mã. Trả về undefined khi được cung cấp với thông tin đầ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)

Thông số

Thông số Loại Nội dung mô tả
encoded_uri string URI đã được mã hoá bằng encodeUri() hoặc bằng các phương thức khác.

Các quyền được liên kết

Không nội dung nào.

decodeUriComponent

Giải mã mọi ký tự mã hoá trong thành phần URI được cung cấp. Trả về một chuỗi đại diện cho thành phần URI đã giải mã. Trả về undefined khi được cung cấp thông tin nhập 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)

Thông số

Thông số Loại Nội dung 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 thức khác.

Các quyền được liên kết

Không nội dung nào.

encodeUri

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

Ví dụ:

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

Cú pháp

encodeUri(uri)

Thông số

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

Các quyền được liên kết

Không nội dung nào.

encodeUriComponent

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

Ví dụ:

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

Cú pháp

encodeUriComponent(str)

Thông số

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

Các quyền được liên kết

Không nội dung nào.

fromBase64

API fromBase64 cho phép bạn giải mã các chuỗi từ cách biểu diễn base64 của các chuỗi đó. Trả về undefined khi cho sẵn giá trị nhập không hợp lệ.

Cú pháp

fromBase64(base64EncodedString)

Thông số

Thông số Loại Nội dung 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 được liên kết

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)

Thông số

Thông số Loại Nội dung mô tả
min số Giá trị tiềm năng nhỏ nhất của số nguyên được trả về.
max số Giá trị tiềm năng lớn nhất của số nguyên được trả về.

Các quyền được liên kết

Không nội dung nào.

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 đây:

{
  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 được liên kết

read_container_data

getCookieValues

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

Cú pháp

getCookieValues(name[, decode])

Thông số

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

Các quyền được liên kết

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])

Thông số

Thông số Loại Nội dung mô tả
queryKey string Khoá để đọc từ các tham số truy vấn.
retrieveAll boolean Liệu có truy xuất tất 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 được liên kết

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 bất kỳ khoá truy vấn nào).

getReferrerQueryParameters

API getReferrerQueryParameters hoạt động giống như getQueryParameters, ngoại trừ việc API này hoạt động trên đường 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ả tham số cho queryKey của đường liên kết 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])

Thông số

Thông số Loại Nội dung mô tả
queryKey string Khoá để đọc từ các tham số truy vấn.
retrieveAll boolean Liệu có truy xuất tất cả giá trị hay không.

Ví dụ: nếu URL liên kết 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 được liên kết

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 bất kỳ khoá truy vấn nào.)

getReferrerUrl

Với một loại thành phần, API sẽ đọc đối tượng tài liệu cho đường 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 đường liên kết giới thiệu đó. Nếu không có thành phần nào được chỉ định, thì URL liên kết giới thiệu đầy đủ sẽ được trả về.

Cú pháp

getReferrerUrl([component])

Thông số

Thông số Loại Nội dung mô tả
component string Thành phần sẽ trả về từ URL. Có thể là một trong những trạng thái sau: 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 được liên kết

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 bất kỳ khoá truy vấn nào.)

getTimestamp

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

Trả về một số đại diện cho 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, được Date.now() trả về.

Cú pháp

getTimestamp();

Các quyền được liên kết

Không nội dung nào.

getTimestampMillis

Trả về một số đại diện cho 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, được Date.now() trả về.

Cú pháp

getTimestampMillis();

Các quyền được liên kết

Không nội dung nào.

getType

Trả về một chuỗi mô tả loại 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)

Ghi chú

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 "không xác định"
null "null"
true 'boolean'
12 "number"
'string' "string" (chuỗi)
{ a: 3 } "đối tượng"
[ 1, 3 ] "mảng"
(x) => x + 1 "hàm"

Các quyền được liên kết

Không nội dung nào.

getUrl

Trả về một chuỗi đại diện cho tất cả hoặc một phần URL hiện tại, dựa trên một loại thành phần và một số tham số cấu hình.

Cú pháp

getUrl(component)

Thông số

Thông số Loại Nội dung mô tả
component string Thành phần sẽ trả về từ URL. Thuộc tính này phải là một trong các loại sau: 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 được liên kết

get_url

gtagSet

Đẩy lệnh gtag set đến 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à nó kích hoạt đã xử lý xong (hoặc đã hết thời gian chờ xử lý thẻ). Bản cập nhật đảm bảo sẽ được xử lý trong vùng chứa này trước mọi mục đang chờ trong hàng đợi lớp dữ liệu.

Ví dụ: nếu được gọi bởi một thẻ được kích hoạt khi Tiến hành lấy sự đồng ý, thì bản 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, 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)

Thông số

Thông số Loại Nội dung mô tả
Object đối tượng Một đối tượng cập nhật trạng thái toàn cục cho các thuộc tính chứa đối tượng đó.

Các quyền được liên kết

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

Nếu dữ liệu đầu vào vào gtagSet là một khoá và một số giá trị đối tượng không thuần tuý, thì API sẽ kiểm tra quyền ghi vào khoá đó, chẳng hạn như đối với gtagSet('abc', true) , API sẽ kiểm tra quyền ghi vào 'abc'.

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 tiếp cận cùng một đối tượng mới được đánh dấu.

injectHiddenIframe

Thêm 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 dùng để gọi các lệnh gọi lại đó.

Cú pháp

injectHiddenIframe(url, onSuccess)

Thông số

Thông số Loại Nội dung mô tả
url string URL được dùng làm giá trị cho 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 được liên kết

inject_hidden_iframe

injectScript

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

Cú pháp

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

Thông số

Thông số Loại Nội dung mô tả
url string Địa chỉ của tập lệnh sẽ đượ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 nên được lưu vào bộ nhớ đệm. Nếu bạn chỉ định giá trị này, thì hệ thống sẽ chỉ tạo một phần tử tập lệnh để yêu cầu JavaScript. Nếu bạn cố gắng tải thêm một lần nữa, thì các phương thức onSuccess và onFailure đã cho sẽ được đưa vào hàng đợi cho đến khi tập lệnh tải.

Các quyền được liên kết

inject_script

isConsentGranted

Trả về true nếu đồng ý đã chỉ định được đồng ý.

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

Giao diện người dùng của 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ẻ luôn bậ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)

Thông số

Thông số Loại Nội dung mô tả
consentType string Loại đồng ý để kiểm tra trạng thái của.

Các quyền được liên kết

Quyền access_consent có quyền đọc cho loại đồng ý.

JSON

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

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

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

Cú pháp

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

Thông số

JSON.parse

Thông số Loại Nội dung mô tả
stringInput bất kỳ Giá trị cần chuyển đổi. Nếu giá trị không phải là chuỗi, thì dữ liệu đầu vào sẽ bị chuyển đổi thành một chuỗi.

JSON.stringify

Thông số Loại Nội dung mô tả
value bất kỳ 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 được liên kết

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 của trình duyệt.

Cú pháp

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

Thông số

Thông số Loại Nội dung mô tả
obj1 [, obj2,... objN] bất kỳ Đối số

Các quyền được liên kết

logging

makeInteger

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

Cú pháp

makeInteger(value)

Thông số

Thông số Loại Nội dung mô tả
value bất kỳ Giá trị cần chuyển đổi.

Các quyền được liên kết

Không nội dung nào.

makeNumber

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

Cú pháp

makeNumber(value)

Thông số

Thông số Loại Nội dung mô tả
value bất kỳ Giá trị cần chuyển đổi.

Các quyền được liên kết

Không nội dung nào.

makeString

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

Cú pháp

makeString(value)

Thông số

Thông số Loại Nội dung mô tả
value bất kỳ Giá trị cần chuyển đổi.

Các quyền được liên kết

Không nội dung nào.

makeTableMap

Chuyển đổi một đối tượng bảng đơn giản có hai cột thành Map. Trường này dùng để thay đổi 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 một Bản đồ:

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

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

Cú pháp

makeTableMap(tableObj, keyColumnName, valueColumnName)

Thông số

Thông số Loại Nội dung mô tả
tableObj List (Danh sách) Đối tượng bảng cần chuyển đổi. Đây là danh sách 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 mà các giá trị này sẽ trở thành giá trị trong Map đã chuyển đổi.

Các quyền được liên kết

Không nội dung nào.

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

Thông số

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

Các quyền được liên kết

Không nội dung nào.

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. Phương thức này trả về một mảng tên thuộc tính có thể đếm của riêng một đối tượng nhất định theo thứ tự của vòng lặp for...in.... Nếu giá trị đầu vào không phải là đối tượng, thì giá trị đó sẽ bị buộc thành đối tượng.

Phương thức values() cung cấp hành vi Object.values() của Thư viện chuẩn. Phương thức này trả về một mảng gồm các giá trị thuộc tính có thể đếm của riêng một đối tượng nhất định theo thứ tự giống như thứ tự của vòng lặp for...in.... Nếu giá trị đầu vào không phải là một đối tượng, thì giá trị đó sẽ bị 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. Phương thức này trả về một mảng gồm các cặp thuộc tính có thể liệt kê [key, value] của riêng một đối tượng nhất định theo thứ tự giống như vòng lặp for...in.... Nếu giá trị đầu vào không phải là một đối tượng, thì giá trị đó sẽ bị buộc 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 được một đối tượng được cố định nữa; việc đóng băng một đối tượng sẽ ngăn không cho thêm thuộc tính mới vào đối tượng đó, xoá các thuộc tính hiện có và thay đổi giá trị của các thuộc tính hiện có. freeze() trả về cùng một đối tượng đã được truyền vào. Đối số nguyên gốc hoặc đối số rỗng sẽ được coi là đối tượng bị cố định và sẽ được trả về.

Phương thức delete() cung cấp hành vi xoá toán tử của Thư viện chuẩn. Hàm này sẽ xoá khoá đã cho khỏi đối tượng trừ phi đối tượng bị treo. Giống như toán tử xoá của 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ị treo ngay cả khi giá trị đầu vào thứ hai (keyToDelete) chỉ định một khoá không tồn tại. Phương thức này sẽ trả về false trong mọi trường hợp khác. Tuy nhiên, toán tử này khác với toán tử xoá của Thư viện chuẩn theo những cách sau:

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

Cú pháp

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

Thông số

Object.keys

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

Object.values

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

Object.entries

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

Object.freeze

Thông số Loại Nội dung mô tả
objectInput bất kỳ Đối tượng cần đóng băng. Nếu dữ liệu đầu vào không phải là một đối tượng, thì nó sẽ được coi là một đối tượng cố định.

Object.delete

Thông số Loại Nội dung mô tả
objectInput bất kỳ Đố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 phần 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 không đúng định dạng. Đối với các URL được định dạng đúng cách, các trường không xuất hiện trong chuỗi URL sẽ có giá trị là một chuỗi trống, hoặc trong trường hợp searchParams, thì sẽ có 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);

Thông số

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

Các quyền được liên kết

Không nội dung nào.

queryPermission

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

Cú pháp

queryPermission(permission, functionArgs*)

Thông số

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

Đối số 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ố để 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 dưới dạng tham số thứ ba:

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

Các quyền được liên kết

Không nội dung nào.

readCharacterSet

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

Cú pháp

readCharacterSet()

Thông số

Không nội dung nào.

Các quyền được liên kết

read_character_set

readTitle

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

Cú pháp

readTitle()

Thông số

Không nội dung nào.

Các quyền được liên kết

read_title

require

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

Cú pháp

require(name)

Thông số

Thông số Loại Nội dung 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 được liên kết

Không nội dung nào.

sendPixel

Tạo yêu cầu GET đến một điểm cuối URL được chỉ định.

Cú pháp

sendPixel(url, onSuccess, onFailure)

Thông số

Thông số Loại Nội dung mô tả
url string Vị trí 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 được gửi thành công, trình duyệt vẫn 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 được liên kết

send_pixel

setCookie

Đặt hoặc xoá cookie có tên, giá trị và tuỳ chọn đã chỉ định.

Cú pháp

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

Thông số

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

  • Miền: do tài sản options['domain'] đặt (nếu có). Đặt giá trị này thành 'auto' để cố gắng ghi cookie bằng cách sử dụ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ử liên tiếp các miền con hẹp hơn. Nếu tất cả các bước trên đều không thành công, Chrome sẽ cố gắng ghi cookie mà không cần miền. Nếu không có giá trị nào được đặt, hệ thống sẽ cố ghi cookie mà không chỉ định miền. Lưu ý: khi cookie chưa chỉ định miền được ghi vào document.cookie, tác nhân người dùng sẽ đặt mặc định miền của cookie đó là máy chủ lưu trữ vị trí tài liệu hiện tại.
  • Đường dẫn: do options['path'] thiết lập, nếu có. Khi một cookie không có đường dẫn chỉ định được ghi vào document.cookie, tác nhân người dùng sẽ mặc định đường dẫn của cookie đến đường dẫn của vị trí tài liệu hiện tại.
  • Max-Age: (Độ tuổi tối đa): 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 theo định dạng UTC. Bạn có thể dùng Date.toUTCString() để định dạng Date cho tham số này.
  • An toàn: do options['secure'] đặt, nếu có.
  • SameSite: do options['samesite'] đặt, nếu có.

Các quyền được liên kết

set_cookies

setDefaultConsentState

Đẩy bản cập nhật mặc định về sự đồng ý lên 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 đã xử lý xong (hoặc đã hết thời gian chờ xử lý thẻ). Bản cập nhật đảm bảo sẽ được xử lý trong vùng chứa này trước mọi mục đang chờ trong lớp dữ liệu. Tìm hiểu thêm về chế độ đồ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)

Thông số

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

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

Tên khóa Loại Nội dung mô tả
consentType string Bạn có thể đặt giá trị của mỗi loại đồng ý thành "'granted'' hoặc "'denied'". Mọi giá trị không phải là "'granted'` đều sẽ được coi là "'denied". Việc đặt giá trị thành "không xác định" sẽ không ảnh hưởng đến giá trị trước đó của giá trị đó.
region Mảng Một mảng mã khu vực (không bắt buộc) giúp xác định khu vực mà chế độ cài đặt về sự đồng ý sẽ áp dụng. Mã khu vực được biểu thị bằng quốc gia và/hoặc phân mục theo định dạng ISO 3166-2.
wait_for_update số 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 những công cụ thu thập sự đồng ý tải không đồng bộ.

Các quyền được liên kết

Quyền access_consent có quyền ghi đối với mọi loại đồng ý trong đối tượng ConsentSettings.

setInWindow

Thiết lập 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ị. Hãy đặt overrideExisting thành true để thiết lập giá trị trong window, bất kể giá trị hiện có có hiện diện hay không. Trả về một boolean: true nếu giá trị được đặt thành công và false nếu giá trị không được đặt thành công.

Cú pháp

setInWindow(key, value, overrideExisting)

Thông số

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

Các quyền được liên kết

access_globals

sha256

Tính toán chuỗi đại diện SHA-256 của dữ liệu đầu vào và gọi một lệnh gọi lại có chuỗi đại diện được mã hoá trong base64, trừ khi đối tượng options chỉ định một cách 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)

Thông số

Thông số Loại Nội dung mô tả
input string Chuỗi cần tính hàm băm.
onSuccess hàm Được gọi bằng chuỗi đại diện 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 chuỗi đại diện hoặc nếu trình duyệt không có dịch vụ 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 lỗi và thông báo.
options đối tượng Đối tượng tuỳ chọn 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à base64 hoặc hex.

Các quyền được liên kết

Không nội dung nào.

templateStorage

Trả về một đối tượng 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 trong các quá trình 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 toàn bộ thời gian 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 được liên kết

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 giá trị biểu diễn base64.

Cú pháp

toBase64(input)

Thông số

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

Ví dụ

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

Các quyền được liên kết

Không có

updateConsentState

Đẩy nội dung cập nhật về sự đồng ý lên 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 được xử lý xong (hoặc đã hết thời gian chờ xử lý thẻ). Bản cập nhật được đảm bảo sẽ được xử lý trong vùng chứa này trước mọi mục đang chờ ở hàng đợi trong lớp dữ liệu. Tìm hiểu thêm về chế độ đồng ý.

Ví dụ:

const updateConsentState = require('updateConsentState');

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

Cú pháp

updateConsentState(consentSettings)

Thông số

Thông số Loại Nội dung mô tả
consentSettings đối tượng Đối tượng cập nhật trạng thái cho các loại đồng ý đã chỉ định.

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

Tên khóa Loại Nội dung mô tả
consentType string Bạn có thể đặt giá trị cho mỗi loại đồng ý thành "đã cấp" hoặc "đã từ chối". Bất kỳ giá trị nào khác ngoài "đã cấp" đều sẽ được coi là "đã bị từ chối". Việc đặt giá trị thành "không xác định" sẽ không ảnh hưởng đến giá trị trước đó.

Các quyền được liên kết

Quyền access_consent có quyền ghi đối với mọi 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 dạng hộp cát để tạo thử nghiệm cho các 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ề thử nghiệm mẫu tuỳ chỉnh.

assertApi

Trả về một đối tượng trình so khớp có thể dùng để đưa ra nhận định thành thạo về API nhất định.

Cú pháp

assertApi(apiName)

Thông số

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

Người so khớp

  • 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 lập mô hình dựa trên thư viện [Truth] của Google. Phương thức này trả về một đối tượng có thể dùng để đưa ra nhận định thành thạo về giá trị của một đối tượng. Lỗi xác nhận sẽ ngay lập tức dừng hoạt động kiểm thử và đánh dấu là không thành công. Tuy nhiên, lỗi trong một lượ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)

Thông số

Thông số Loại Nội dung mô tả
actual bất kỳ Giá trị để sử dụng trong các lần kiểm tra độ thành thạo.
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.

Người so khớp

Trình so khớp Nội dung mô tả
isUndefined() Xác nhận rằng đối tượng 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 đối tượng 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 đối tượng là false.
isTrue() Xác nhận rằng đối tượng là true.
isFalsy() Xác nhận rằng đối tượng là giả mạo. Các giá trị giả là undefined, null, false, NaN, 0 và '' (chuỗi trống).
isTruthy() Xác nhận rằng chủ đề là trung thực. Các giá trị giả là undefined, null, false, NaN, 0 và '' (chuỗi trống).
isNaN() Xác nhận rằng tiêu đề là giá trị NaN.
isNotNaN() Xác nhận rằng tiêu đề là giá trị bất kỳ ngoài NaN.
isInfinity() Xác nhận rằng đối tượng là Infinity dương hoặc âm.
isNotInfinity() Xác nhận rằng chủ thể là bất kỳ giá trị nào ngoài Infinity dương hoặc âm.
isEqualTo(expected) Xác nhận rằng chủ thể tương đương với giá trị đã cho. Đây là tính năng so sánh giá trị chứ không phải là so sánh tham khảo. Nội dung của các đối tượng và mảng được so sánh theo quy tắc đệ quy.
isNotEqualTo(expected) Xác nhận rằng chủ thể không bằng với giá trị đã cho. Đây là phần so sánh giá trị chứ không phải là so sánh tham chiếu. Nội dung của các đối tượng và mảng được so sánh theo quy tắc đệ quy.
isAnyOf(...expected) Xác nhận rằng chủ thể tương đương với một trong các giá trị đã cho. Đây là phần so sánh giá trị chứ không phải là so sánh tham chiếu. Nội dung của các đối tượng và mảng được so sánh theo quy tắc đệ quy.
isNoneOf(...expected) Xác nhận rằng chủ thể không bằng bất kỳ giá trị nào đã cho. Đây là phần so sánh giá trị chứ không phải là so sánh tham khảo. Nội dung của các đối tượng và mảng được so sánh theo quy tắc đệ quy.
isStrictlyEqualTo(expected) Xác nhận rằng chủ thể hoàn toàn bằng (===) với giá trị đã cho.
isNotStrictlyEqualTo(expected) Xác nhận rằng chủ thể này không hoàn toàn bằng (!==) với giá trị đã cho.
isGreaterThan(expected) Xác nhận rằng chủ thể lớn hơn (>) giá trị đã cho trong phép so sánh có thứ tự.
isGreaterThanOrEqualTo(expected) Xác nhận rằng chủ thể 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 chủ thể nhỏ hơn (<) giá trị đã cho trong phép so sánh có thứ tự.
isLessThanOrEqualTo(expected) Xác nhận rằng chủ thể nhỏ hơn hoặc bằng (<=) giá trị đã cho trong phép so sánh có thứ tự.
contains(...expected) Xác nhận rằng tiêu đề là một mảng hoặc chuỗi chứa tất cả các giá trị đã cho theo thứ tự bất kỳ. Đây là tính năng so sánh giá trị, không phải là so sánh tham khảo. Nội dung của các đối tượng và mảng được so sánh theo quy tắc đệ quy.
doesNotContain(...expected) Xác nhận rằng chủ đề là một mảng hoặc chuỗi không chứa giá trị nào đã cho. Đây là phần so sánh giá trị, không phải là so sánh tham khảo. Nội dung của đối tượng và mảng được so sánh theo quy tắc đệ quy.
containsExactly(...expected) Xác nhận rằng chủ thể là một mảng chứa tất cả giá trị đã cho theo thứ tự bất kỳ và không có giá trị nào khác. Đây là phần so sánh giá trị chứ không phải là so sánh tham chiếu. Nội dung của các đối tượng và mảng được so sánh theo quy tắc đệ quy.
doesNotContainExactly(...expected) Xác nhận rằng chủ thể là một mảng chứa một tập hợp giá trị khác từ các giá trị đã cho theo thứ tự bất kỳ. Đây là tính năng so sánh giá trị, không phải là so sánh tham khảo. Nội dung của các đối tượng và mảng được so sánh theo quy tắc đệ quy.
hasLength(expected) Xác nhận rằng tiêu đề là một mảng hoặc chuỗi có độ dài đã cho. Xác nhận luôn không thành công nếu giá trị không phải là mảng hoặc chuỗi.
isEmpty() Xác nhận rằng tiêu đề là một mảng hoặc chuỗi trống (length = 0). Xác nhận luôn không thành công nếu giá trị không phải là mảng hoặc chuỗi.
isNotEmpty() Xác nhận rằng tiêu đề là một mảng hoặc chuỗi không trống (độ dài > 0). Xác nhận luôn không thành công nếu giá trị không phải là một mảng hoặc chuỗi.
isArray() Xác nhận rằng kiểu đối tượng là một mảng.
isBoolean() Xác nhận rằng kiểu của đối tượng là một boolean.
isFunction() Xác nhận rằng kiểu đối tượng là một hàm.
isNumber() Xác nhận rằng kiểu đối tượng là một số.
isObject() Xác nhận rằng kiểu đối tượng là một đối tượng.
isString() Xác nhận rằng kiểu đối tượng 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 thất bại trong kiểm thử hiện tại và in thông báo đã cho (nếu được cung cấp).

Cú pháp

fail(opt_message);

Thông số

Thông số Loại Nội dung mô tả
opt_message string Nội dung 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 hộp cát. API mô phỏng này có thể sử dụng an toàn trong mã mẫu, nhưng sẽ không hoạt động khi không ở chế độ kiểm thử. Các bản mô phỏng sẽ được đặt lại trước khi chạy mỗi lượt kiểm thử.

Cú pháp

mock(apiName, returnValue);

Thông số

Thông số Loại Nội dung mô tả
apiName string Tên của API cần mô phỏng; cùng chuỗi như được truyền đến require()
returnValue bất kỳ Giá trị để 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 API Hộp cát; nếu returnValue không phải là hàm, thì giá trị đó sẽ được trả về thay cho API Hộp cát.

Ví dụ

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

runCode

Chạy mã cho mẫu, tức là nội dung của thẻ Code (Mã), trong môi trường thử nghiệm 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)

Thông số

Thông số Loại Nội dung mô tả
data đối tượng Đối tượng dữ liệu 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'});