自訂範本快速入門指南

自訂範本可讓您編寫自己的代碼和變數定義,供機構組織內的其他人員搭配使用,以及內建代碼和變數範本。自訂範本具有以權限為主的沙箱特性,可讓您比使用自訂 HTML 標記自訂 JavaScript 變數更安全、更有效率地編寫自訂代碼和變數。

您可以在 Google 代碼管理工具的「範本」部分定義自訂代碼和變數範本。範本主畫面將列出已在容器中定義的任何代碼或變數範本。您也可以在這個畫面建立新範本

您可以匯出範本並分享給機構內的其他成員。您也可以在社群範本庫中開發範本,以便廣泛發布。

範本編輯器

範本編輯器可讓您建立、預覽及測試自訂範本。其中包含四個主要區域供您輸入,可幫助您定義代碼範本:

  • 資訊 - 定義範本的基本屬性,例如標記或變數名稱和圖示。
  • 欄位:這個視覺編輯器可讓您在代碼範本中加入輸入欄位。
  • 程式碼:輸入採用沙箱機制的 JavaScript,定義代碼或變數的行為。
  • 權限:查看及設定代碼或變數允許執行的動作。

建立第一個自訂代碼範本

本範例會逐步說明如何建立基本像素廣告代碼範例。當這個代碼在網頁上觸發時,代碼會將包含正確帳戶資訊的命中傳送給代碼供應商的伺服器。

1. 如要開始建立第一個範本,請按一下左側導覽面板中的「Templates」(範本),然後按一下「Tag Templates」區段下方的「New」(新增) 按鈕。

2. 按一下「Info」,然後定義標記的「Name」 (必要)、「Description」和「Icon」

名稱:使用者在「代碼管理工具」使用者介面中導入這個代碼時會看到的名稱。

「Description」只是字面上的意思,可清楚呈現這個標記的功能 (200 個半形字元以內)。

「Icon」可讓您選擇在標記顯示於支援圖示屬性的清單中時要顯示的圖片。圖示圖片必須為正方形的 PNG、JPEG 或 GIF 檔案,大小不超過 50 KB,且大小至少為 64 x 64 像素。

3. 按一下「重新整理」即可預覽範本。

欄位輸入內容的右側會顯示「Template Preview」(範本預覽) 視窗。每次在編輯器中進行變更時,都會顯示「Refresh」按鈕。按一下 [重新整理],即可查看您所做的變更對代碼外觀會有什麼影響。

4. 按一下「欄位」,在代碼範本中加入欄位。

範本編輯器的「Fields」分頁可讓您在標記範本中建立及編輯欄位。欄位可用來輸入自訂資料,例如帳戶 ID。您可以新增標準表單元素,例如文字欄位、下拉式選單、圓形按鈕和核取方塊。

5. 按一下「新增欄位」,然後選取「文字輸入」。將預設名稱 (例如 "text1") 換成 "accountId"。在「範本預覽」中,按一下「重新整理」

這個欄位旁邊會顯示熟悉的變數選取器 (變數選取器圖示) 圖示。這個範本的使用者可以按一下變數選取器圖示,選擇此容器中使用的變數。

下一步是在欄位中加入標籤:

6. 按一下文字欄位旁邊的展開圖示 (展開圖示),開啟這個欄位的更多選項。在「顯示名稱」欄位中輸入「帳戶 ID」。在「Template Preview」(範本預覽) 中,按一下「Refresh」(重新整理)

標題上方應會顯示標題為「Account ID」的文字標籤。

7. 按一下「Code」分頁標籤,然後在編輯器中輸入採用沙箱機制的 JavaScript:

// require relevant API
const sendPixel = require('sendPixel');
const encodeUriComponent = require('encodeUriComponent');

// capture values of template fields
const account = data.accountId;

// use the provided APIs to do things like send pixels
const url = 'https://endpoint.example.com/?account=' + encodeUriComponent(account);
sendPixel(url, data.gtmOnSuccess, data.gtmOnFailure);

第一行程式碼 const sendPixel = require('sendPixel') 會匯入 sendPixel API

第二行程式碼 const encodeUriComponent = require('encodeUriComponent') 會匯入 encodeUriComponent API

下一行 const account = data.accountId; 會取得在步驟 5 建立的 accountId 值,並將其儲存在名為 account 的常數中。

第 3 行程式碼 const url = 'https://endpoint.example.com/?account=' + encodeUriComponent(account); 設定了 url 常數,用來串連固定的網址端點,該端點會記錄數據分析資料和已設定代碼的編碼帳戶 ID。

最後一行 sendPixel(url, data.gtmOnSuccess, data.gtmOnFailure) 會使用必要參數執行 sendPixel() 函式,並向指定網址發出要求。data.gtmOnSuccessdata.gtmOnFailure 值會告知 Google 代碼管理工具,代碼已完成或失敗的工作,然後由 Google 代碼管理工具用於代碼排序預覽模式等功能。

8. 按一下「儲存」儲存進度。這會將偵測到的所有權限載入範本編輯器。

有些範本 API 具有與其相關的權限,指定這些權限可以或不能執行哪些操作。在程式碼中使用 sendPixel 等範本 API 時,代碼管理工具會在「權限」分頁中顯示相關權限。

9. 按一下「Permissions」,修正 sendPixel 可傳送資料的目標網域。在「Send Pixels」項目中,按一下展開圖示 (展開圖示),然後在「允許的網址比對模式」中輸入 https://endpoint.example.com/

如果將標記範本設為傳送資料,您必須在相關權限底下指定允許的網址比對模式,以限制資料的傳送目標位置。如果程式碼中指定的網址與允許的網址比對模式不符,sendPixel 呼叫就會失敗。

網址比對模式必須使用 HTTPS,並同時指定主機和路徑模式。主機可以是網域 (例如「https://example.com/」) 或特定子網域 (例如「https://sub.example.com/」)。路徑至少須包含「/」。https://example.com/*https://\*.example.com/test/\*.example.com/www.example.comshop.example.comblog.example.com\*https://example.com/\*

用於分行指定其他網址比對模式。

10. 按一下「Run Code」,然後查看「Console」視窗,確認是否有任何問題。

「Console」視窗中會顯示所有偵測到的錯誤。

11. 按一下「儲存」,然後關閉範本編輯器。

標記範本現在應該已可供使用。

使用新的代碼

使用新定義的自訂標記範本建立新代碼的程序與任何其他標記相同:

  1. 在 Google 代碼管理工具中,依序按一下「代碼」>「新增」
  2. 新代碼會顯示在「新增代碼」視窗的「自訂」部分。 按一下該按鈕,開啟代碼範本。
  3. 填寫代碼範本設定的必要欄位。
  4. 按一下「Triggering」(觸發條件),然後選取適當的觸發條件,以決定代碼啟動時機。
  5. 儲存代碼並發布容器。

建立第一個自訂變數範本

自訂變數範本與標記範本類似,但有一些明顯的差異:

  • 自訂變數範本必須傳回值。

    變數會直接傳回一個值,而不是呼叫 data['gtmOnSuccess'] 表示完成。

  • 自訂變數範本適用於代碼管理工具 UI 的不同部分。

  • 如要根據自訂變數建立新變數,請勿依序前往「Tags」>「New」,而是依序前往「Variables」>「New」

如需建立自訂變數範本的完整指南,請參閱「建立自訂變數」一文。

「Export and import」(匯出及匯入)

如要與貴機構共用自訂範本,您可以匯出自訂範本,然後匯入其他代碼管理工具容器。如何匯出範本:

  1. 在代碼管理工具中,按一下「範本」
  2. 在清單中按一下想要匯出的範本名稱。即可在範本編輯器中開啟範本。
  3. 按一下「More Actions」選單 (),然後選取「Export」

如何匯入範本:

  1. 在代碼管理工具中,按一下「範本」
  2. 按一下 [新增],系統隨即會在範本編輯器中開啟空白範本。
  3. 按一下「More Actions」選單 (),然後選取「Import」
  4. 選取要匯入的 .tpl 檔案。