カスタム テンプレート API

コア API

以下の API はサンドボックス化された JavaScript と連携して、Google タグ マネージャーでカスタム テンプレートを作成します。各 API は require() ステートメントとともに追加されます。たとえば、次のとおりです。

const myAPI = require('myAPI');

addConsentListener

指定された同意タイプの状態が変化したときに実行するリスナー関数を登録します。

指定された同意タイプの状態が denied から granted、または granted から denied に変わるたびに、特定のリスナーが呼び出されます。状態のない同意タイプは granted とみなされるため、未設定の同意タイプが更新されて granted に変わった場合、リスナーは呼び出されません。リスナー関数は、コードを適切な回数だけ実行する役割を担っています。

例:

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

構文

addConsentListener(consentType, listener)

パラメータ

パラメータ タイプ 説明
consentType 文字列 状態の変化をリッスンする同意タイプ。
listener 関数 指定された同意タイプの状態が変化したときに実行する関数。

リスナーが呼び出されると、変更される同意タイプとその同意タイプの新しい値が渡されます。

パラメータ タイプ 説明
consentType 文字列 変更される同意タイプ。
granted boolean 指定された同意タイプが granted に変更される場合に true となるブール値。

関連付けられているアクセス権

同意タイプの読み取り権限を持つ access_consent


addEventCallback

addEventCallback API を使用すると、イベントの終了時に呼び出されるコールバック関数を登録できます。コールバックは、イベントのすべてのタグが実行されるか、ページ内イベントがタイムアウトになると呼び出されます。コールバックには 2 つの値が渡されます。1 つは、この関数を呼び出すコンテナの ID で、もう 1 つは、イベントに関する情報が含まれたオブジェクトです。

構文

addEventCallback(callback)

パラメータ

パラメータ タイプ 説明
callback 関数 イベントの終了時に呼び出す関数。

eventData オブジェクトには、以下のデータが格納されます。

キー名 タイプ 説明
tags 配列 タグデータ オブジェクトの配列。イベント中に呼び出されたすべてのタグのオブジェクトが、この配列に含まれます。タグデータ オブジェクトには、タグの ID(id)、実行ステータス(status)、実行時間(executionTime)が含まれます。タグデータには、そのタグで設定されている追加のタグメタデータも含まれます。

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

関連付けられているアクセス権

read_event_metadata


aliasInWindow

aliasInWindow API を使用すると、エイリアス(例: window.foo = window.bar)を作成できるため、エイリアスを必要とする特定のタグをサポートできます。fromPath にある window オブジェクトの値を toPathwindow オブジェクトのキーに割り当てます。成功した場合は true、失敗した場合は false を返します。

構文

aliasInWindow(toPath, fromPath)

パラメータ

パラメータ タイプ 説明
toPath 文字列 値のコピー先となる window オブジェクトへのドット区切りのパス。最後のコンポーネントまでのパスにあるすべてのコンポーネントは、window オブジェクトにすでに存在している必要があります。
fromPath 文字列 値のコピー元となる window へのドット区切りのパス。値が存在しない場合、操作は失敗します。

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

関連付けられているアクセス権

access_globalstoPathfromPath の両方で必要となります。toPath には書き込み権限、fromPath には読み取り権限が必要です。


callInWindow

window オブジェクトのパスから関数を呼び出すことができます(この動作はポリシーによって制御されます)。指定された引数を使用して window 内の指定されたパスで関数を呼び出し、値を返します。戻り型がサンドボックス化された JavaScript でサポートされている型に直接マップできない場合は、undefined を返します。サンドボックス化された JavaScript でサポートされている 8 つの型は、nullundefinedbooleannumberstringArrayObjectfunction です。指定したパスが存在しなかったり、関数を参照していなかったりする場合は、undefined を返します。

構文

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

パラメータ

パラメータ タイプ 説明
pathToFunction 文字列 window 内で呼び出す関数へのドット区切りのパス。
args * 関数に渡す引数。

関連付けられているアクセス権

execute 権限が有効な access_globals


callLater

関数の呼び出しが非同期的に行われるように、呼び出しをスケジュール設定します。この関数は、現在のコードがリターンすると呼び出されます。setTimeout(<function>, 0) と同じです。

構文

callLater(function)

パラメータ

パラメータ タイプ 説明
function 関数 呼び出す関数。

copyFromDataLayer

データレイヤー内の特定のキーに現在割り当てられている値を返します。プリミティブ型、関数、オブジェクト リテラルの場合は指定されたキーで見つかった値、そうでない場合は undefined です。

構文

copyFromDataLayer(key[, dataLayerVersion])

パラメータ

パラメータ タイプ 説明
key 文字列 「a.b.c」形式のキー。
dataLayerVersion 数値 オプションのデータレイヤー バージョン。デフォルト値は 2 です。値 1 を使用することを強くおすすめします。

関連付けられているアクセス権

read_data_layer


copyFromWindow

window オブジェクトから変数をコピーします。window の値がサンドボックス化された JavaScript でサポートされている型に直接マップできない場合、undefined を返します。サンドボックス化された JavaScript でサポートされている 8 つの型は、nullundefinedbooleannumberstringArrayObjectfunction です。取得された(また強制変換された)値を返します。

構文

copyFromWindow(key)

パラメータ

パラメータ タイプ 説明
key 文字列 window で値をコピーするキー。

関連付けられているアクセス権

access_globals


createArgumentsQueue

引数オブジェクトが並んだキューを作成して、それを必要とするタグ ソリューションに提供します。

fnKey 引数(createQueue と同じセマンティクス)を使用して、グローバル スコープ(つまり window)内に関数を作成します。関数が作成された後、この API は、arrayKey 引数を使用して window に配列を作成します(まだ存在しない場合)。

fnKey で作成された関数が呼び出されると、引数オブジェクトが arrayKey 下に作成された配列にプッシュされます。API の戻り値は、fnKey 下に作成された関数です。

この関数には、access_globals 権限に対する fnKeyarrayKey の読み取りおよび書き込み設定が必要です。

例:

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

構文

createArgumentsQueue(fnKey, arrayKey)

パラメータ

パラメータ タイプ 説明
fnKey 文字列 関数が設定されている window 内のパス(存在しない場合)。この引数は、標準のドット表記をサポートしています。キーのパスが存在しない場合、例外がスローされます。つまり、fnKey'one.two' の場合、例外がスローされます。
arrayKey 文字列 配列が設定されている window のパス(まだ存在しない場合)。この引数は、標準のドット表記をサポートしています。キーのパスが存在しない場合、例外がスローされます。つまり、arrayKey'one.two' で、'one' という名前のグローバル オブジェクトがない場合、例外がスローされます。

関連付けられているアクセス権

access_globals


createQueue

window に配列を作成し(まだ作成していない場合)、その配列に値をプッシュする関数を返します。

この関数には、access_globals 権限に対する arrayKey の読み取りおよび書き込み設定が必要です。

例:

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

構文

createQueue(arrayKey)

パラメータ

パラメータ タイプ 説明
arrayKey 文字列 配列が設定されている window のキー(まだ存在しない場合)。この引数は、標準のドット表記をサポートしています。キーのパスが存在しない場合、例外がスローされます。たとえば、arrayKey'one.two' で、'one' という名前のグローバル オブジェクトがない場合、例外がスローされます。

関連付けられているアクセス権

access_globals


decodeUri

指定された URI でエンコードされた文字をデコードします。デコードされた URI コンポーネントを表す文字列を返します。無効な入力がある場合、undefined を返します。

例:

const decode = require('decodeUri');

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

構文

decodeUri(encoded_uri)

パラメータ

パラメータ タイプ 説明
encoded_uri 文字列 encodeUri() またはその他の方法でエンコードされた URI。

関連付けられているアクセス権

なし。


decodeUriComponent

指定された URI コンポーネント内のエンコードされた文字をデコードします。デコードされた URI コンポーネントを表す文字列を返します。無効な入力がある場合、undefined を返します。

例:

const decode = require('decodeUriComponent');

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

構文

decodeUriComponent(encoded_uri_component)

パラメータ

パラメータ タイプ 説明
encoded_uri_component 文字列 encodeUriComponent() またはその他の方法でエンコードされた URI コンポーネント。

関連付けられているアクセス権

なし。


encodeUri

特殊文字をエスケープして、エンコードされた Uniform Resource Identifier(URI)を返します。提供された文字列を URI としてエンコードしたものを表す文字列を返します。無効な入力(単独のサロゲート)がある場合、undefined を返します。

例:

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

構文

encodeUri(uri)

パラメータ

パラメータ タイプ 説明
uri 文字列 完全な URI。

関連付けられているアクセス権

なし。


encodeUriComponent

特殊文字をエスケープして、エンコードされた Uniform Resource Identifier(URI)を返します。提供された文字列を URI としてエンコードしたものを表す文字列を返します。無効な入力(単独のサロゲート)がある場合、undefined を返します。

例:

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

構文

encodeUriComponent(str)

パラメータ

パラメータ タイプ 説明
str 文字列 URI のコンポーネント。

関連付けられているアクセス権

なし。


fromBase64

fromBase64 API を使うと、文字列を base64 表現からデコードできます。無効な入力がある場合、undefined を返します。

構文

fromBase64(base64EncodedString)

パラメータ

パラメータ タイプ 説明
base64EncodedString 文字列 Base64 でエンコードされた文字列。

const fromBase64 = require('fromBase64');

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

関連付けられているアクセス権

なし


generateRandom

指定範囲内の乱数(整数)を返します。

構文

generateRandom(min, max)

パラメータ

パラメータ タイプ 説明
min 数値 返される整数の潜在的な最小値。
max 数値 返される整数の潜在的な最大値。

関連付けられているアクセス権

なし。


getContainerVersion

現在のコンテナに関するデータを含むオブジェクトを返します。返されるオブジェクトには次のフィールドがあります。

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

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

構文

getContainerVersion();

関連付けられているアクセス権

read_container_data


getCookieValues

指定した名前のすべての Cookie の値を返します。

構文

getCookieValues(name[, decode])

パラメータ

パラメータ タイプ 説明
name 文字列 Cookie の名前。
decode boolean Cookie の値を JavaScript の decodeURIComponent() でデコードするかどうかを指定します。デフォルトは true です。

関連付けられているアクセス権

get_cookies


getQueryParameters

現在の URL の queryKey の最初かすべてのパラメータを返します。 queryKey から最初の値か、queryKey から値の配列を返します。

構文

getQueryParameters(queryKey[, retrieveAll])

パラメータ

パラメータ タイプ 説明
queryKey 文字列 クエリ パラメータから読み込むキー。
retrieveAll boolean すべての値を取得するかどうか。

たとえば、現在の URL が https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo の場合:

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

関連付けられているアクセス権

get_urlquery コンポーネントが許可され、許可されているクエリキーの queryKey が指定されている(または任意のクエリキーを許可する)必要があります。


getReferrerQueryParameters

getReferrerQueryParameters API は getQueryParameters と同じように動作しますが、現在の URL ではなく参照 URL に対して機能する点が異なります。指定された参照 URL の queryKey の最初のパラメータまたはすべてのパラメータを返します。queryKey から最初の値か、queryKey から値の配列を返します。

構文

getReferrerQueryParameters(queryKey[, retrieveAll])

パラメータ

パラメータ タイプ 説明
queryKey 文字列 クエリ パラメータから読み込むキー。
retrieveAll boolean すべての値を取得するかどうか。

たとえば、参照元 URL が https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo の場合:

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

関連付けられているアクセス権

get_referrerquery コンポーネントが許可され、許可されているクエリキーの queryKey が指定されている(または任意のクエリキーを許可する)必要があります。


getReferrerUrl

コンポーネント タイプを指定すると、API は参照 URL のドキュメント オブジェクトを読み取り、参照 URL の一部を表す文字列を返します。コンポーネントが指定されていない場合は、完全な参照 URL が返されます。

構文

getReferrerUrl([component])

パラメータ

パラメータ タイプ 説明
component 文字列 URL から返されるコンポーネント。以下のいずれかになります。 protocolhostportpathqueryextensioncomponentundefinednull である場合、または上記のいずれのコンポーネントにも一致しない場合は、URL 全体を返します。

関連付けられているアクセス権

get_referrerquery コンポーネントが許可され、許可されているクエリキーの queryKey が指定されている(または任意のクエリキーを許可する)必要があります。


getTimestamp

非推奨。getTimestampMillis を優先します。

現在の時刻を示す数値(Unix エポックからの経過ミリ秒数)を返します。Date.now() によって返されます。

構文

getTimestamp();

関連付けられているアクセス権

なし。


getTimestampMillis

現在の時刻を示す数値(Unix エポックからの経過ミリ秒数)を返します。Date.now() によって返されます。

構文

getTimestampMillis();

関連付けられているアクセス権

なし。


getType

指定された値の型を説明する文字列を返します。typeof とは異なり、getTypearrayobject を区別します。

構文

getType(data.someField)

次の表に、各入力値に対して返される文字列を示します。

入力値 結果
undefined 'undefined'
null 'null'
true 'boolean'
12 'number'
'string' 'string'
{ a: 3 } 'object'
[ 1, 3 ] 'array'
(x) => x + 1 'function'

関連付けられているアクセス権

なし。


getUrl

コンポーネント タイプと URL 設定パラメータを指定して、現在の URL のすべてまたは一部を表す文字列を返します。

構文

getUrl(component)

パラメータ

パラメータ タイプ 説明
component 文字列 URL から返されるコンポーネント。protocolhostportpathqueryextensionfragment のいずれかになる必要があります。コンポーネントが undefinednull である場合、または上記のいずれのコンポーネントにも一致しない場合は、href 値全体を返します。

関連付けられているアクセス権

get_url


gtagSet

gTag の set コマンドをデータレイヤーにプッシュし、現在のイベントとトリガーされたタグの処理(またはタグ処理のタイムアウト)が終了した後すぐに処理が行われるようにします。更新は、データレイヤーのキューに追加されたアイテムの前に、このコンテナで処理されることが保証されます。

たとえば、同意の初期化で配信されたタグから呼び出された場合、初期化イベントを処理する前に更新が適用されます。ads_data_redactiontrue または false に設定されていることや、url_passthroughtrue または false に設定されていることが考えられます。

例:

const gtagSet = require('gtagSet');

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

構文

gtagSet(object)

パラメータ

パラメータ タイプ 説明
Object オブジェクト 含まれるプロパティのグローバル状態を更新するオブジェクト。

関連付けられているアクセス権

write_data_layer は、指定されたすべてのキーについて、dataLayer への書き込み権限を確認します。gtagSet への入力がプレーン オブジェクトである場合、API はそのオブジェクト内のすべてのフラット化されたキーへの書き込み権限を確認します。たとえば、gtagSet({foo: {bar: 'baz'}}) の場合、API は foo.bar への書き込み権限を確認します。

gtagSet への入力がキーで、プレーン以外のオブジェクト値である場合、API はそのキーへの書き込み権限を確認します。たとえば、gtagSet('abc', true) の場合、API は 'abc' への書き込み権限を確認します。

入力オブジェクトにサイクルがある場合は、同じオブジェクトに到達する前のキーのみがチェックされることに注意してください。


injectHiddenIframe

非表示の iframe をページに追加します。

コールバックは関数インスタンスとして与えられ、それらを呼び出す JavaScript 関数にラップされています。

構文

injectHiddenIframe(url, onSuccess)

パラメータ

パラメータ タイプ 説明
url 文字列 iframe の src 属性の値として使用される URL。
onSuccess 関数 フレームが正常に読み込まれたときに呼び出されます。

関連付けられているアクセス権

inject_hidden_iframe


injectScript

スクリプトタグをページに追加して、指定された URL を非同期に読み込みます。コールバックは関数インスタンスとして与えられ、それらを呼び出す JavaScript 関数にラップされています。

構文

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

パラメータ

パラメータ タイプ 説明
url 文字列 スクリプトが挿入されるアドレス。
onSuccess 関数 スクリプトが正常に読み込まれたときに呼び出されます。
onFailure 関数 スクリプトの読み込みに失敗したときに呼び出されます。
cacheToken 文字列 指定された URL をキャッシュする必要があることを示すために使用される任意の文字列。この値を指定すると、JavaScript をリクエストするためのスクリプト要素が 1 つだけ作成されます。さらに読み込もうとすると、スクリプトが読み込まれるまで、指定された onSuccess メソッドと onFailure メソッドがキューに追加されます。

関連付けられているアクセス権

inject_script


isConsentGranted

指定された同意タイプが granted の場合、true を返します。

特定の同意タイプへの同意は、同意タイプが「granted」に設定されているか何も設定されていない場合、取得されたとみなされます。同意タイプに他の値が設定されている場合、同意は得られていないとみなされます。

タグ設定のためのタグ マネージャー管理画面には、常に起動するオプションがあります。常に起動するオプションがオンになっているタグでこの API を使用する場合、同意が得られたとみなされ、実際の同意の状態に関係なく true が返されます。

例:

const isConsentGranted = require('isConsentGranted');

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

構文

isConsentGranted(consentType)

パラメータ

パラメータ タイプ 説明
consentType 文字列 状態を確認する同意タイプ。

関連付けられているアクセス権

同意タイプの読み取り権限を持つ access_consent


JSON

JSON 関数を提供するオブジェクトを返します。

parse() 関数は JSON 文字列を解析し、この文字によって表される値またはオブジェクトを生成します。値を解析できない場合(不正な形式の JSON など)は undefined を返します。入力値が文字列でない場合は、入力が文字列に強制変換されます。

stringify() 関数は、入力を JSON 文字列に変換します。(オブジェクトにサイクルがあるなど)値を解析できない場合は undefined を返します。

構文

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

パラメータ

JSON.parse

パラメータ タイプ 説明
stringInput 任意 変換する値。値が文字列でない場合は、入力が文字列に強制変換されます。

JSON.stringify

パラメータ タイプ 説明
value 任意 変換する値。

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

ローカル ストレージにアクセスするためのメソッドを含むオブジェクトを返します。

構文

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

関連付けられているアクセス権

access_local_storage

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

引数をブラウザ コンソールに記録します。

構文

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

パラメータ

パラメータ タイプ 説明
obj1 [, obj2,... objN] 任意 引数

関連付けられているアクセス権

logging


makeInteger

与えられた値を数値(整数)に変換します。

構文

makeInteger(value)

パラメータ

パラメータ タイプ 説明
value 任意 変換する値。

関連付けられているアクセス権

なし。


makeNumber

指定された値を数値に変換します。

構文

makeNumber(value)

パラメータ

パラメータ タイプ 説明
value 任意 変換する値。

関連付けられているアクセス権

なし。


makeString

指定された値を文字列として返します。

構文

makeString(value)

パラメータ

パラメータ タイプ 説明
value 任意 変換する値。

関連付けられているアクセス権

なし。


makeTableMap

2 つの列で構成された単純なテーブル オブジェクトを Map に変換します。これを使って、2 つの列を持つ SIMPLE_TABLE テンプレート フィールドを、より管理しやすい形式に変更します。

たとえば、この関数で次のテーブル オブジェクトを変換します。

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

以下のマップに変換されます。

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

オブジェクトを返します。Key-Value ペアが追加されている場合は変換された Map、それ以外の場合は null を返します。

構文

makeTableMap(tableObj, keyColumnName, valueColumnName)

パラメータ

パラメータ タイプ 説明
tableObj リスト 変換するテーブル オブジェクト。各 Map がテーブル内の行を表すマップのリストです。行オブジェクトの各プロパティ名は列名で、プロパティ値は行の列値です。
keyColumnName 文字列 値が変換された Map 内のキーになる列の名前。
valueColumnName 文字列 値が変換された Map 内の値になる列の名前。

関連付けられているアクセス権

なし。


Math

Math 関数を提供するオブジェクト。

構文

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

パラメータ

Math 関数のパラメータは数値に変換されます。

関連付けられているアクセス権

なし。


Object

Object メソッドを提供するオブジェクトを返します。

keys() メソッドは、標準ライブラリの Object.keys() の動作を実行します。for...in... ループと同じ順序で、指定したオブジェクトに固有の列挙プロパティ名の配列を返します。入力値がオブジェクトでない場合、オブジェクトに強制変換されます。

values() メソッドは、標準ライブラリの Object.values() の動作を実行します。for...in... ループと同じ順序で、指定したオブジェクトに固有の列挙プロパティの配列を返します。入力値がオブジェクトでない場合、オブジェクトに強制変換されます。

entries() メソッドは、標準ライブラリの Object.entries() の動作を実行します。for...in... ループと同じ順序で、指定したオブジェクトに固有の列挙プロパティ [key, value] の配列を返します。入力値がオブジェクトでない場合、オブジェクトに強制変換されます。

freeze() メソッドは、標準ライブラリの Object.freeze() の動作を実行します。固定されたオブジェクトを変更することはできません。つまり、新しいプロパティを追加したり、既存のプロパティを削除したり、既存のプロパティ値を変更したりすることは不可能です。freeze() は、渡されたのと同じオブジェクトを返します。プリミティブ引数または null 引数は、固定されたオブジェクトと同様に扱われ、返されます。

delete() メソッドは、標準ライブラリの削除演算子の動作を実行します。オブジェクトが固定されていないことを条件に、指定されたキーをオブジェクトから削除します。標準ライブラリの削除演算子と同様に、最初の入力値(objectInput)が固定されていないオブジェクトであれば、2 番目の入力値(keyToDelete)で存在しないキーが指定されていても true を返します。それ以外の場合は false を返します。ただし、標準ライブラリの削除演算子とは次の点で異なります。

  • keyToDelete には、ネストされたキーを指定するドット区切り文字列は使用できません。
  • delete() を使用して配列から要素を削除することはできません。
  • delete() を使用して、グローバル スコープからプロパティを削除することはできません。

構文

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

パラメータ

Object.keys

パラメータ タイプ 説明
objectInput 任意 列挙するキーを持つオブジェクト。入力がオブジェクトでない場合、オブジェクトに強制変換されます。

Object.values

パラメータ タイプ 説明
objectInput 任意 列挙する値のオブジェクト。入力がオブジェクトでない場合、オブジェクトに強制変換されます。

Object.entries

パラメータ タイプ 説明
objectInput 任意 Key-Value ペアで列挙するオブジェクト。入力がオブジェクトでない場合、オブジェクトに強制変換されます。

Object.freeze

パラメータ タイプ 説明
objectInput 任意 固定するオブジェクト。入力がオブジェクトでない場合、固定されたオブジェクトとして扱われます。

Object.delete

パラメータ タイプ 説明
objectInput 任意 削除するキーを持つオブジェクト。
keyToDelete 文字列 削除するトップレベルのキー。

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

URL オブジェクトと同様に、指定された URL の全構成要素を含むオブジェクトを返します。

この API は、不正な形式の URL に対して undefined を返します。URL が適切にフォーマットされている場合、URL 文字列に存在しないフィールドの文字列、または searchParams のオブジェクトは空になります。

返されるオブジェクトには次のフィールドがあります。

{
  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,
}

const parseUrl = require('parseUrl');

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

構文

parseUrl(url);

パラメータ

パラメータ タイプ 説明
url 文字列 チェック用の完全な URL。

関連付けられているアクセス権

なし。


queryPermission

絞り込まれた範囲に対して許可された権限を照会して、booleanを返します。権限が与えられている場合は true、そうでない場合は false を返します。

構文

queryPermission(permission, functionArgs*)

パラメータ

パラメータ タイプ 説明
permission 文字列 権限の名前。
functionArgs 任意 関数の引数は、照会される権限によって異なります。以下の関数の引数を参照してください。

関数引数

sendPixelinjectScriptinjectHiddenIframe: 2 番目のパラメータは URL 文字列です。

writeGlobalsreadGlobals: 2 番目のパラメータは、書き込みまたは読み取りの対象となるキーです。

readUrl: URL 全体を読み取ることができるかどうかを照会するために追加の引数は必要ありません。特定のコンポーネントを読み取ることができるかどうかを照会するには、コンポーネント名を 2 番目の引数として渡します。

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

特定のクエリキーが読み取り可能かどうかを確認するには、クエリキーを 3 番目のパラメータとして渡します。

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

関連付けられているアクセス権

なし。


readCharacterSet

document.characterSet の値を返します。

構文

readCharacterSet()

パラメータ

なし。

関連付けられているアクセス権

read_character_set


readTitle

document.title の値を返します。

構文

readTitle()

パラメータ

なし。

関連付けられているアクセス権

read_title


require

組み込み関数を、名前を基にインポートします。プログラムから呼び出すことができる関数またはオブジェクトを返します。ブラウザで組み込み関数がサポートされていない場合、未定義を返します。

構文

require(name)

パラメータ

パラメータ タイプ 説明
name 文字列 インポートする関数の名前。

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

関連付けられているアクセス権

なし。


sendPixel

指定された URL エンドポイントに対し GET リクエストを行います。

構文

sendPixel(url, onSuccess, onFailure)

パラメータ

パラメータ タイプ 説明
url 文字列 ピクセルを送信する場所。
onSuccess 関数 ピクセルが正常に読み込まれたときに呼び出されます。注: リクエストが正常に送信された場合でも、ブラウザでは onSuccess を実行するために有効な画像レスポンスが必要になることがあります。
onFailure 関数 ピクセルの読み込みに失敗したときに呼び出されます。注: リクエストが正常に送信された場合でも、サーバーから有効な画像レスポンスが返されないと、onFailure が実行されることがあります。

関連付けられているアクセス権

send_pixel


setCookie

指定された名前、値、オプションで Cookie を設定または削除します。

構文

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

パラメータ

パラメータ タイプ 説明
name 文字列 Cookie の名前。
value 文字列 Cookie の値。
options オブジェクト Domain、Path、Expires、Max-Age、Secure、SameSite の各属性を指定します(下記のオプションを参照)。
encode boolean Cookie の値を JavaScript の encodeURIComponent() でエンコードするかどうかを指定します。デフォルト値は true です。

  • Domain: 存在する場合、options['domain'] プロパティによって設定されます。この値を 'auto' に設定すると、ドキュメントの場所に基づいて、可能な限り広いドメインを使用して Cookie の書き込みを試みます。その試みが失敗した場合は、徐々に狭いサブドメインを試していきます。すべて失敗した場合は、ドメインなしで Cookie の書き込みを試みます。値が設定されていない場合、ドメインを指定せずに Cookie の書き込みを試みます。なお、ドメインが指定されていない Cookie が document.cookie に書き込まれると、ユーザー エージェントはデフォルトでその Cookie のドメインを現在のドキュメントの場所のホストとします。
  • Path: 存在する場合、options['path'] によって設定されます。パスが指定されていない Cookie が document.cookie に書き込まれると、ユーザー エージェントはデフォルトでその Cookie のパスを現在のドキュメントの場所のパスとします。
  • Max-Age: 存在する場合、options['max-age'] によって設定されます。
  • Expires: 存在する場合、options['expires'] によって設定されます。存在する場合、UTC 形式の日付文字列でなければなりません。Date.toUTCString() を使用して、このパラメータの Date をフォーマットできます。
  • Secure: 存在する場合、options['secure'] によって設定されます。
  • SameSite: 存在する場合、options['samesite'] によって設定されます。

関連付けられているアクセス権

set_cookies


setDefaultConsentState

デフォルトの同意の更新をデータレイヤーにプッシュし、現在のイベントとトリガーされたタグの処理(またはタグ処理のタイムアウト)が終了した後すぐに処理されるようにします。更新は、データレイヤーのキューに追加されたアイテムの前に、このコンテナで処理されることが保証されます。 詳細: 同意について

例:

const setDefaultConsentState = require('setDefaultConsentState');

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

構文

setDefaultConsentState(consentSettings)

パラメータ

パラメータ タイプ 説明
consentSettings オブジェクト 指定された同意タイプのデフォルト状態を定義するオブジェクト。

consentSettings オブジェクトは、任意の同意タイプ文字列を、'granted' または 'denied' のいずれかにマッピングしたものです。次の値をサポートします。

キー名 タイプ 説明
consentType 文字列 各同意タイプの値は「granted」または「denied」に設定できます。「granted」以外の値はすべて「denied」として扱われます。この値を「undefined」に設定しても、それ以前の値には影響しません。
region 配列 同意設定を適用する地域を指定する地域コードの配列(省略可)。地域コードは ISO 3166-2 形式の国または下位地域区分を使用して表されます。
wait_for_update 数値 ミリ秒単位の値を指定して、データ送信までの待機時間を設定します。非同期で読み込まれる同意ツールで使用されます。

関連付けられているアクセス権

consentSettings オブジェクトのすべての同意タイプに対する書き込み権限を持つ access_consent


setInWindow

指定されたキーで window 内に指定された値を設定します。すでに値が存在する場合、デフォルトではこのメソッドは window 内に値を設定しません。既存の値の有無にかかわらず、window 内に値を設定するには、overrideExistingtrue に設定します。booleanを返します。値が正常に設定された場合は true、そうでない場合は false を返します。

構文

setInWindow(key, value, overrideExisting)

パラメータ

パラメータ タイプ 説明
key 文字列 window に値を配置するキー。
value * window に設定する値。
overrideExisting boolean 値があるかどうかにかかわらず、window に値を設定する必要があることを示すフラグ。

関連付けられているアクセス権

access_globals


sha256

入力値の SHA-256 ダイジェストを計算し、ダイジェストが base64 でエンコードされたコールバックを呼び出します(options オブジェクトが別の出力エンコードを指定していない場合)。

例:

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

構文

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

パラメータ

パラメータ タイプ 説明
input 文字列 ハッシュを計算する文字列。
onSuccess 関数 生成されたダイジェスト(base64 でエンコード済み)で呼び出されます(options オブジェクトが別の出力エンコードを指定していない場合)。
onFailure 関数 ダイジェストの計算中にエラーが発生した場合、またはブラウザが sha256 をネイティブ サポートしていない場合に呼び出されます。コールバックは、エラーの名前とメッセージを含むオブジェクトとともに呼び出されます。
options オブジェクト オプションオブジェクト(省略可)が出力エンコードを指定します。指定する場合、オブジェクトには base64 または hex の値を持つキー outputEncoding が含まれている必要があります。

関連付けられているアクセス権

なし。


templateStorage

テンプレート ストレージにアクセスするためのメソッドを含むオブジェクトを返します。テンプレート ストレージを使うと、単一のテンプレートの実行全体でデータを共有できます。テンプレート ストレージに保存されているデータは、ページの存続期間中は維持されます。

構文

const templateStorage = require('templateStorage');

templateStorage.getItem(key);

templateStorage.setItem(key, value);

templateStorage.removeItem(key);

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

関連付けられているアクセス権

access_template_storage

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

toBase64 API を使うと、文字列を base64 表現にエンコードできます。

構文

toBase64(input)

パラメータ

パラメータ タイプ 説明
input 文字列 エンコードする文字列。

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

関連付けられているアクセス権

なし


updateConsentState

同意の更新をデータレイヤーにプッシュし、現在のイベントとトリガーされたタグの処理(またはタグ処理のタイムアウト)が終了した後すぐに処理されるようにします。更新は、データレイヤーのキューに追加されたアイテムの前に、このコンテナで処理されることが保証されます。詳細: 同意について

例:

const updateConsentState = require('updateConsentState');

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

構文

updateConsentState(consentSettings)

パラメータ

パラメータ タイプ 説明
consentSettings オブジェクト 指定された同意タイプの状態を更新するオブジェクト。

consentSettings オブジェクトは、任意の同意タイプ文字列を、'granted' または 'denied' のいずれかにマッピングしたものです。次の値をサポートします。

キー名 タイプ 説明
consentType 文字列 各同意タイプの値は「granted」または「denied」に設定できます。 「granted」以外の値は「denied」として扱われます。この値を「未定義」に設定しても、以前の値には影響しません。

関連付けられているアクセス権

consentSettings オブジェクトのすべての同意タイプに対する書き込み権限を持つ access_consent


テスト API

以下の API はサンドボックス化された JavaScript テストと連携して Google タグ マネージャーでカスタム テンプレートのテストを作成します。これらのテスト API には、require() ステートメントは必要ありません。カスタム テンプレート テストの詳細


assertApi

指定された API に関するアサーションをスムーズに行うために使用できるマッチャー オブジェクトを返します。

構文

assertApi(apiName)

パラメータ

パラメータ タイプ 説明
apiName 文字列 確認する API の名前。require() に渡された文字列と同じ文字列。

マッチャー

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

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

assertThat

assertThat API は Google の [Truth] ライブラリを参考に作成されています。これは、サブジェクトの値に関するアサーションをスムーズに行うために使用できるオブジェクトを返します。アサーションが失敗すると、テストは直ちに停止し、失敗としてマークが付けられます。ただし、1 つのテストが失敗しても、他のテストケースに影響することはありません。

構文

assertThat(actual, opt_message)

パラメータ

パラメータ タイプ 説明
actual 任意 アサーションで使用する値です。
opt_message 文字列 アサーションが失敗した場合に出力するメッセージ(省略可)。

マッチャー

マッチャー 説明
isUndefined() サブジェクトが undefined であることのアサーションを行います。
isDefined() サブジェクトが undefined ではないことのアサーションを行います。
isNull() サブジェクトが null であることのアサーションを行います。
isNotNull() サブジェクトが null ではないことのアサーションを行います。
isFalse() サブジェクトが false であることのアサーションを行います。
isTrue() サブジェクトが true であることのアサーションを行います。
isFalsy() サブジェクトが falsy であることのアサーションを行います。falsy 値は undefinednullfalseNaN、0、および ''(空の文字列)です。
isTruthy() サブジェクトが truthy であることのアサーションを行います。falsy 値は undefinednullfalseNaN、0、および ''(空の文字列)です。
isNaN() サブジェクトの値が NaN であることのアサーションを行います。
isNotNaN() サブジェクトが NaN 以外の任意の値であることのアサーションを行います。
isInfinity() サブジェクトが正または負の無限大であることのアサーションを行います。
isNotInfinity() サブジェクトが正または負の無限大以外の値であることのアサーションを行います。
isEqualTo(expected) サブジェクトが指定された値と等しいことのアサーションを行います。参照を比較するのではなく、値を比較します。オブジェクトと配列の内容は繰り返し比較されます。
isNotEqualTo(expected) サブジェクトが指定された値と等しくないことのアサーションを行います。参照を比較するのではなく、値を比較します。オブジェクトと配列の内容は繰り返し比較されます。
isAnyOf(...expected) サブジェクトが指定された値のいずれかと等しいことのアサーションを行います。参照を比較するのではなく、値を比較します。オブジェクトと配列の内容は繰り返し比較されます。
isNoneOf(...expected) サブジェクトが指定された値のどの値にも等しくないことのアサーションを行います。参照を比較するのではなく、値を比較します。オブジェクトと配列の内容は繰り返し比較されます。
isStrictlyEqualTo(expected) サブジェクトが指定された値と厳密に等しい(===)ことのアサーションを行います。
isNotStrictlyEqualTo(expected) サブジェクトが指定された値と厳密には等しくない(!==)ことのアサーションを行います。
isGreaterThan(expected) 順序比較で、指定された値よりサブジェクトが大きい(>)ことのアサーションを行います。
isGreaterThanOrEqualTo(expected) 順序比較で、サブジェクトが指定された値より大きい、または指定された値と等しい(>=)ことのアサーションを行います。
isLessThan(expected) 順序比較で、指定された値よりサブジェクトが小さい(<)ことのアサーションを行います。
isLessThanOrEqualTo(expected) 順序比較で、サブジェクトが指定された値より小さい、または指定された値と等しい(<=)ことのアサーションを行います。
contains(...expected) サブジェクトが、指定されたすべての値を任意の順序で含む配列または文字列であることのアサーションを行います。参照を比較するのではなく、値を比較します。オブジェクトと配列の内容は繰り返し比較されます。
doesNotContain(...expected) サブジェクトが、指定されたどの値も含まない配列または文字列であることのアサーションを行います。参照を比較するのではなく、値を比較します。 オブジェクトと配列の内容は繰り返し比較されます。
containsExactly(...expected) サブジェクトが、指定されたすべての値を任意の順序で含み、それ以外の値を含まない配列であることのアサーションを行います。参照を比較するのではなく、値を比較します。オブジェクトと配列の内容は繰り返し比較されます。
doesNotContainExactly(...expected) サブジェクトが、指定された値とは異なる一連の値を任意の順序で含む配列であることのアサーションを行います。参照を比較するのではなく、値を比較します。オブジェクトと配列の内容は繰り返し比較されます。
hasLength(expected) サブジェクトが、指定された長さの配列または文字列であることのアサーションを行います。 値が配列または文字列でない場合、アサーションは常に失敗します。
isEmpty() サブジェクトが空(長さ = 0)の配列または文字列であることのアサーションを行います。値が配列または文字列でない場合、アサーションは常に失敗します。
isNotEmpty() サブジェクトが空でない(長さ > 0)配列または文字列であることのアサーションを行います。値が配列または文字列でない場合、アサーションは常に失敗します。
isArray() サブジェクトの型が配列であることのアサーションを行います。
isBoolean() サブジェクトの型がブール値であることのアサーションを行います。
isFunction() サブジェクトの型が関数であることのアサーションを行います。
isNumber() サブジェクトの型が数値であることのアサーションを行います。
isObject() サブジェクトの型がオブジェクトであることのアサーションを行います。
isString() サブジェクトの型が文字列であることのアサーションを行います。

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

現在のテストが直ちに失敗し、指定されたメッセージを出力します(指定されている場合)。

構文

fail(opt_message);

パラメータ

パラメータ タイプ 説明
opt_message 文字列 省略可能なエラー メッセージのテキスト。

fail('This test has failed.');

mock

mock API を使用すると、サンドボックス化された API の動作をオーバーライドできます。モック API はテンプレート コードで安全に使用できますが、テストモード以外では使用できません。モックは、各テストの実行前にリセットされます。

構文

mock(apiName, returnValue);

パラメータ

パラメータ タイプ 説明
apiName 文字列 モックする API の名前。require() に渡された文字列と同じ文字列。
returnValue 任意 API または API の代わりに呼び出される関数に対して返される値。returnValue が 関数の場合、この関数はサンドボックス化 された API の代わりに呼び出されます。returnValue が 関数以外の場合、その値がサンドボックス化された API の代わりに返されます。

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

runCode

指定した入力データ オブジェクトを設定した現在のテスト環境で、テンプレートのコード([コード] タブの内容)を実行します。

構文

runCode(data)

パラメータ

パラメータ タイプ 説明
data オブジェクト テストで使用するデータ オブジェクト。

戻り値

変数テンプレートの変数の値を返します。他のすべてのテンプレート タイプに対して undefined を返します。

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