API cốt lõi
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 của loại đồng ý được chỉ định thay đổi từ từ chối thành đồng ý hoặc từ đồng ý thành từ chối. Loại yêu cầu đồng ý không có trạng thái được coi là đã cấ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 đã cấp. Hàm trình nghe sẽ chịu trách nhiệm đảm bảo mã của chúng chạy đúng số lần.
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 sự đồng ý đang được thay đổi và giá trị mới của loại sự đồng ý đó:
| Thông số | Loại | Mô tả |
|---|---|---|
consentType |
string | Loại yêu cầu đồng ý đang được thay đổi. |
granted |
boolean | Giá trị boolean là true nếu loại đồng ý đã chỉ định đang được thay đổi thành đã cấp. |
Quyền được liên kết
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 khi kết thúc 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 hết thời gian chờ sự kiện trong 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 để 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 | Mô tả |
|---|---|---|
tags |
Mảng | Một mảng gồm 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ã nhận dạng của thẻ (id), trạng thái thực thi của thẻ (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 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);
});
Quyền được liên kết
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 cần có bí danh. Gán 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, false nếu không.
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, nơi bạn sẽ sao chép giá trị. 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')
Quyền được liên kết
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 được kiểm soát bằng 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ể ánh xạ trực tiếp kiểu trả về đến một kiểu được hỗ trợ trong JavaScript trong hộp cát, thì undefined sẽ được trả về. 8 loại được hỗ trợ trong JavaScript trong 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. |
Quyền được liên kết
access_globals đã bật quyền execute.
callLater
Lên lịch gọi một hàm để xảy ra 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 gán cho khoá đã cho trong lớp dữ liệu: Giá trị tìm thấy tại khoá đã cho nếu đó là kiểu gốc, hàm hoặc giá trị cố định đối tượng, nếu không thì là undefined.
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 |
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 không nên sử dụng giá trị 1. |
Quyền được liên kết
copyFromWindow
Sao chép một biến từ đối tượng window. Nếu không thể ánh xạ trực tiếp giá trị trong window đến một loại được hỗ trợ trong JavaScript trong hộp cát, thì undefined sẽ được trả về. 8 loại được hỗ trợ trong JavaScript trong hộp cát là null, undefined, boolean, number, string, Array, Object và function.
Trả về giá trị đã tìm nạp (và buộc).
Cú pháp
copyFromWindow(key)
Tham số
| Thông số | Loại | Mô tả |
|---|---|---|
key |
string | Khoá trong window để sao chép giá trị. |
Quyền được liên kết
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ẻ cần đến hàng đợi.
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 với createQueue). Sau khi hàm được tạo, 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 hàm được tạo trong fnKey được gọi, hàm này sẽ đẩy đối tượng đối số 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 đặt hàm, nếu đường dẫn này 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, hệ thống sẽ gửi một trường hợp ngoại lệ. Tức là nếu fnKey là 'one.two', thì hàm này sẽ gửi một ngoại lệ. |
arrayKey |
string | Đường dẫn trong window nơi đặt mảng, 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, hệ thống sẽ gửi một trường hợp ngoại lệ. Tức là 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ì đối tượng này sẽ gửi một ngoại lệ. |
Quyền được liên kết
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)
Tham số
| Thông số | Loại | Mô tả |
|---|---|---|
arrayKey |
string | Khoá trong window nơi đặt mảng, 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, hệ thống sẽ gửi một trường hợp 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ì đối tượng này sẽ gửi một ngoại lệ. |
Quyền được liên kết
decodeUri
Giải mã mọi ký tự đã mã hoá trong URI đã 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 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 thức khác. |
Quyền được liên kết
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 chuỗi đại diện cho 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. |
Quyền được liên kết
Không có.
encodeUri
Trả về một Giá trị nhận dạng tài nguyên đồng nhất (URI) đã mã hoá bằng cách thoát các ký tự đặc biệt. Trả về một chuỗi đại diện cho chuỗi đã cung cấp được mã hoá dưới dạng URI. Trả về undefined khi được cung cấp dữ liệu đầu vào không hợp lệ (một đại diện đơ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. |
Quyền được liên kết
Không có.
encodeUriComponent
Trả về một Giá trị nhận dạng tài nguyên đồng nhất (URI) đã mã hoá bằng cách thoát các ký tự đặc biệt. Trả về một chuỗi đại diện cho chuỗi đã cung cấp được mã hoá dưới dạng URI. Trả về undefined khi được cung cấp dữ liệu đầu vào không hợp lệ (một đại diện đơn lẻ).
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. |
Quyền được liên kết
Không có.
fromBase64
API fromBase64 cho phép bạn giải mã các chuỗi từ bản trình bày base64. Trả về undefined khi được cung cấp dữ liệu đầ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') {
// ...
}
Quyền được liên kết
Không có
generateRandom
Trả về một số (số nguyên) ngẫu nhiên trong phạm vi đã cho.
Cú pháp
generateRandom(min, max)
Tham số
| Thông số | Loại | Mô tả |
|---|---|---|
min |
số | Giá trị tiềm năng tối thiểu của số nguyên được trả về. |
max |
số | Giá trị tiềm năng tối đa của số nguyên được trả về. |
Quyền được liên kết
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();
Quyền được liên kết
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ó giải mã giá trị cookie bằng
decodeURIComponent() của JavaScript hay không. Giá trị mặc định là true. |
Quyền được liên kết
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 | Liệu 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']
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 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 trình giới thiệu đã cho. 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 | Liệu có truy xuất tất cả các giá trị hay không. |
Ví dụ: nếu URL của trình 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']
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 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 trình giới thiệu và trả về một chuỗi đại diện cho một phần của trình giới thiệu. Nếu bạn không chỉ định thành phần nào, hệ thống sẽ trả về URL đầy đủ của đường liên kết giới thiệu.
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 giá trị 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, toàn bộ URL sẽ được trả về. |
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 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, như được Date.now() trả về.
Cú pháp
getTimestamp();
Quyền được liên kết
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, như được Date.now() trả về.
Cú pháp
getTimestampMillis();
Quyền được liên kết
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 |
'số' |
'string' |
'chuỗi" |
{ a: 3 } |
'object' |
[ 1, 3 ] |
'mảng' |
(x) => x + 1 |
'function' |
Quyền được liên kết
Không có.
getUrl
Trả về một chuỗi đại diện cho toàn bộ hoặc một phần của 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)
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ị 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ề. |
Quyền được liên kết
gtagSet
Đẩy 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 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 trong hàng đợi của lớp dữ liệu.
Ví dụ: nếu được gọi bởi một thẻ được 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 |
đố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 của đối tượng đó. |
Quyền được liên kết
write_data_layer kiểm tra quyền ghi vào dataLayer cho tất cả các khoá đã chỉ định. Nếu dữ liệu đầu vào cho gtagSet là một đối tượng thuần tuý, thì API sẽ kiểm tra quyền ghi vào 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 vào foo.bar.
Nếu dữ liệu đầu vào cho gtagSet là một khoá và một số giá trị đối tượng không phải là giá trị 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 vòng lặp trong đối tượng đầu vào, thì chỉ các khoá trước khi đạt đến cùng một đối tượng mới được kiểm tra.
injectHiddenIframe
Thêm một iframe ẩn vào trang.
Lệnh gọi lại được cung cấp dưới dạng thực thể hàm và được gói trong các hàm JavaScript gọi đến các hàm đó.
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. |
Quyền được liên kết
injectScript
Thêm thẻ tập lệnh vào trang để tải URL đã cho một cách 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 gọi đến các thực thể đó.
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 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 không tải được tập lệnh. |
cacheToken |
string | Chuỗi không bắt buộc dùng để cho biết URL đã cho phải đượ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 lần thử tải bổ sung sẽ dẫn đến việc các phương thức onSuccess và onFailure đã cho được đưa vào hàng đợi cho đến khi tập lệnh tải. |
Quyền được liên kết
isConsentGranted
Trả về true nếu loại sự đồng ý đã chỉ định được cấp.
Sự đồng ý đối với 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 hoàn toàn không được đặt. Nếu bạn đặt loại sự đồng ý thành bất kỳ giá trị nào khác, thì loại sự đồng ý đó sẽ được coi là không được cấp.
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 tuỳ chọn để luôn kích hoạt. Nếu một thẻ luôn bật tính năng kích hoạt sử dụng API này, thì sự đồng ý sẽ được coi là đã được cấp và true sẽ được trả về, bất kể trạng thái đồng ý thực tế là gì.
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. |
Quyền được liên kết
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 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à chuỗi, thì giá trị đầu vào sẽ được chuyển đổi thành 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 thể phân tích cú pháp giá trị (ví dụ: đối tượng có 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 | 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ẽ được chuyển đổi thành chuỗi. |
JSON.stringify
| Thông số | Loại | 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);
Quyền được liên kết
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ý đối số vào bảng điều khiển của trình duyệt.
Cú pháp
logToConsole(obj1 [, obj2,... objN])
Tham số
| Thông số | Loại | Mô tả |
|---|---|---|
obj1 [, obj2,... objN] |
bất kỳ | Đối số |
Quyền được liên kết
makeInteger
Chuyển đổi giá trị đã cho thành số (số nguyên).
Cú pháp
makeInteger(value)
Tham số
| Thông số | Loại | Mô tả |
|---|---|---|
value |
bất kỳ | Giá trị cần chuyển đổi. |
Quyền được liên kết
Không có.
makeNumber
Chuyển đổi giá trị đã cho thành một số.
Cú pháp
makeNumber(value)
Tham số
| Thông số | Loại | Mô tả |
|---|---|---|
value |
bất kỳ | Giá trị cần chuyển đổi. |
Quyền được liên kết
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 |
bất kỳ | Giá trị cần chuyển đổi. |
Quyền được liên kết
Không có.
makeTableMap
Chuyển đổi đối tượng bảng đơn giản có hai cột thành Map. Phương thức này dùng để thay đổi trường mẫu SIMPLE_TABLE có hai 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 đố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 Đố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 đố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ó giá trị sẽ trở thành khoá trong Map đã chuyển đổi. |
valueColumnName |
string | Tên của cột có giá trị sẽ trở thành giá trị trong Map đã chuyển đổi. |
Quyền được liên kết
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ố hàm toán học được chuyển đổi thành số.
Quyền được liên kết
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 tên thuộc tính có thể liệt kê của một đối tượng nhất định theo thứ tự mà vòng lặp for...in... sẽ trả về. Nếu giá trị đầu vào không phải là đối tượng, thì giá trị đó sẽ được chuyển đổi 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. Hàm này trả về một mảng 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à đối tượng, thì giá trị đó sẽ được chuyển đổi thành đố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 các cặp thuộc tính có thể liệt kê [key, value] 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à đối tượng, thì giá trị đó sẽ được chuyển đổi thành đố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; việc đóng băng đối tượng sẽ ngăn việc 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ố gốc hoặc rỗng sẽ được coi là đối tượng bị đóng băng 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. Phương thứ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á 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ị đó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 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 ở những điểm sau:
keyToDeletekhông được là một chuỗi được phân tách bằng dấu chấm chỉ định khoá lồng nhau.- Không thể dùng
delete()để xoá các phần tử khỏi một mảng. - Không thể dùng
delete()để xoá bất kỳ thuộc tính nào khỏi phạm vi toàn cục.
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 | bất kỳ | Đối tượng có các khoá cần liệt kê. Nếu dữ liệu đầu vào không phải là đối tượng, thì dữ liệu đó sẽ được chuyển đổi thành đối tượng. |
Object.values
| Thông số | Loại | Mô tả |
|---|---|---|
| objectInput | bất kỳ | Đối tượng có các giá trị cần liệt kê. Nếu dữ liệu đầu vào không phải là đối tượng, thì dữ liệu đó sẽ được chuyển đổi thành đối tượng. |
Object.entries
| Thông số | Loại | Mô tả |
|---|---|---|
| objectInput | bất kỳ | Đối tượng có các cặp khoá/giá trị cần liệt kê. Nếu dữ liệu đầu vào không phải là đối tượng, thì dữ liệu đó sẽ được chuyển đổi thành đối tượng. |
Object.freeze
| Thông số | Loại | 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à đối tượng, thì dữ liệu đó sẽ được coi là đối tượng bị đóng băng. |
Object.delete
| Thông số | Loại | 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 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 đúng cách, các 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. |
Quyền được liên kết
Không có.
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 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 quyền. |
functionArgs |
bất kỳ | Các đối số hàm khác nhau tuỳ theo quyền đang đượ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: Không cần thêm đối số nào để truy vấn xem có thể đọc toàn bộ URL hay không. Để truy vấn xem có thể đọc một thành phần nhất định 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ó đọ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(...);
}
Quyền được liên kết
Không có.
readCharacterSet
Trả về giá trị của document.characterSet.
Cú pháp
readCharacterSet()
Tham số
Không có.
Quyền được liên kết
readTitle
Trả về giá trị của document.title.
Cú pháp
readTitle()
Tham số
Không có.
Quyền được liên kết
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();
Quyền được liên kết
Không có.
sendPixel
Tạo 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, 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 không tải được pixel. Lưu ý: ngay cả khi yêu cầu gửi thành công, onFailure có thể chạy nếu máy chủ không trả về phản hồi hình ảnh hợp lệ. |
Quyền được liên kết
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])
Tham số
| Thông số | Loại | 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, Tuổi tối đa, An toàn và SameSite. (Xem phần Tuỳ chọn bên dưới.) |
encode |
boolean | Kiểm soát việc liệu giá trị cookie có được mã hoá bằng encodeURIComponent() của JavaScript hay không.
Mặc định là true. |
- 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í tài liệu. Nếu không thành công, trình duyệt sẽ thử các miền con hẹp hơn. Nếu tất cả các miền đó đều không thành công, thì cookie sẽ được ghi mà không cần miền. Nếu bạn không đặt giá trị, thì thuộc tính 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àodocument.cookie, thì tác nhân người dùng sẽ đặt miền của cookie theo mặc định 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àodocument.cookie, thì tác nhân người dùng sẽ đặt đường dẫn mặc định của cookie thành đường dẫn của vị trí tài liệu hiện tại. - Max-Age: do
options['max-age']đặt, nếu có. - Expires (Ngày 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 UTC. Bạn có thể sử dụngDate.toUTCString()để định dạngDatecho tham số này. - Secure (Bảo mật): do
options['secure']đặt, nếu có. - SameSite: do
options['samesite']đặt, nếu có.
Quyền được liên kết
setDefaultConsentState
Đẩy nội dung cập nhật về sự đồng ý mặc định đế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 hoàn tất quá trình xử lý (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 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 |
đối tượng | 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 bản đồ ánh xạ các chuỗi loại sự đồng ý tuỳ ý đến một trong hai loạ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 mỗi loại sự đồng ý thành "granted" ("đã cấp") hoặc "denied" ("bị từ chối"). 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 không bắt buộc gồm các mã khu vực chỉ định khu vực áp dụng chế độ cài đặt trạng thái đồng ý. Mã khu vực được biểu thị bằng quốc gia và/hoặc các tiểu khu ở định dạng ISO 3166-2. |
wait_for_update |
số | Chỉ định một giá trị mili giây để kiểm soát khoảng thời gian chờ trước khi gửi dữ liệu. Dùng với các công cụ yêu cầu đồng ý tải không đồng bộ. |
Quyền được liên kết
Quyền access_consent có quyền ghi đối với tất cả các loại sự đồ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 có 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ị. |
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. |
Quyền được liên kết
sha256
Tính toán hàm băm SHA-256 của dữ liệu đầu vào và gọi lệnh gọi lại với hàm băm đượ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 để 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 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 bộ mã hoá đầu ra. Nếu được chỉ định, đối tượng phải chứa khoá outputEncoding với giá trị là một trong hai giá trị base64 hoặc hex. |
Quyền được liên kết
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 trên các lần thực thi của một mẫu. Dữ liệu được lưu trữ trong bộ nhớ mẫu sẽ tồn tại trong suốt thời gian hoạt động 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();
Quyền được liên kết
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 bản trình bày 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');
Quyền được liên kết
Không có
updateConsentState
Đẩy nội dung cập nhật về sự đồng ý đế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 hoàn tất quá trình xử lý (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 trong hàng đợi ở 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 |
đối tượng | Một đối tượng cập nhật trạng thái cho các loại sự đồng ý đã chỉ định. |
Đối tượng consentSettings là một bản đồ ánh xạ các chuỗi loại sự đồng ý tuỳ ý đến một trong hai loạ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 yêu cầu đồng ý thành "đã đồng ý" hoặc "đã từ chối". Mọi giá trị khác ngoài "granted" (đã cấp) sẽ được coi là "denied" (bị từ chối). Việc đặt giá trị thành "undefined" sẽ không ảnh hưởng đến giá trị trước đó. |
Quyền được liên kết
Quyền access_consent có quyền ghi đối với tất cả các loại sự đồ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 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ề kiểm thử mẫu tuỳ chỉnh.
assertApi
Trả về một đối tượng trình so khớp có thể dùng để đưa ra các câu nhận định 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; cùng một chuỗi được truyền đến require().
|
Trình 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 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ể được dùng để đưa ra các câu nhận định trôi chảy về giá trị của một chủ thể. Một lỗi xác nhận sẽ ngay lập tức dừng kiểm thử và đánh dấu kiểm thử đó là không thành công. Tuy nhiên, lỗi trong một bài 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 |
bất kỳ | Giá trị cần sử dụng trong các lượt kiểm tra trôi chảy. |
opt_message |
string | Thông báo không bắt buộc để in nếu câu nhận định không thành công. |
Trình so khớp
| Trình so khớp | Mô tả |
|---|---|
isUndefined() |
Xác nhận rằng chủ đề là undefined. |
isDefined() |
Xác nhận rằng chủ đề không phải là undefined. |
isNull() |
Xác nhận rằng chủ đề là null. |
isNotNull() |
Xác nhận rằng chủ đề 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à số vô cực dương hoặc âm. |
isNotInfinity() |
Xác nhận rằng đối tượng là bất kỳ giá trị nào ngoài số vô cực dương hoặc âm. |
isEqualTo(expected) |
Xác nhận rằng chủ đề bằng với giá trị đã cho. Đây là 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 đệ quy. |
isNotEqualTo(expected) |
Xác nhận rằng chủ đề 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 đệ quy. |
isAnyOf(...expected) |
Xác nhận rằng chủ đề 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 đệ quy. |
isNoneOf(...expected) |
Xác nhận rằng chủ đề 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 đệ quy. |
isStrictlyEqualTo(expected) |
Xác nhận rằng đối tượng là hoàn toàn bằng (===) với giá trị đã cho. |
isNotStrictlyEqualTo(expected) |
Xác nhận rằng đối tượng không hoàn toàn bằng (!==) với 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 chủ đề 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à 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ánhRecursively. |
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 trong số các giá trị đã cho. Đây là 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 đệ 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 thứ tự bất kỳ và không có giá trị nào khác. Đây là so sánh giá trị, chứ không phải so sánh tham chiếu. Nội dung của các đối tượng và mảng được so sánhRecursively. |
doesNotContainExactly(...expected) |
Xác nhận rằng đối tượng là một mảng chứa một tập hợp giá trị khác với các giá trị đã cho theo thứ tự bất kỳ. Đây là 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 đệ quy. |
hasLength(expected) |
Xác nhận rằng chủ đề là một mảng hoặc chuỗi có độ dài nhất định. Câu nhận định 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 chủ đề là một mảng hoặc chuỗi trống (độ dài = 0). Câu nhận định 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. |
isNotEmpty() |
Xác nhận rằng chủ đề là một mảng hoặc chuỗi không trống (độ dài > 0). Câu nhận định 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 loại của chủ đề là một mảng. |
isBoolean() |
Xác nhận rằng loại của chủ đề là boolean. |
isFunction() |
Xác nhận rằng loại của đối tượng là một hàm. |
isNumber() |
Xác nhận rằng loại của chủ đề 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 của 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 không đạt kiểm thử hiện tại 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 Hộp cát. Bạn có thể sử dụng API mô phỏng một cách an toàn trong mã mẫu, nhưng API này chỉ hoạt động ở chế độ kiểm thử.
Các mô phỏng sẽ được đặt lại trước khi chạy mỗi chương trình kiểm thử.
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 được truyền đến require() |
returnValue |
bất kỳ | 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 API Hộp cát; nếu returnValue là bất kỳ giá trị nào khác ngoài 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();
});
mockObject
API mockObject cho phép bạn ghi đè hành vi của các API Hộp cát trả về một đối tượng. Bạn có thể sử dụng API này một cách an toàn trong mã mẫu, nhưng API này chỉ hoạt động ở chế độ kiểm thử. Mô phỏng sẽ được đặt lại trước khi chạy mỗi chương trình kiểm thử.
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 được truyền đến require() |
objectMock |
đối tượng | 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 |
đối tượng | Đối tượng dữ liệu sẽ được sử 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'});