從 at.js 1.x 升級為 at.js 2.x

Adobe Target 中的最新版 at.js 提供豐富的功能,讓貴公司能以新世代用戶端技術為基礎進行個人化。本次的新版本著重於升級 at.js,進而與單一頁面應用程式 (SPA) 產生和諧互動。

以下是幾個使用 at.js 2.x 特有 (舊版未提供) 的優點:

  • 可在頁面載入時快取所有選件,以減少對單一伺服器呼叫發出的多個伺服器呼叫。
  • 大幅改善一般使用者在網站上的體驗,因為選件能透過快取立即顯示,避免傳統伺服器呼叫引發的延遲時間。
  • 簡單的單行程式碼和一次性開發人員設定,讓行銷人員可透過 VEC 在 SPA 上建立和執行 A/B 和 (XT) 活動。

at.js 2.x 系統圖表

下列圖表可協助您瞭解 at.js 2.x 搭配檢視的工作流程,以及如何藉由這套工作流程增強 SPA 整合。如需 at.js 2.x 中所使用概念的詳細介紹,請參閱實作單頁應用程式

使用 at.js 2.x 的 Target 流程

呼叫 詳細資料
1 如果使用者已通過驗證,呼叫會傳回 Experience Cloud ID,而另一個呼叫會同步客戶 ID。
2 at.js 程式庫會同步載入並隱藏文件本文。
也能使用將頁面上實作的程式碼片段預先隱藏的選項,以非同步方式載入 at.js。
3 提出頁面載入要求,包含所有已設定的參數 (MCID、SDID 和客戶 ID)。
4 設定檔指令碼執行,然後注入設定檔存放區。存放區會從對象資料庫中請求合格對象 (例如,從 Adobe Analytics、對象管理 等共用的對象)。
客戶屬性會透過批次程序傳送至設定檔存放區。
5 Target 會根據 URL 要求參數和設定檔資料,決定可針對目前頁面和未來檢視傳回哪些活動和體驗給訪客。
6 目標內容會傳回至頁面,選擇性地包括其他個人化的設定檔值。
目前頁面上目標內容會儘快出現,不會有忽隱忽現的預設內容。
針對在瀏覽器中快取的使用者 SPA 動作顯示檢視的目標內容,以便在透過 triggerView() 觸發檢視時立刻套用,不需額外的伺服器呼叫。
7 Analytics 資料傳送至「資料收集」伺服器。
8 目標資料會透過 SDID 來比對 Analytics 資料,然後經過處理放入 Analytics 報表儲存體中。然後就可以在 Analytics 與 Target 中,透過 Analytics for Target (A4T) 報表來檢視
Analytics 資料。

現在,SPA 上只要是有實作 triggerView() 的位置,系統都會從快取擷取檢視和動作並向使用者顯示,不需要伺服器呼叫。triggerView() 也會對 Target 後端發出通知要求,以便增加和記錄曝光計數。

Target 流程 at.js 2.x triggerView

呼叫 詳細資料
1 系統在 SPA 中呼叫 triggerView(),以便呈現檢視和套用動作來修改視覺元素。
2 從快取讀取檢視的目標內容。
1 目標內容會儘快出現,不會有忽隱忽現的預設內容。
4 通知要求會傳送至 Target 設定檔存放區,以計算活動中的訪客數和增加量度。
5 Analytics 資料傳送至資料收集伺服器。
6 Target 資料會透過 SDID 來比對 Analytics 資料,然後經過處理放入 Analytics 報表儲存體中。然後就可以在 Analytics 與 Target 中,透過 A4T 報表來檢視 Analytics 資料。

部署 at.js 2.x

  1. 透過Adobe Launch 擴充功能部署 at.js 2.x

    注意

    偏好使用的方法是使用 Adobe Launch 部署 at.js。

    使用 Target UI 手動下載 at.js 2.x,並使用您所選擇的方法進行部署。

棄用的 at.js 函數

at.js 2.x 已棄用多個函數。

重要

如果部署 at.js 2.x 時您的網站上仍使用這些已棄用的函數,便會顯示主控台警告。建議的升級做法是在預備環境中測試 at.js 2.x 部署,並確實逐一瀏覽每個記錄到主控台中的警告,並將棄用的函數轉譯為 at.js 2.x 中推出的新函數。

已棄時的函數及其對應的新函數如下所列。如需完整的函數清單,請參閱 at.js 函數

注意

at.js 2.x 不再自動預先隱藏標示為 mboxDefault 的元素。因此客戶必須在網站上或透過標籤管理程式,手動提供預先隱藏邏輯。

mboxCreate(mbox,params)

說明:

執行要求並將選件套用至具有 mboxDefault 類別名稱的最接近 DIV。

範例:

<div class="mboxDefault">
  default content to replace by offer
</div>
<script>
  mboxCreate('mboxName','param1=value1','param2=value2');
</script>

at.js 2.x 等同項目

mboxCreate(mbox, params) 的替代函數為 getOffer()applyOffer()

範例:

<div class="mboxDefault"> 
  default content to replace by offer 
</div> 
<script> 
  var el = document.currentScript.previousElementSibling;
  adobe.target.getOffer({
    mbox: "mboxName",
    params: {
      param1: "value1",
      param2: "value2"
    },
    success: function(offer) {
      adobe.target.applyOffer({
        mbox: "mboxName",
        selector: el,
        offer: offer
      });
    },
    error: function(error) {
      console.error(error);
      el.style.visibility = "visible";
    }
  });
</script> 

mboxDefine() 和 mboxUpdate()

說明:

在元素與 mbox 名稱之間建立內部對應,但是不執行要求。與 mboxUpdate() 搭配使用,會執行要求並將選件套用至 mboxDefine() 中的 nodeId 所識別的元素。也可用來更新 mboxCreate 起始的 mbox。

範例:

<div id="someId" class="mboxDefault"></div>
<script>
 mboxDefine('someId','mboxName','param1=value1','param2=value2');
 mboxUpdate('mboxName','param3=value3','param4=value4');
</script>

at.js 2.x 等同項目:

mboxDefine()mboxUpdate 的替代函數為 getOffer()applyOffer(),而 applyOffer() 中會使用選取器選項。此做法可讓您使用任何 CSS 選取器將選件對應至元素,而非只能使用帶有 ID 的選取器。

範例:

<div id="someId" class="mboxDefault"> 
  default content to replace by offer 
</div> 
<script> 
  adobe.target.getOffer({
    mbox: "mboxName",
    params: {
      param1: "value1",
      param2: "value2",
      param3: "value3",
      param4: "value4" 
    },
    success: function(offer) {
      adobe.target.applyOffer({
        mbox: "mboxName",
        selector: "#someId",
        offer: offer
      });
    },
    error: function(error) {
      console.error(error);
      var el = document.getElementById("someId");
      el.style.visibility = "visible";
    }
  });
</script>

adobe.target.registerExtension()

說明:

提供標準方式來註冊特定的延伸模組。

此函數不再受支援且不應使用。

2 中棄用、新增和支援的 at.js 函數摘要.x

方法 支援? 新增? 已過時?
(將顯示預設內容)
getOffer()
getOffers()
applyOffer()
applyOffers()
triggerView()
trackEvent()
mboxCreate()
mboxDefine()
mboxUpdate()
targetGlobalSettings()
Data Providers
targetPageParams()
targetPageParamsAll()
registerExtension()
At.js Custom Events

限制和圖說

請留意下列限制和圖說:

轉換追蹤

客戶使用 mboxCreate() 追蹤轉換時必須使用 trackEvent()getOffer()

選件傳送

客戶若沒有將 mboxCreate() 取代為 getOffer()applyOffer(),選件可能不會傳送。

at.js 2.x 是否能在某些頁面上使用,並在其他頁面上使用 at.js 1.x 或 mbox.js?

可以,使用不同版本和資料庫的頁面中會保留訪客設定檔。Cookie 格式相同。

at.js 2.x 使用的新 API

at.js 2.x 使用新的 API,我們稱之為「傳送 API」。若要針對 at.js 是否正確呼叫 Target Edge 伺服器進行除錯,您可以將瀏覽器上「開發人員工具」的「網路」索引標籤篩選為「傳送」、「tt.omtrdc.net」或您的用戶端代碼。您也會發現 Target 傳送的是 JSON 裝載而非機碼值組。

不再使用 Target 全域 mbox

在 at.js 2.x 中,網路呼叫中不會再出現「target-global-mbox」。我們已改為將傳送至 Target 伺服器的 JSON 裝載中的「target-global-mbox」語法取代為「execute > pageLoad」,如下所示:

{
  "id": {
    // ...
  },
  "context": {
    "channel": "web",
    // ...
  },
  "execute": {
    "pageLoad": {}
  }
}

基本上,推出全域 mbox 概念的目的,是用來告知 Target 是否要在頁面載入時擷取選件和內容。因此我們在最新版本中讓這個用途更加明確。

at.js 中的全域 mbox 名稱仍重要嗎?

客戶可以透過Target >管理>實作>編輯at.js設定來指定全域mbox名稱。 此設定供 Target Edge 伺服器用來將 execute > pageLoad 轉譯為 Target UI 中顯示的全域 mbox 名稱。這麼做可讓客戶繼續使用伺服器端 API、表單式撰寫器、設定檔指令碼,以及使用全域 mbox 名稱建立對象。我們強烈建議您也務必在管理> Visual Experience Composer頁面上設定相同的全域mbox名稱,以防您仍有使用at.js 1的頁面。X 或 mbox.js),如下圖所示。

修改 at.js 對話方塊

自訂全域 mbox

需要為 at.js 2.x 開啟自動建立全域 mbox 設定嗎?

在大多數情況下需要。此設定可告知 at.js 2.x 在頁面載入時向 Target Edge 伺服器引發要求。由於全域 mbox 已轉譯為 execute > pageLoad,因此如果您想在頁面載入時觸發要求,便應開啟此設定。

即使沒有從 at.js 2.x 指定 Target 全域 mbox 名稱,現有的 VEC 活動仍會繼續運作嗎?

會,因為 execute > pageLoad 在 Target 後端上的處理方式如同 target-global-mbox

如果我的表單式活動目標鎖定為 target-global-mbox,這些活動是否仍會繼續運作?

會,因為 execute > pageLoad 在 Target Edge 伺服器上的處理方式如同 target-global-mbox

支援和不支援的 at.js 2.x 設定

設定 支援?
X-Domain
自動建立全域 mbox
全域 mbox 名稱

at.js 2.x 中的跨網域追蹤支援

跨網域追蹤能夠拼接不同網域之間的訪客。由於必須為各個網域建立新 Cookie,因此在訪客從某個網域導覽至另一個網域時,就很難加以追蹤。為實現跨網域追蹤,Target 使用協力廠商 Cookie 來追蹤網域之間的訪客。這可讓您建立橫跨 siteA.comsiteB.com 的 Target 活動,而且當訪客在各個唯一網域導覽時,訪客會維持相同的體驗。此功能與 Target 的第三方和第一方 Cookie 行為整合。

注意

at.js 2.x 不提供跨網域追蹤的立即可用支援。at.js 2.x 可透過 Experience Cloud ID (ECID) 資料庫 v4.3.0+ 支援跨網域追蹤。

在 Target 中,協力廠商 Cookie 會儲存在 <CLIENTCODE>.tt.omtrdc.net 中。第一方 Cookie 會儲存在 clientdomain.com 中。第一個要求會傳回 HTTP 回應標頭,此標頭嘗試設定名為 mboxSessionmboxPC 的第三方 Cookie,之後傳回附有額外參數 (mboxXDomainCheck=true) 的重新導向要求。若瀏覽器接受協力廠商 Cookie,則重新導向請求會包含這些 Cookie 並傳回體驗。這個工作流程之所以可行,是因為我們使用 HTTP GET 方法。

不過,at.js 2.x 已不再使用 HTTP GET,而是改用 HTTP POST。您現在可透過 at.js 2.x 使用 HTTP POST,將 JSON 裝載傳送至 Target Edge 伺服器。這表示檢查瀏覽器是否支援第三方 Cookie 的重新導向要求現在已失效。這是因為 HTTP GET 要求為等冪交易,而 HTTP POST 是非等冪交易且不得任意重複。因此,at.js 2.x 中的跨網域追蹤不再提供立即可用支援。只有 at.js 1.x 才提供跨網域追蹤的立即可用支援。

如果您想要使用跨網域追蹤,則必須與at.js 2一起安裝ECID程式庫v4.3.0+x 不提供跨網域追蹤的立即可用支援。ECID 資料庫的存在是為了管理可用來識別訪客 (甚至是跨網域) 的持續 ID。

注意

安裝 ECID 資料庫 v4.3.0+ 和 at.js 2.x 後,您將能建立橫跨多個唯一網域的活動以及追蹤使用者。請務必注意,此功能只有在工作階段過期後才能運作。

支援自動建立全域 mbox

此設定可告知 at.js 2.x 在頁面載入時向 Target Edge 伺服器引發要求。由於全域 mbox 已轉譯為 execute > pageLoad,且會由 Target Edge 伺服器加以解譯,因此顧客如果希望在頁面載入時觸發要求,便應開啟此功能。

支援全域 mbox 名稱

客戶可以透過Target >管理>實作>編輯來指定全域mbox名稱。 此設定供 Target Edge 伺服器用來將 execute > pageLoad 轉譯為輸入的全域 mbox 名稱。這麼做可讓客戶繼續使用伺服器端 API、表單式撰寫器、設定檔指令碼,以及建立鎖定全域 mbox 為目標的對象。

以下 at.js 自訂事件適用於 triggerView(),還是僅適用於 applyOffer()applyOffers()?

  • adobe.target.event.CONTENT_RENDERING_FAILED
  • adobe.target.event.CONTENT_RENDERING_SUCCEEDED
  • adobe.target.event.CONTENT_RENDERING_NO_OFFERS
  • adobe.target.event.CONTENT_RENDERING_REDIRECT

是的,at.js 自訂事件也適用於 triggerView()

它說,當我使用&lbrace;“page” : “true”&rbrace;呼叫triggerView()時,會傳送通知給Target後端並增加印象。 那麼也會造成設定檔指令碼執行嗎?

對 Target 後端發出預先擷取呼叫時,會執行設定檔指令碼,接著會加密受影響的設定檔資料,然後傳回用戶端。叫用含有 {"page": "true"}triggerView() 後,會傳送通知並附上加密的設定檔資料。此時 Target 後端會將設定檔資料解密並儲存至資料庫中。

呼叫 triggerView() 之前需要新增預先隱藏程式碼以處理忽隱忽現情況嗎?

不需要,您不需要在呼叫 triggerView() 之前新增預先隱藏程式碼。at.js 2.x 會在顯示和套用檢視之前,處理預先隱藏和忽隱忽現的邏輯。

這是at.js 1.at. js 2不支援建立觀眾的xparameters。x?

下列at.js 1.x參數目前支援​NOT​在使用at.js 2時建立觀眾。x 中的頁面載入要求:

  • browserHeight
  • browserWidth
  • browserTimeOffset
  • screenHeight
  • screenWidth
  • screenOrientation
  • colorDepth
  • devicePixelRatio

at.js 相容性

下表說明 at.js。2.x​與不同活動類型、整合、功能和at.js函式相容。

活動類型

類型 支援?
A/B 測試
自動分配
自動鎖定目標
體驗鎖定目標
多變數測試
自動個人化
建議
注意

所有修改皆已套用至 Page Load Event 時,可透過 at.js 2.x 和 VEC 支援自動鎖定目標活動。修改已新增至特定視圖時,僅支援 A/B 測試、自動分配和體驗鎖定目標 (XT) 活動。

整合

類型 支援?
目標分析 (A4T)
對象
客戶屬性
AEM 體驗片段
Adobe Launch 擴充功能
除錯程式
Auditor 尚未針對 at.js 2.x 更新規則
動態標籤管理 (DTM)
選擇加入 無。at.js 版本 2.1.0 支援 GDPR 的選擇加入支援
採用 Adobe Target 技術的 AEM 增強型個人化

功能

功能 支援?
X域
屬性/工作區
QA 連結
表單式體驗撰寫器
可視化體驗撰寫器 (VEC)
自訂程式碼
回應 Token
點擊追蹤
多活動傳送
targetGlobalSettings 支援 (但不支援跨網域)
at.js 方法 除了下列會顯示預設內容的方法以外均支援:
mboxCreate()
mboxUpdate()
mboxDefine()

查詢字串參數

參數 支援?
?mboxDisable
?mboxDisable
?mboxTrace
?mboxSession
?mboxOverride.browserIp

回應 Token

at.js 2.x,就像 at.js 1.x,使用自訂事件 at-request-succeeded 來呈現回應 Token。如需使用 at-request-succeeded 自訂事件的程式碼範例,請參閱回應 Token

at.js 1. 參數x至at.js 2。x 的裝載對應

本節概述 at.js 1.x 與 at.js 2.x 之間的對應。

探索參數對應之前,請注意這些資料庫版本使用的端點已變更:

  • at.js 1.x - http://<client code>.tt.omtrdc.net/m2/<client code>/mbox/json
  • at.js 2.x - http://<client code>.tt.omtrdc.net/rest/v1/delivery

另一項顯著差異為:

  • at.js 1.x - 用戶端代碼是路徑的一部分
  • at.js 2.x - 用戶端代碼會以查詢字串參數的形式傳送,例如:
    http://<client code>.tt.omtrdc.net/rest/v1/delivery?client=democlient

以下各節列出每個 at.js 1.xparameter、其說明和對應的2。 xJSON裝載(如果適用):

at_property

(at.js 1.x 參數)

用於企業使用者權限

{
  ....
  "property": {
    "token": "1213213123122313121"
  }
  ....
}

mboxHost

(at.js 1.x 參數)

Target 資料庫執行所在位置的頁面網域。

at.js 2.x JSON 裝載:

{
  "context": {
    "browser": {
       "host": "test.com"
    }
  }
}

webGLRenderer

(at.js 1.x 參數)

瀏覽器的 WEB GL 轉譯器功能我們的裝置偵測機制會使用此功能,判斷訪客的裝置是否為桌上型電腦、iPhone、Android 裝置等。

at.js 2.x JSON 裝載:

{
  "context": {
    "browser": {
       "webGLRenderer": "AMD Radeon Pro 560X OpenGL Engine"
    }
  }
}

mboxURL

(at.js 1.x 參數)

頁面 URL。

at.js 2.x JSON 裝載:

{
  "context": {
    "address": {
       "url": "http://test.com"
    }
  }
}

mboxReferrer

(at.js 1.x 參數)

頁面轉介者。

at.js 2.x JSON 裝載:

{
  "context": {
    "address": {
       "referringUrl": "http://google.com"
    }
  }
}

mbox (名稱) 等於全域 mbox

(at.js 1.x 參數)

傳遞 API 已無全域 mbox 概念。在 JSON 裝載中,您必須使用 execute > pageLoad

at.js 2.x JSON 裝載:

{
  "execute": {
    "pageLoad": {
       "parameters": ....
       "profileParameters": ...
       .....
    }
  }
}

mbox (名稱) ​等於全域 mbox

(at.js 1.x 參數)

若要使用 mbox 名稱,請將其傳遞至 execute > mboxes。mbox 需要索引和名稱。

at.js 2.x JSON 裝載:

{
  "execute": {
    "mboxes": [{
       "index": 0,
       "name": "some-mbox",
       "parameters": ....
       "profileParameters": ...
       .....
    }]
  }
}

mboxId

(at.js 1.x 參數)

已不再使用。

mboxCount

(at.js 1.x 參數)

已不再使用。

mboxRid

(at.js 1.x 參數)

下游系統用來協助進行偵錯的要求 ID。

at.js 2.x JSON 裝載:

{
  "requestId": "2412234442342"
  ....
}

mboxTime

(at.js 1.x 參數)

已不再使用。

mboxSession

(at.js 1.x 參數)

工作階段 ID 會以查詢字串參數 (sessionId) 的形式傳送至傳送 API 端點。

mboxPC

(at.js 1.x 參數)

TNT ID 會傳遞至 id > tntId

at.js 2.x JSON 裝載:

{
  "id": {
    "tntId": "ca5ddd7e33504c58b70d45d0368bcc70.21_3"
  }
  ....
}

mboxMCGVID

(at.js 1.x 參數)

Marketing Cloud 訪客 ID 會傳遞至 id > marketingCloudVisitorId

at.js 2.x JSON 裝載:

{
  "id": {
    "marketingCloudVisitorId": "797110122341429343505"
  }
  ....
}

vst.aaaa.idvst.aaaa.authState

(at.js 1.x 參數)

客戶 ID 應傳遞至 id > customerIds

at.js 2.x JSON 裝載:

{
  "id": {
    "customerIds": [{
       "id": "1232131",
       "integrationCode": "aaaa",
       "authenticatedState": "....."
     }]
  }
  ....
}

mbox3rdPartyId

(at.js 1.x 參數)

用來連結不同 Target ID 的客戶協力廠商 ID。

at.js 2.x JSON 裝載:

{
  "id": {
    "thirdPartyId": "1232312323123"
  }
  ....
}

mboxMCSDID

(at.js 1.x 參數)

SDID (也稱為補充資料 ID)。應傳遞至 experienceCloud > analytics > supplementalDataId

at.js 2.x JSON 裝載:

{
  "experienceCloud": {
    "analytics": {
      "supplementalDataId": "1212321132123131"
    }
  }
  ....
}

vst.trk

(at.js 1.x 參數)

Analytics 追蹤伺服器。應傳遞至 experienceCloud > analytics > trackingServer

at.js 2.x JSON 裝載:

{
  "experienceCloud": {
    "analytics": {
      "trackingServer": "analytics.test.com"
    }
  }
  ....
}

vst.trks

(at.js 1.x 參數)

Analytics 追蹤伺服器安全。應傳遞至 experienceCloud > analytics > trackingServerSecure

at.js 2.x JSON 裝載:

{
  "experienceCloud": {
    "analytics": {
      "trackingServerSecure": "secure-analytics.test.com"
    }
  }
  ....
}

mboxMCGLH

(at.js 1.x 參數)

Audience Manager 位置提示。應傳遞至 experienceCloud > audienceManager > locationHint

at.js 2.x JSON 裝載:

{
  "experienceCloud": {
    "audienceManager": {
      "locationHint": 9
    }
  }
  ....
}

mboxAAMB

(at.js 1.x 參數)

Audience Manager Blob。應傳遞至 experienceCloud > audienceManager > blob

at.js 2.x JSON 裝載:

{
  "experienceCloud": {
    "audienceManager": {
      "blob": "2142342343242342"
    }
  }
  ....
}

mboxVersion

(at.js 1.x 參數)

版本會透過版本參數以查詢字串參數的形式傳送。

訓練影片:at.js 2.X體系結構 圖概 述徽章

at.js 2.x 增強了 Adobe Target 對 SPA 的支援,並與其他 Experience Cloud 解決方案整合。本影片說明整合方式。

請參閱瞭解at.js 2的方式。** xworks以取得詳細資訊。

本頁內容

Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now