API cốt 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 Google
Trình quản lý thẻ. 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 sự đồng ý đã chỉ định các thay đổi về loại.
Trình nghe nhất định sẽ được gọi mỗi lần trạng thái cho thuộc tính được chỉ định loại đồng ý thay đổi từ từ chối thành đã đồng ý hoặc từ đã đồng ý thành từ chối. Sự đồng ý không có trạng thái nào được coi là đã được cấp, do đó trình nghe sẽ không được gọi nếu chưa đặt loại đồng ý sẽ được cập nhật thành đã đồng ý. Các chức năng trình nghe sẽ chịu trách nhiệm đảm bảo mã của họ chạy số lần thích hợp.
Ví dụ:
const isConsentGranted = require('isConsentGranted');
const addConsentListener = require('addConsentListener');
if (!isConsentGranted('ad_storage')) {
let wasCalled = false;
addConsentListener('ad_storage', (consentType, granted) => {
if (wasCalled) return;
wasCalled = true;
const cookies = getMyCookies();
sendFullPixel(cookies);
});
}
Cú pháp
addConsentListener(consentType, listener)
Tham số
| Thông số | Loại | Mô tả |
|---|---|---|
consentType |
string | Loại đồ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 một trình nghe được gọi, loại đồng ý đang được truyền sẽ được truyền đã thay đổi và giá trị mới của loại đồng ý đó:
| Thông số | Loại | Mô tả |
|---|---|---|
consentType |
string | Loại đồng ý sắp được thay đổi. |
granted |
boolean | Giá trị boolean đúng nếu loại đồng ý đã chỉ định đang được thay đổi để cho phép. |
Các quyền được liên kết
Quyền access_consent có quyền đọc đối với loại đồng ý.
addEventCallback
API addEventCallback cho phép bạn đăng ký một hàm callback sẽ
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 đã được 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 chuyển hai giá trị, mã của vùng chứa gọi phương thức
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 kết thúc sự kiện. |
Đối tượng eventData chứa dữ liệu sau:
| Tên khóa | Loại | Mô tả |
|---|---|---|
tags |
Mảng | Một mảng gồm các đối tượng dữ liệu thẻ. Tất cả các thẻ được kích hoạt trong sự kiện
sẽ có một mục trong mảng này. Đối tượng dữ liệu thẻ chứa
mã nhận dạng của thẻ (id), trạng thái thực thi của thẻ
(status) và thời gian thực thi
(executionTime). Dữ liệu thẻ cũng sẽ bao gồm
siêu dữ liệu thẻ đã đượ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
aliasInWindow
API aliasInWindow cho phép bạn tạo bí danh (ví dụ: window.foo =
window.bar), giúp hỗ trợ một số thẻ nhất định yêu cầu đặt chồng phổ. Chỉ định
giá trị trong đối tượng window được tìm thấy tại fromPath đối với 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 | Một đường dẫn được phân tách bằng dấu chấm vào đối tượng window nơi có một giá trị
cần được sao chép vào. Tất cả thành phần trong đường dẫn đến thành phần cuối cùng
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 đến window dẫn đến giá trị cần sao chép. Nếu
giá trị không tồn tại, thao tác sẽ không thành công. |
Ví dụ
aliasInWindow('foo.bar', 'baz.qux')
Các quyền đượ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 ra khỏi đối tượng window, theo một chính sách-
một cách dễ dàng. Gọi hàm tại đường dẫn đã cho trong window bằng giá trị cho trước
đối số 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, undefined sẽ được trả về. Chiến lược phát hành đĩa đơn
8 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 giá trị cho
đường dẫn không tồn tại hoặc không tham chiếu đến một hàm, undefined sẽ là
bị trả lại.
Cú pháp
callInWindow(pathToFunction, argument [, argument2,... argumentN])
Tham số
| Thông số | Loại | 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 tới
. |
args |
* | Các đối số cần truyền vào 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 lệnh gọi đến một hàm diễn ra không đồng bộ. Chức năng này sẽ là
đượ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ị được tìm thấy tại khoá đã cho nếu đó là kiểu, hàm hoặc đối tượng nguyên thuỷ
cố định hoặc undefined nếu không.
Cú pháp
copyFromDataLayer(key[, dataLayerVersion])
Tham số
| Thông số | Loại | Mô tả |
|---|---|---|
key |
string | Khoá có định dạng "a.b.c". |
dataLayerVersion |
số | Dữ liệu không bắt buộc phiên bản lớp. 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
copyFromWindow
Sao chép một biến từ đối tượng window. Nếu giá trị trong window không được
được ánh xạ trực tiếp tới một loại được hỗ trợ trong JavaScript hộp cát, thì undefined sẽ được
đã trả lại. 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à bắt 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ị. |
Các quyền được liên kết
createArgumentsQueue
Tạo một hàng đợi chứa các đối tượng đối số để hỗ trợ thẻ các giải pháp yêu cầu.
Tạo một hàm trong phạm vi toàn cục (ví dụ: window), sử dụng đối số fnKey
(cùng ngữ nghĩa như createQueue). Sau khi hàm được tạo, API này thì
sẽ tạo một mảng trong window (nếu chưa có) bằng arrayKey
đối số.
Khi hàm được tạo trong fnKey được gọi, hàm này sẽ đẩy các đối số
vào mảng được tạo trong arrayKey. Giá trị trả về của API là
được tạo trong fnKey.
Hàm này yêu cầu chế độ cài đặt đọc và ghi cho fnKey và arrayKey trên
quyền access_globals.
Ví dụ:
const gtag = createArgumentsQueue('gtag', 'dataLayer');
gtag('set', {'currency': 'USD'});
Cú pháp
createArgumentsQueue(fnKey, arrayKey)
Tham số
| Thông số | Loại | Mô tả |
|---|---|---|
fnKey |
string | Đường dẫn trong window nơi hàm được đặt (nếu có)
chưa tồn tại. Đối số này hỗ trợ ký hiệu dấu chấm chuẩn. Nếu
đường dẫn của khoá không tồn tại, hệ thống sẽ gửi một ngoại lệ. Tức là, nếu
fnKey là 'one.two', nó sẽ gửi một
ngoại lệ. |
arrayKey |
string | Đường dẫn trong window nơi mảng được đặt, nếu chưa
đã tồn tại. Đối số này hỗ trợ ký hiệu dấu chấm chuẩn. Nếu
đường dẫn của khoá không tồn tại, hệ thống sẽ gửi một ngoại lệ. Tức là, nếu
arrayKey là 'one.two' và không có
đối tượng toàn cục có tên 'one', nó sẽ gửi một
ngoại lệ. |
Các 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 giá trị
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 mà trong đó mảng được đặt, nếu chưa
đã tồn tại. Đối số này hỗ trợ ký hiệu dấu chấm chuẩn. Nếu
đường dẫn của khoá không tồn tại, 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 có tên 'one', nó sẽ gửi một
ngoại lệ. |
Các quyền được liên kết
decodeUri
Giải mã mọi ký tự đã mã hoá trong URI được cung cấp. Trả về một chuỗi
biểu thị URI được giải mã. Trả về undefined khi được cung cấp với giá trị không hợp lệ
đầu vào.
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 | URI đã được mã hoá bằng
encodeUri()
hoặc bằng các cách khác. |
Các quyền được liên kết
Không có.
decodeUriComponent
Giải mã mọi ký tự đã mã hoá trong thành phần URI được cung cấp. Trả về a
chuỗi đại diện cho thành phần URI được giải mã. Trả về undefined khi
có 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)
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 cách khác. |
Các quyền được liên kết
Không có.
encodeUri
Trả về Giá trị nhận dạng tài nguyên đồng nhất (URI) được mã hoá bằng cách thoát đặc biệt
ký 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 giá trị thay thế duy nhất).
Ví dụ:
sendPixel('https://www.example.com/' + encodeUri(pathInput));
Cú pháp
encodeUri(uri)
Tham số
| Thông số | Loại | Mô tả |
|---|---|---|
uri |
string | Một URI hoàn chỉnh. |
Các quyền được liên kết
Không có.
encodeUriComponent
Trả về Giá trị nhận dạng tài nguyên đồng nhất (URI) được mã hoá bằng cách thoát đặc biệt
ký 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 giá trị thay thế duy nhất).
Ví dụ:
sendPixel('https://www.example.com/?' + encodeUriComponent(queryInput));
Cú pháp
encodeUriComponent(str)
Tham số
| Thông số | Loại | Mô tả |
|---|---|---|
str |
string | Một thành phần của URI. |
Các quyền được liên kết
Không có.
fromBase64
API fromBase64 cho phép bạn giải mã các chuỗi từ base64 của các chuỗi đó
đại diện. Trả về undefined khi cho giá trị nhập 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 mã hóa 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ề số (số nguyên) ngẫu nhiên trong dải ô cho trước.
Cú pháp
generateRandom(min, max)
Tham số
| Thông số | Loại | 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 có.
getContainerVersion
Trả về một đối tượng chứa dữ liệu về vùng chứa hiện tại. Được trả về đối tượng 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
getCookieValues
Trả về giá trị của tất cả cookie có tên cho sẵn.
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 liệu giá trị cookie có được giải mã bằng
JavaScript
decodeURIComponent(). Mặc định là
true. |
Các 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 các 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ả 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, sau đó:
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 mọi khoá truy vấn).
getReferrerQueryParameters
API getReferrerQueryParameters hoạt động giống như getQueryParameters,
ngoại trừ việc nó hoạt động trên đường liên kết giới thiệu thay vì URL hiện tại. Trả về giá trị đầu tiên hoặc
tất cả các tham số cho queryKey của đường liên kết giới thiệu đã cho. Trả về giá trị đầu tiên
giá trị 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ả 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, sau đó:
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 mọi khoá truy vấn).
getReferrerUrl
Cho trước 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à sẽ 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 là đã chỉ định, thì URL liên kết giới thiệu đầy đủ sẽ được trả về.
Cú pháp
getReferrerUrl([component])
Tham số
| Thông số | Loại | Mô tả |
|---|---|---|
component |
string | Thành phần cần trả về từ URL. Có thể là một trong những trạng thái sau đây:
protocol, host, port
path, query, extension. Nếu
component mới 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ẽ
đã trả lại. |
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 mọi khoá truy vấn).
getTimestamp
Không dùng nữa. Ưu tiên getTimestampMillis.
Trả về number biểu thị thời gian hiện tại tính bằng mili giây kể từ Unix
thời gian bắt đầu của hệ thống, được Date.now() trả về.
Cú pháp
getTimestamp();
Các quyền được liên kết
Không có.
getTimestampMillis
Trả về number biểu thị thời gian hiện tại tính bằng mili giây kể từ Unix
thời gian bắt đầu của hệ thống, được Date.now() trả về.
Cú pháp
getTimestampMillis();
Các 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 khác 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 |
"không xác định" |
null |
"null" |
true |
"boolean" |
12 |
"number" |
'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 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, cho sẵn loại thành phần và một số thông 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:
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,
toàn bộ giá trị href sẽ được trả về. |
Các quyền được liên kết
gtagSet
Đẩy một lệnh gtag set đến lớp dữ liệu và lệnh này sẽ được xử lý ngay khi có thể thực hiện sau khi sự kiện hiện tại và mọi thẻ mà sự kiện đó kích hoạt kết thúc (hoặc đã hết thời gian chờ xử lý thẻ). Bản cập nhật được đảm bảo được xử lý trong vùng chứa này trước bất kỳ mục nào được xếp hàng đợi trong lớp dữ liệu hàng đợi.
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ì
bản cập nhật sẽ được áp dụng trước khi xử lý sự kiện Khởi chạy. Ví dụ
sẽ là ads_data_redaction được đặt thành true, false hoặc url_passthrough
đang đượ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 chung cho các thuộc tính chứa nó. |
Các 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á được chỉ định. Nếu dữ liệu đầu vào vào gtagSet là một đối tượng thuần tuý, API sẽ kiểm tra
để có quyền ghi vào tất cả các khoá đã làm phẳng bên trong đối tượng đó, ví dụ: với
gtagSet({foo: {bar: 'baz'}}), API sẽ kiểm tra việc ghi
quyền cho foo.bar.
Nếu dữ liệu đầu vào vào gtagSet là một khoá và một giá trị đối tượng không phải đơn thuần, API sẽ
hãy kiểm tra quyền ghi vào khoá đó, ví dụ: trong gtagSet('abc', true) ,
API sẽ kiểm tra quyền ghi vào 'abc'.
Lưu ý rằng nếu có chu kỳ trong đối tượng nhập, chỉ các khoá trước khi đạt đến cùng một đối tượng sẽ được kiểm tra.
injectHiddenIframe
Thêm 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 JavaScript các hàm gọi qua.
Cú pháp
injectHiddenIframe(url, onSuccess)
Tham số
| Thông số | Loại | Mô tả |
|---|---|---|
url |
string | URL được sử dụng làm giá trị của 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
injectScript
Thêm thẻ tập lệnh vào trang để tải không đồng bộ URL đã cho. Chiến lược phát hành đĩa đơn lệnh gọi lại được cung cấp dưới dạng thực thể hàm và được gói trong JavaScript các hàm gọi qua.
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 tuỳ chọn dùng để cho biết URL đã cho cần được lưu vào bộ nhớ đệm. Nếu
giá trị này được chỉ định, chỉ một phần tử tập lệnh sẽ được tạo
yêu cầu JavaScript. Bất kỳ lần thử tải nào nữa sẽ dẫn đến
phương thức onSuccess và onFailure đã cho
đượ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
isConsentGranted
Trả về true nếu loại đồng ý đã chỉ định được đồng ý.
Sự đồng ý cho một loại đồng ý cụ thể được coi là đồng ý nếu sự đồng ý đó loại đã được đặt thành "đã cấp" hoặc không được đặt. Nếu loại đồng ý được đặt thành bất kỳ giá trị nào khác, thì 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 phần cài đặt thẻ sẽ cung cấp một lựa chọn để luôn luôn
bốc cháy. Nếu một thẻ luôn bật tính năng kích hoạt sử dụng API này, thì trạng thái đồng ý sẽ được xem xét
đã đượ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 ý để kiểm tra trạng thái. |
Các quyền được liên kết
Quyền access_consent có quyền đọc đối với loại đồ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 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ị nhập không phải là một chuỗi, thì
giá trị nhập vào sẽ được buộc 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 giá trị
không thể phân tích cú pháp (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à một chuỗi, thông tin đầu vào sẽ là bị buộc thành một 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);
Các 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ý 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])
Tham số
| Thông số | Loại | Mô tả |
|---|---|---|
obj1 [, obj2,... objN] |
bất kỳ | Đối số |
Các 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. |
Các quyền được liên kết
Không có.
makeNumber
Chuyển đổi giá trị đã cho thành số.
Cú pháp
makeNumber(value)
Tham số
| Thông số | Loại | Mô tả |
|---|---|---|
value |
bất kỳ | Giá trị cần chuyển đổi. |
Các 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. |
Các quyền được liên kết
Không có.
makeTableMap
Chuyển đổi một đối tượng bảng đơn giản có 2 cột thành Map. Thông tin này dùng để
thay đổi trường mẫu SIMPLE_TABLE có hai cột thành trường dễ quản lý hơn
.
Ví dụ: hàm này có thể chuyển đổi một đối tượng của bảng:
[
{'key': 'k1', 'value': 'v1'},
{'key': 'k2', 'value': 'v2'}
]
vào một Bản đồ:
{
'k1': 'v1',
'k2': 'v2'
}
Trả về Object (Đối tượng): Map được chuyển đổi nếu các cặp khoá-giá trị đã được thêm vào
hoặc null nếu không có.
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. Đó là danh sách các bản đồ mà 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à cột
giá trị trong hàng. |
keyColumnName |
string | Tên của cột mà các giá trị sẽ trở thành khóa trong dữ liệu được chuyển đổi
Map. |
valueColumnName |
string | Tên của cột mà các giá trị sẽ trở thành giá trị trong cột được chuyển đổi
Map. |
Các 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ố
Tham số hàm toán học được chuyển đổi thành số.
Các 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 Object.keys() Thư viện chuẩn
hành vi. Phương thức này trả về một mảng thuộc tính có thể liệt kê riêng của một đối tượng nhất định
theo thứ tự tương tự như vòng lặp for...in.... Nếu giá trị nhập là
không phải là đối tượng, nó sẽ bị ép buộc thành một đối tượng.
Phương thức values() cung cấp Object.values() Thư viện chuẩn
hành vi. Phương thức này trả về một mảng các giá trị thuộc tính có thể liệt kê của riêng một đối tượng nhất định
theo thứ tự tương tự như vòng lặp for...in.... Nếu giá trị đầu vào không phải là một
thì nó sẽ bị ép gán thành một đối tượng.
Phương thức entries() cung cấp Object.entries() Thư viện chuẩn
hành vi. Phương thức này trả về một mảng thuộc tính có thể liệt kê riêng của một đối tượng nhất định
[key, value] ghép nối theo thứ tự mà vòng lặp for...in... sẽ thực hiện. Nếu
giá trị đầu vào không phải là một đối tượng, nó sẽ bị buộc thành một đối tượng.
Phương thức freeze() cung cấp Object.freeze() Thư viện chuẩn
hành vi. Không thể thay đổi đối tượng cố định nữa; việc đóng băng một vật thể sẽ giúp ngăn chặn
tài sản mới được thêm vào tài sản đó, các tài sản hiện có sẽ không bị xoá,
và giá trị của các thuộc tính hiện tại bị thay đổi. freeze() trả về
chính là đối tượng đã được truyền vào. Đối số nguyên thuỷ hoặc đối số rỗng sẽ được coi là
nếu đó là một đối tượng cố định và sẽ được trả về.
Phương thức delete() cung cấp toán tử xoá của Thư viện chuẩn
hành vi. Thao tác này sẽ xoá khoá đã cho khỏi đối tượng trừ phi đối tượng bị cố định.
Giống như toán tử xoá Thư viện chuẩn, hàm này sẽ trả về true nếu giá trị nhập đầu tiên
giá trị (objectInput) là một đối tượng không bị cố định ngay cả khi giá trị nhập vào thứ hai
giá trị (keyToDelete) chỉ định khoá không tồn tại. Hàm này sẽ trả về false trong
tất cả các trường hợp khác. Tuy nhiên, toán tử này khác với toán tử xoá trong Thư viện chuẩn
theo các cách sau:
keyToDeletekhông được là chuỗi được phân tách bằng dấu chấm để chỉ định một khoá lồng nhau.- Không thể sử dụng
delete()để xoá các phần tử khỏi một mảng. - Không thể sử dụng
delete()để xoá bất kỳ thuộc tính nào khỏi phạm vi chung.
Cú pháp
Object.keys(objectInput)
Object.values(objectInput)
Object.entries(objectInput)
Object.freeze(objectInput)
Object.delete(objectInput, keyToDelete)
Tham số
Object.keys
| Thông số | Loại | Mô tả |
|---|---|---|
| objectInput | 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ì sẽ bị ép buộc thành một đố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, nó sẽ bị ép buộc thành một đố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à thì nó sẽ bị ép gán thành một đối tượng. |
Object.freeze
| Thông số | Loại | Mô tả |
|---|---|---|
| objectInput | bất kỳ | Đối tượng cần cố định. Nếu dữ liệu đầu vào không phải là đối tượng, thì nó sẽ được coi là một vật cố định. |
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 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. Để định dạng đúng
Các URL, 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, là một đối tượng trống.
Đối tượng được trả về sẽ có các trường sau:
{
href: string,
origin: string,
protocol: string,
username: string,
password: string,
host: string,
hostname: string,
port: string,
pathname: string,
search: string,
searchParams: Object<string, (string|Array)>,
hash: string,
}
Ví dụ
const parseUrl = require('parseUrl');
const urlObject = parseUrl('https://abc:xyz@example.com:8080/foo?param=val%2Cue#bar');
Cú pháp
parseUrl(url);
Tham số
| Thông số | Loại | Mô tả |
|---|---|---|
url |
string | URL đầy đủ sẽ được phân tích cú pháp. |
Các quyền được liên kết
Không có.
queryPermission
Truy vấn các quyền được phép và bị thu hẹp. Trả về một boolean: true nếu một
quyền đã được cấp, nếu không thì false.
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ố của hàm sẽ khác nhau tuỳ theo quyền được truy vấn. Xem Đố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
đã viết hoặc đã đọc.
readUrl: Không cần đối số bổ sung để truy vấn xem toàn bộ
URL có thể đọc được. Để truy vấn xem một thành phần nhất định có thể được đọc hay không, hãy chuyển phương thức
tên thành phần làm đối số thứ hai:
if (queryPermission('readUrl','port')) {
// read the port
}
Để kiểm tra xem khoá truy vấn cụ thể có đọc được hay không, hãy chuyể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 có.
readCharacterSet
Trả về giá trị của document.characterSet.
Cú pháp
readCharacterSet()
Tham số
Không có.
Cá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ó.
Các quyền được liên kết
require
Nhập hàm tích hợp sẵn theo tên. Trả về một hàm hoặc đối tượng có thể được gọi 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 sẵn.
Cú pháp
require(name)
Tham số
| Thông số | Loại | Mô tả |
|---|---|---|
name |
string | Tên 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 có.
sendPixel
Gửi yêu cầu GET đến một điểm cuối URL đã chỉ định.
Cú pháp
sendPixel(url, onSuccess, onFailure)
Tham số
| Thông số | Loại | Mô tả |
|---|---|---|
url |
string | 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 gửi thành công, thì các trình duyệt có thể yêu cầu phản hồi hình ảnh hợp lệ để để chạy onSuccess. |
onFailure |
hàm | Được gọi khi pixel không tải được. Lưu ý: ngay cả khi yêu cầu gửi thành công, onFailure có thể chạy nếu máy chủ không trả về một phản hồi hình ảnh hợp lệ. |
Các quyền được liên kết
setCookie
Đặt hoặc xoá cookie có tên, giá trị và tuỳ chọn được chỉ định.
Cú pháp
setCookie(name, value[, options, encode])
Tham số
| Thông số | Loại | Mô tả |
|---|---|---|
name |
string | Tên của cookie. |
value |
string | Giá trị của cookie. |
options |
đối tượng | Chỉ định Miền, Các thuộc tính Đường dẫn, Hết hạn, Độ tuổi tối đa, Bảo mật và SameSite. (Xem Tùy chọn bên dưới.) |
encode |
boolean | Kiểm soát việc giá trị cookie có được mã hoá bằng
JavaScript
encodeURIComponent().
Mặc định là true. |
- Miền: do tài sản
options['domain']đặt (nếu có). Đặt giá trị này vào'auto'để cố gắng ghi cookie bằng miền rộng nhất có thể, dựa vào vị trí tài liệu. Nếu không thành công, Chrome sẽ thử liên tụ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, máy chủ sẽ cố gắng ghi cookie mà không cần miền. Nếu bạn không đặt giá trị nào, tác vụ này sẽ cố gắng ghi cookie mà không chỉ định miền. Lưu ý: khi cookie không có miền được chỉ định là được ghi vàodocument.cookie, thì tác nhân người dùng sẽ mặc định miền của cookie vào máy chủ lưu trữ của vị trí tài liệu hiện tại. - Path (Đường dẫn): do
options['path']đặt, nếu có. Khi cookie không có đường dẫn đã chỉ định được ghi vàodocument.cookie, thì 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. - Độ 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ó, thông số này phải là chuỗi ngày theo định dạng UTC.Date.toUTCString()có thể được sử dụng để định dạng mộtDatecho tham số này. - Secure: do
options['secure']đặt, nếu có. - SameSite: do
options['samesite']đặt, nếu có.
Các quyền được liên kết
setDefaultConsentState
Đưa nội dung cập nhật mặc định về sự đồng ý lên lớp dữ liệu và được xử lý ngay khi có thể thực hiện sau khi sự kiện hiện tại và mọi thẻ mà sự kiện đó kích hoạt kết thúc (hoặc đã hết thời gian chờ xử lý thẻ). Bản cập nhật được đảm bảo được xử lý trong vùng chứa này trước bất kỳ mục nào được xếp hàng đợi 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)
Tham số
| Thông số | Loại | Mô tả |
|---|---|---|
consentSettings |
đối tượng | Đối tượng xác định trạng thái mặc định cho sự đồng ý đã chỉ định loại. |
Đối tượng consentSettings là mối liên kết các chuỗi loại đồng ý tuỳ ý đến
một trong số 'granted' hoặc 'denied'. Định dạng 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 đồng ý thành ""đã đồng ý"" hoặc "đã từ chối". Bất kỳ giá trị nào khác với "'đã cấp"" sẽ được coi là "đã từ chối". Chế độ cài đặt giá trị thành `không xác định` sẽ không có bất kỳ ảnh hưởng nào đến giá trị trước đó của nó. |
region |
Mảng | Một mảng mã vùng tuỳ chọn xác định khu vực mà áp dụng chế độ cài đặt lấy sự đồng ý. Mã vùng được thể hiện theo quốc gia và/hoặc phân mục theo định dạng ISO 3166-2. |
wait_for_update |
số | Chỉ định một giá trị mili giây để kiểm soát thời gian chờ trước khi dữ liệu đã gửi. Được dùng với các công cụ lấy 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
đồng ý.
setInWindow
Đặt giá trị đã cho trong window ở 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ể
sự hiện diện của một giá trị hiện có. Trả về một boolean: true nếu giá trị là
được đặt thành công và nếu không thì false.
Cú pháp
setInWindow(key, value, overrideExisting)
Tham số
| Thông số | Loại | Mô tả |
|---|---|---|
key |
string | Khoá trong window để đặt giá trị vào. |
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ị nào trong đó hay không. |
Các quyền được liên kết
sha256
Tính toán chuỗi đại diện SHA-256 của đầu vào và gọi lệnh gọi lại bằng hàm
chuỗi đại diện được mã hoá theo base64, trừ phi đối tượng options chỉ định một chuỗi đại diện khác
mã hoá đầu ra.
Ví dụ:
sha256('inputString', (digest) => {
sendPixel('https://example.com/collect?id=' + digest);
data.gtmOnSuccess();
}, data.gtmOnFailure);
sha256('inputString', (digest) => {
sendPixel('https://example.com/collect?id=' + digest);
data.gtmOnSuccess();
}, data.gtmOnFailure, {outputEncoding: 'hex'});
Cú pháp
sha256(input, onSuccess, onFailure = undefined, options = undefined)
Tham số
| Thông số | Loại | Mô tả |
|---|---|---|
input |
string | Chuỗi cần tính toán hàm băm. |
onSuccess |
hàm | Được gọi bằng thông báo kết quả, được mã hoá trong base64, trừ khi
Đố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ó hỗ trợ gốc dành cho sha256. Lệnh gọi lại được gọi với một đối tượng chứa tên lỗi và thông báo. |
options |
đối tượng | Không bắt buộc đối tượng tuỳ chọn để chỉ định phương thức mã hoá đầu ra. Nếu
đã 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 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. Mẫu cho phép chia sẻ dữ liệu qua các lần thực thi một mẫu duy nhất. Dữ liệu được lưu trữ trong bộ nhớ mẫu sẽ tồn tại trong suốt thời gian 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();
Các 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 giá trị biểu diễn base64.
Cú pháp
toBase64(input)
Tham số
| Thông số | Loại | Mô tả |
|---|---|---|
input |
string | Chuỗi cần mã hoá. |
Ví dụ
const toBase64 = require('toBase64');
const base64Hello = toBase64('hello');
Các quyền được liên kết
Không có
updateConsentState
Đưa 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 này được đảm bảo được xử lý trong vùng chứa này trước bất kỳ mục nào được xếp hàng đợi trong lớp dữ liệu. Tìm hiểu thêm về sự đồng ý.
Ví dụ:
const updateConsentState = require('updateConsentState');
updateConsentState({
'ad_storage': 'granted',
'analytics_storage': 'denied',
'third_party_storage': 'granted',
});
Cú pháp
updateConsentState(consentSettings)
Tham số
| Thông số | Loại | Mô tả |
|---|---|---|
consentSettings |
đối tượng | Một đối tượng cập nhật trạng thái của các loại đồng ý đã chỉ định. |
Đối tượng consentSettings là mối liên kết các chuỗi loại đồng ý tuỳ ý đến
một trong số 'granted' hoặc 'denied'. Định dạng 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 đồng ý thành "đã đồng ý" hoặc "bị từ chối". Bất kỳ giá trị nào khác với giá trị " đã cấp" sẽ được coi là "bị từ chối". Chế độ cài đặt giá trị thành "không xác định" sẽ không có bất kỳ ảnh hưởng nào đến giá trị trước đó của nó. |
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
đồng ý.
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 tính năng 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ó require()
tuyên bố. 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 xác nhận về API nhất định.
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 như đượ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á 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 để xác nhận một cách trôi chảy về giá trị của một đối tượng. Một
lỗi xác nhận sẽ dừng kiểm thử ngay lập tức và đánh dấu là không thành công. Tuy nhiên,
lỗi trong một kiểm thử sẽ không ảnh hưởng đến các trường hợp kiểm thử khác.
Cú pháp
assertThat(actual, opt_message)
Tham số
| Thông số | Loại | Mô tả |
|---|---|---|
actual |
bất kỳ | Giá trị dùng trong quá trình kiểm tra mức độ 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. |
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ủ thể không phải là undefined. |
isNull() |
Xác nhận rằng chủ đề là null. |
isNotNull() |
Xác nhận rằng chủ thể 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ủ đề này là sai sự thật. Giá trị sai lệch là
undefined, null, false
NaN, 0 và '' (chuỗi trống). |
isTruthy() |
Xác nhận rằng đối tượng là sự thật. Giá trị sai lệch là
undefined, null, false
NaN, 0 và '' (chuỗi trống). |
isNaN() |
Xác nhận rằng đối tượng là giá trị NaN. |
isNotNaN() |
Xác nhận rằng đối tượng là giá trị bất kỳ ngoài NaN. |
isInfinity() |
Xác nhận rằng đối tượng là vô cực tích cực hay tiêu cực. |
isNotInfinity() |
Xác nhận rằng đối tượng là bất kỳ giá trị nào ngoài giá trị tích cực hoặc tiêu cực Vô hạn. |
isEqualTo(expected) |
Xác nhận rằng tiêu đề bằng với giá trị đã cho. Đây là một giá trị so sánh chứ không phải so sánh tham chiếu. Nội dung của đối tượng và mảng được so sánh đệ quy. |
isNotEqualTo(expected) |
Xác nhận rằng đối tượng không bằng với giá trị đã cho. Đây là một so sánh giá trị, không phải là so sánh tham chiếu. Nội dung của đối tượng và các mảng được so sánh đệ quy. |
isAnyOf(...expected) |
Xác nhận rằng tiêu đề bằng một trong các giá trị đã cho. Đây là một so sánh giá trị, không phải là so sánh tham chiếu. Nội dung của đối tượng và các mảng được so sánh đệ quy. |
isNoneOf(...expected) |
Xác nhận rằng chủ thể không bằng bất kỳ giá trị nào đã cho. Chiến dịch này là so sánh giá trị chứ không phải là so sánh tham chiếu. Nội dung của đối tượng và mảng được so sánh đệ quy. |
isStrictlyEqualTo(expected) |
Xác nhận rằng chủ thể hoàn toàn ngang bằng (===) với
giá trị nhất định. |
isNotStrictlyEqualTo(expected) |
Xác nhận rằng chủ thể không hoàn toàn ngang bằng (!==) với
giá trị đã cho. |
isGreaterThan(expected) |
Xác nhận rằng chủ thể lớn hơn (>) giá trị đã cho
giá trị trong một phép so sánh theo thứ tự. |
isGreaterThanOrEqualTo(expected) |
Xác nhận rằng chủ thể lớn hơn hoặc bằng
(>=) giá trị đã cho trong phép so sánh theo thứ tự. |
isLessThan(expected) |
Xác nhận rằng chủ thể dưới (<) giá trị đã cho
giá trị trong một phép so sánh theo 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 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à thông tin so sánh giá trị, không phải để tham khảo so sánh. Nội dung của đối tượng và mảng được so sánh theo cách đệ quy. |
doesNotContain(...expected) |
Xác nhận rằng chủ đề là một mảng hoặc chuỗi không chứa các giá trị đã cho. Đây là thông tin so sánh giá trị, không phải là thông tin so sánh tham chiếu. Nội dung của đối tượng và mảng được so sánh theo cách đệ quy. |
containsExactly(...expected) |
Xác nhận rằng tiêu đề là một mảng chứa tất cả các giá trị theo thứ tự bất kỳ và không có giá trị nào khác. Đây là thông tin so sánh giá trị, không phải so sánh tham chiếu. Nội dung của đối tượng và mảng được so sánh theo cách đệ quy. |
doesNotContainExactly(...expected) |
Xác nhận rằng tiêu đề là một mảng chứa một nhóm khác từ các giá trị đã cho theo thứ tự bất kỳ. Đây là một bảng so sánh giá trị, không phải là so sánh tham chiếu. Nội dung của đối tượng và mảng là được so sánh theo cách đệ quy. |
hasLength(expected) |
Xác nhận rằng chủ đề 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ột 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 (length = 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 . |
isNotEmpty() |
Xác nhận rằng chủ đề 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 của chủ đề là một mảng. |
isBoolean() |
Xác nhận rằng kiểu của chủ đề là một boolean. |
isFunction() |
Xác nhận rằng kiểu của chủ đề là một hàm. |
isNumber() |
Xác nhận rằng kiểu của chủ đề là một số. |
isObject() |
Xác nhận rằng kiểu của chủ thể là một đối tượng. |
isString() |
Xác nhận rằng kiểu 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 vượt qua chương trình 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);
Tham số
| Thông số | Loại | 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 API Hộp cát. Bản mô phỏng
Bạn có thể sử dụng API an toàn trong mã mẫu, nhưng chỉ hoạt động ở chế độ thử nghiệm.
Hệ thống sẽ đặt lại các thông tin mô phỏng trước khi chạy mỗi lượt 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 để mô phỏng; cùng một chuỗi như đượ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 trong
thay thế của API Hộp cát; nếu returnValue là giá trị khác
hơn một hàm, thì giá trị đó sẽ được trả về thay cho Hộp cát
API. |
Ví dụ
mock('encodeUri', "https://endpoint.example.com/?account=12345");
mock('sendPixel', function(url, onSuccess, onFailure) {
onSuccess();
});
mockObject
API mockObject cho phép bạn ghi đè hành vi của các API Hộp cát
trả về một đối tượng. API này an toàn để sử dụng trong mã mẫu, nhưng vẫn hoạt động được
chỉ ở chế độ thử nghiệm. Hệ thống sẽ đặt lại các thông tin mô phỏng trước khi chạy mỗi lượt 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 để mô phỏng; cùng một chuỗi như đượ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ẻ Mã, trong môi trường kiểm thử hiện tại bằng 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 được dùng trong kiểm thử. |
Giá trị trả về
Trả về giá trị của một biến cho các mẫu biến; trả về undefined với giá
tất cả các loại mẫu khác.
Ví dụ
runCode({field1: 123, field2: 'value'});