カスタム テンプレートのアクセス権

このドキュメントでは、ウェブ カスタム テンプレートの権限について説明します。


各権限は…

  • その権限を要求する API によってチェックされます。
  • サンドボックス化された JavaScript から、使用されている API に応じて自動検出されます。検出処理は、カスタム テンプレート エディタでの編集時(迅速なフィードバック ループを実現するため)と、コードのコンパイル時(適切な権限が適用されていることを検証するため)に行われます。
  • カスタム テンプレート エディタ内で編集して、権限をより具体的に指定できるようになっています。
  • queryPermission API により、サンドボックス化された JavaScript 内でクエリ可能です。

access_globals

表示名: Accesses global variables

説明: グローバル変数(機密 API を潜在的に含む)へのアクセスを許可します。

構成: アクセス可能なキーのリスト。各キーは、ドット区切りのパスです(例: foo.bar)。各パスの最初のトークンは、ブラウザのグローバル スコープで事前定義されたキーや JavaScript キーワードであってはなりません。既読、 実行、書き込み、実行のチェックボックスでアクセス権を制御します。

要求元: setInWindowcopyFromWindowcallInWindowcreateQueuecreateArgumentsQueue

クエリ シグネチャ: queryPermission('access_globals', 'read', <key to read from>)queryPermission('access_globals', 'write', <key to write to>)queryPermission('access_globals', 'readwrite', <key to read and write>)、または queryPermission('access_globals', 'execute', <key of function to execute>)

メモ: カスタム テンプレートでグローバル値からの読み取りやグローバル値への書き込みを許可するかどうかを制御します。

コード例

const queryPermission = require('queryPermission');
const createQueue = require('createQueue');
if (queryPermission('access_globals', 'readwrite', 'dataLayer')) {
  const dataLayerPush = createQueue('dataLayer');
}

access_local_storage

表示名: Accesses local storage

説明: ローカル ストレージ内の指定したキーへのアクセスを許可します。

構成: アクセス可能なローカル ストレージ キーのリスト。これは、ワイルドカードを使用しないシンプルなキー配列です。読み取りと書き込みのチェックボックスで、アクセス権を制御します。

要求元: localStorage

クエリ シグネチャ: queryPermission('access_local_storage', 'read', <key to read from>)queryPermission('access_local_storage', 'write', <key to write to>)、または queryPermission('access_local_storage', 'readwrite', <key to read and write>)

コード例

const queryPermission = require('queryPermission');
const localStorage = require('localStorage');
const key = 'my_key';
if (queryPermission('access_local_storage', 'read', key)) {
  const value = localStorage.getItem(key);
}

access_template_storage

表示名: Accesses template storage

説明: ページの存続期間中は維持されるテンプレート用の一時的なストレージへのアクセスを許可します。

構成: なし

要求元: templateStorage

クエリ シグネチャ: queryPermission('access_template_storage')

コード例

const queryPermission = require('queryPermission');
const templateStorage = require('templateStorage');
const key = 'my_key';
if (queryPermission('access_template_storage')) {
  const value = templateStorage.getItem(key);
}

get_cookies

表示名: Reads cookie value(s)

説明: 指定した名前の Cookie の値を読み取ります。

構成: 読み取りが許可されている Cookie の名前のリスト。

要求元: getCookieValues

クエリ シグネチャ: queryPermission('get_cookies', <name>)

注: Cookie 名に基づいて、その Cookie の読み取りを許可するかどうかを制御します。

コード例

const queryPermission = require('queryPermission');
const getCookieValues = require('getCookieValues');
const cookieName = 'info';
let cookieValues;
if (queryPermission('get_cookies', cookieName)) {
  cookieValues = getCookieValues(cookieName);
}

get_referrer

表示名: Reads referrer URL

説明: 参照 URL の絞り込まれた部分への読み取りアクセスを許可します。

構成: 次のブール値で、参照 URL のどの部分の読み取りを許可するかを管理します。参照 URL の特定の部分は、対応する部分が true である場合にのみ読み取ることができます。これらのブール値のすべてが true に設定されている場合、コンポーネントを指定せずに getReferrerUrl を呼び出して完全な参照 URL を取得できます。値が設定されていない場合、デフォルト値は all です。値が設定されている場合、protocolhostportpathquery、または extension を含むコンポーネントの配列である必要があります。

queryKeys: query が選択されている場合、テンプレート作成者は、読み取り可能なクエリキーのセットをさらに制限できます。これは、ワイルドカードを使用しないシンプルなキー配列です。

要求元: getReferrerUrlgetReferrerQueryParameters

クエリ シグネチャ: queryPermission('get_referrer', <url_component>)

コード例

const queryPermission = require('queryPermission');
const getReferrerUrl = require('getReferrerUrl');
let referrer;
if (queryPermission('get_referrer', 'query')) {
  referrer = getReferrerUrl('queryParams');
}

get_url

表示名: Reads URL

説明: 現在のページの URL の「一部」または「すべて」を返します。

構成: 次のブール値で、URL のどの部分の読み取りを許可するかを管理します。URL の特定の部分は、対応する部分が true である場合にのみ読み取ることができます。呼び出し元は、これらのブール値がすべて true に設定されている場合に限り、コンポーネントを指定せずに getUrl を呼び出して、URL 全体を取得することができます。値が設定されていない場合、デフォルト値は all です。値が設定されている場合、protocolhostportpathqueryextension、または fragment を含むコンポーネントの配列である必要があります。

queryKeys: query が選択されている場合、テンプレート作成者は、読み取り可能なクエリキーのセットをさらに制限できます。これは、ワイルドカードを使用しないシンプルなキー配列です。

要求元: getUrl

クエリ シグネチャ: queryPermission('get_url', <optional url component>, <optional query key>)

URL コンポーネントを指定する場合は、'protocol''host''port''path''query''extension'、または 'fragment' のいずれかにする必要があります。URL コンポーネントを省略すると、権限クエリは URL 全体に対するアクセスのリクエストになります。

クエリキーを指定する場合は、テンプレート コードで読み取ることができるクエリ文字列引数にする必要があります。

メモ: カスタム テンプレートで現在のウェブページからの読み取りを許可するかどうかを制御します。ウェブページの特定の部分に限定することもできます。

コード例

const queryPermission = require('queryPermission');
const getUrl = require('getUrl');
if (queryPermission('get_url', 'query', 'gclid')) {
  const gclid = getUrl('query', false, null, 'gclid');
}

inject_hidden_iframe

表示名: Injects hidden iframes

説明: 指定された URL で非表示の iFrame を挿入します。

構成: URL パターンのリスト

要求元: injectHiddenIframe

クエリ シグネチャ: queryPermission('inject_hidden_iframe', <url>)

注: カスタム テンプレートで非表示 iFrame の挿入を許可するかどうか、ならびにその挿入元を制御します。

コード例

const queryPermission = require('queryPermission');
const injectHiddenIframe = require('injectHiddenIframe');
const url = 'https://www.example.com/iframes';
if (queryPermission('inject_hidden_iframe', url)) {
  injectHiddenIframe(url);
}

inject_script

表示名: Injects scripts

説明: ページにスクリプトを挿入します。

構成: URL パターンのリスト

要求元: injectScript

クエリ シグネチャ: queryPermission('inject_script', <url>)

注: カスタム テンプレートで JavaScript の挿入を許可するかどうか、ならびにその挿入元を制御します。

コード例

const queryPermission = require('queryPermission');
const injectScript = require('injectScript');
const url = 'https://www.example.com?api.js';
if (queryPermission('inject_script', url)) {
  injectScript(url);
}

logging

表示名: Logs to console

説明: 開発者コンソールと GTM のプレビュー モードにログを記録します。

構成: 本番環境でのログを有効にするオプション。デフォルトでは、デバッグやプレビューでのみログを有効にします。権限が拒否された場合、logToConsole はエラーをスローする代わりに、ログメッセージの表示を無効にします。

要求元: logToConsole

クエリ シグネチャ: queryPermission('logging')

注: カスタム テンプレートでデベロッパー コンソールへのログの記録を許可するかどうかを制御します。

コード例

const queryPermission = require('queryPermission');
const logToConsole = require('logToConsole');
// Note that it's fine to call log, since the log call will be ignored if
// logging isn't permitted in the current environment.
logToConsole('diagnostic info');

read_data_layer

表示名: Reads data layer

説明: dataLayer からデータを読み取ります。

構成: キーマッチ表現のセット。キーマッチには、ドット記法による前方一致の参照(末尾はワイルドカード扱い)を指定できます。キーマッチ表現は、データレイヤーからどのプロパティを読み取ることができるかを制御します。

要求元: copyFromDataLayer

クエリ シグネチャ: queryPermission('read_data_layer', <data layer key to read from>)

メモ: カスタム テンプレートでデータレイヤーからの読み取りを許可するかどうかを制御します。

コード例

const queryPermission = require('queryPermission');
const copyFromDataLayer = require('copyFromDataLayer');
const dlKey = 'foo.bar';
if (queryPermission('read_data_layer', dlKey)) {
  const dlContents = copyFromDataLayer(dlKey);
}

read_character_set

表示名: Reads document character set

説明: document.characterSet を読み取ります。

構成: なし

要求元: readCharacterSet

クエリ シグネチャ: queryPermission('read_character_set')

注: カスタム テンプレートで document.characterSet の読み取りを許可するかどうかを制御します。

コード例

const queryPermission = require('queryPermission');
const readCharacterSet = require('readCharacterSet');
if (queryPermission('read_character_set')) {
  const characterSet = readCharacterSet();
}

read_container_data

表示名: Reads container data

説明: コンテナに関するデータを読み取ります。

構成: なし

要求元: getContainerVersion

クエリ シグネチャ: queryPermission('read_container_data')

注: カスタム テンプレートでコンテナに関するデータの読み取りを許可するかどうかを制御します。

コード例

const queryPermission = require('queryPermission');
const getCookieValues = require('getContainerVersion');
let version;
if (queryPermission('read_container_data')) {
  version = getContainerVersion();
}

read_event_metadata

表示名: Reads event metadata

説明: イベント コールバックのイベント メタデータを読み取ります。

構成: なし

要求元: addEventCallback

クエリ シグネチャ: queryPermission('read_event_metadata')

注: カスタム テンプレートでコールバックのイベント メタデータの読み取りを許可するかどうかを制御します。

コード例

const queryPermission = require('queryPermission');
const addEventCallback = require('addEventCallback');
if (queryPermission('read_event_metadata')) {
  addEventCallback((containerId, eventMetadata) => {
    // Read event metadata.
  });
}

read_title

表示名: Reads document title

説明: document.title を読み取ります。

構成: なし

要求元: readTitle

クエリ シグネチャ: queryPermission('read_title')

注: カスタム テンプレートで document.title の読み取りを許可するかどうかを制御します。

コード例

const queryPermission = require('queryPermission');
const readTitle = require('readTitle');
if (queryPermission('read_title')) {
  const title = readTitle();
}

send_pixel

表示名: Sends pixels

説明: 指定された URL に GET リクエストを送信します。応答は処理されません。

構成: 許可されている URL パターンのリスト。

要求元: sendPixel

クエリ シグネチャ: queryPermission('send_pixel', <url>)

注: カスタム テンプレートで GET リクエストの送信を許可するかどうか、ならびにその送信元を制御します。

コード例

const queryPermission = require('queryPermission');
const sendPixel = require('sendPixel');
const url = 'https://www.example.com?foo=3';
if (queryPermission('send_pixel', url)) {
  sendPixel(url);
}

set_cookies

表示名: Sets a cookie

説明: 指定された名前とパラメータを使用して Cookie を設定します。

構成: 許可されている Cookie 名のリスト。オプションとして、名前、ドメイン、パス、secure 属性、有効期限について制限できます。

要求元: setCookie

クエリ シグネチャ: queryPermission('set_cookies', <name>, <options>)

注: Cookie 名、ドメイン、パス、secure 属性、有効期限に基づき、Cookie を書き込めるかどうかを制御します。

コード例

const queryPermission = require('queryPermission');
const setCookie = require('setCookie');
const options = {
  'domain': 'www.example.com',
  'path': '/',
  'max-age': 60*60*24*365,
  'secure': true
};
if (queryPermission('set_cookies', 'info', options)) {
  setCookie('info', 'xyz', options);
}

write_data_layer

表示名: Writes data layer

説明: dataLayer にデータを書き込みます。

構成: キーマッチ表現のセット。キーマッチには、ドット記法による前方一致の参照(末尾はワイルドカード扱い)を指定できます。キーマッチ表現は、データレイヤーに書き込み可能なプロパティを制御します。

要求元: gtagSet

クエリ シグネチャ: queryPermission('write_data_layer', <data layer key to write from>)

注: カスタム テンプレートでデータレイヤーへの書き込みを許可するかどうかを制御します。

コード例

const queryPermission = require('queryPermission');
const gtagSet = require('gtagSet');
const dlKey = 'foo.bar';
if (queryPermission('write_data_layer', dlKey)) {
  gtagSet({dlKey: 'baz'});
}