詳細的客戶端上下文 client-context-in-detail

「用戶端內容」代表動態組合的使用者資料集合。 您可以使用資料來判斷在指定情況下要顯示在網頁上的內容（內容定位）。 網站分析和頁面上的任何Javascript也能使用這些資料。

客戶端上下文主要包括以下方面：

要建立獨立會話儲存並將其添加到客戶端上下文，或建立與上下文儲存元件綁定的會話儲存。 AEM會安裝數個您可立即使用的內容存放區元件。 您可以將這些元件作為元件的基礎。

如需開啟用戶端內容、設定其顯示的資訊以及模擬使用者體驗的相關資訊，請參閱 用戶端內容.

工作階段存放區 session-stores

「用戶端內容」包含包含使用者資料的各種工作階段存放區。 儲存來自以下來源的資料：

客戶端上下文框架提供 javascript API 可用來與工作階段存放區互動，以讀取和寫入使用者資料，以及接聽和回應儲存事件。 您也可以為您用於內容定位或其他目的的使用者資料建立工作階段存放區。

會話儲存資料仍保留在客戶端上。 客戶端上下文不會將資料寫回伺服器。 若要將資料傳送至伺服器，請使用表單或開發自訂javascript。

每個工作階段存放區都是屬性值組的集合。 工作階段存放區代表資料（任何類型）的集合，其概念意義可由設計人員和/或開發人員決定。 以下範例javascript程式碼定義一個物件，代表工作階段存放區可能包含的設定檔資料：

{
  age: 20,
  authorizableId: "aparker@geometrixx.info",
  birthday: "27 Feb 1992",
  email: "aparker@geometrixx.info",
  formattedName: "Alison Parker",
  gender: "female",
  path: "/home/users/geometrixx/aparker@geometrixx.info/profile"
}

工作階段存放區可持續存在於各瀏覽器工作階段之間，或僅能存留於建立工作階段的瀏覽器工作階段。

內容存放區元件 context-store-components

內容存放區元件是可新增至用戶端內容的AEM元件。 通常，上下文儲存元件會顯示來自與其關聯之工作階段存放區的資料。 不過，上下文儲存元件顯示的資訊不限於工作階段儲存資料。

內容存放區元件可包含下列項目：

如需可新增至上下文存放區之已安裝上下文存放區元件的說明，請參閱 可用的客戶端上下文元件.

目標內容傳送 targeted-content-delivery

設定檔資訊也用於傳送 目標內容.

將用戶端內容新增至頁面 adding-client-context-to-a-page

將「用戶端內容」元件加入網頁內文區段，以啟用「用戶端內容」。 客戶端上下文元件節點的路徑為 /libs/cq/personalization/components/clientcontext. 要包括元件，請將以下代碼添加到頁面元件的JSP檔案中，該檔案位於 body 頁面的元素：

<cq:include path="clientcontext" resourceType="cq/personalization/components/clientcontext"/>

clientcontext元件會導致頁面載入實作用戶端內容的用戶端程式庫。

用戶端內容UI僅適用於製作執行個體。

擴展客戶端上下文 extending-client-context

若要擴充用戶端內容，請建立工作階段存放區並選擇性地顯示存放區資料：

建立工作階段存放區 creating-a-session-store

為需要添加到客戶端上下文並從中檢索的資料建立會話儲存。 一般而言，您可使用下列程式來建立工作階段存放區：

在personalization.stores.kernel用戶端程式庫中包含javascript，會在載入用戶端內容架構時建立儲存。

工作階段存放區類型 types-of-session-stores

工作階段存放區是在瀏覽器工作階段期間建立且可用，或保存在瀏覽器儲存或Cookie中。 用戶端內容javascript API定義了代表這兩種資料存放區類型的數個類別：

API也提供這些類別的擴充功能，這些類別專門用於儲存JSON資料或JSONP資料：

建立會話儲存對象 creating-the-session-store-object

用戶端程式庫資料夾的javascript會建立並初始化工作階段存放區。 然後，必須使用上下文儲存管理器註冊會話儲存。 下面的示例建立並註冊 CQ_Analytics.SessionStore 物件。

//Create the session store
if (!CQ_Analytics.MyStore) {
    CQ_Analytics.MyStore = new CQ_Analytics.SessionStore();
    CQ_Analytics.MyStore.STOREKEY = "MYSTORE";
    CQ_Analytics.MyStore.STORENAME = "mystore";
    CQ_Analytics.MyStore.data={};
}
//register the session store
if (CQ_Analytics.ClientContextMgr){
    CQ_Analytics.ClientContextMgr.register(CQ_Analytics.MyStore)
}

若要儲存JSON資料，下列範例會建立並註冊 CQ_Analytics.JSONStore 物件。

if (!CQ_Analytics.myJSONStore) {
    CQ_Analytics.myJSONStore = CQ_Analytics.JSONStore.registerNewInstance("myjsonstore",{});
}

建立上下文儲存元件 creating-a-context-store-component

建立上下文儲存元件以在客戶端上下文中呈現會話儲存資料。 建立後，您可以將內容存放區元件拖曳至「用戶端內容」，從工作階段存放區轉譯資料。 內容存放區元件包含下列項目：

擴充提供的內容存放區元件 extending-the-provided-context-store-components

AEM提供您可擴充的一般儲存和一般儲存屬性內容儲存元件。 儲存資料的結構會決定您擴充的元件：

在Sidekick中配置外觀 configuring-the-appearance-in-sidekick

編輯用戶端內容時，內容存放區元件會顯示在Sidekick中。 與所有元件一樣， componentGroup 和 jcr:title 客戶端上下文元件的屬性決定元件的組和名稱。

具有 componentGroup 屬性值 Client Context 預設會顯示在Sidekick中。 如果您對 componentGroup 屬性，您必須使用「設計」模式，手動將元件新增至Sidekick。

內容儲存元件例項 context-store-component-instances

將上下文儲存元件添加到客戶端上下文時，將在下面建立一個表示元件實例的節點 /etc/clientcontext/default/content/jcr:content/stores. 此節點包含使用元件的編輯對話框配置的屬性值。

初始化客戶端上下文時，將處理這些節點。

初始化關聯的會話儲存 initializing-the-associated-session-store

將init.js.jsp檔案新增至元件，以產生Javascript程式碼，初始化內容存放區元件所使用的工作階段存放區。 例如，使用初始化指令碼來檢索元件的配置屬性，並使用它們來填充會話儲存。

在製作和發佈例項的頁面載入上初始化「用戶端內容」時，產生的Javascript會新增至頁面。 此JSP在載入和呈現上下文儲存元件實例之前執行。

程式碼必須將檔案的mime類型設定為 text/javascript，或未執行。

以下過程將建立init.js.jsp指令碼檔案並添加設定正確mime類型的代碼。 執行儲存初始化的程式碼會隨之執行。

呈現一般儲存屬性元件的工作階段儲存資料 rendering-session-store-data-for-genericstoreproperties-components

使用一致格式在「用戶端內容」中顯示工作階段儲存資料。

顯示屬性資料 displaying-property-data

個人化taglib提供 personalization:storePropertyTag 標籤，顯示工作階段存放區中屬性的值。 要使用標籤，請在JSP檔案中包括以下代碼行：

<%@taglib prefix="personalization" uri="https://www.day.com/taglibs/cq/personalization/1.0" %>

標籤的格式如下：

<personalization:storePropertyTag propertyName="property_name" store="session_store_name"/>

此 propertyName 屬性是要顯示的儲存屬性的名稱。 此 store 屬性是已註冊儲存的名稱。 下列範例標籤會顯示 authorizableId 屬性 profile 商店：

<personalization:storePropertyTag propertyName="authorizableId" store="profile"/>

HTML結構 html-structure

personalization.ui用戶端資料庫資料夾(https://experienceleague.adobe.com/etc/clientlibs/foundation/personalization/ui/themes/default?lang=zh-Hant)提供用戶端內容用來設定HTML程式碼格式的CSS樣式。 下列程式碼說明用於顯示儲存資料的建議結構：

<div class="cq-cc-store">
   <div class="cq-cc-thumbnail">
      <div class="cq-cc-store-property">
           <!-- personalization:storePropertyTag for the store thumbnail image goes here -->
      </div>
   </div>
   <div class="cq-cc-content">
       <div class="cq-cc-store-property cq-cc-store-property-level0">
           <!-- personalization:storePropertyTag for a store property goes here -->
       </div>
       <div class="cq-cc-store-property cq-cc-store-property-level1">
           <!-- personalization:storePropertyTag for a store property goes here -->
       </div>
       <div class="cq-cc-store-property cq-cc-store-property-level2">
           <!-- personalization:storePropertyTag for a store property goes here -->
       </div>
       <div class="cq-cc-store-property cq-cc-store-property-level3">
           <!-- personalization:storePropertyTag for a store property goes here -->
       </div>
   </div>
   <div class="cq-cc-clear"></div>
</div>

此 /libs/cq/personalization/components/contextstores/profiledata 上下文儲存元件使用此結構來顯示來自設定檔工作階段存放區的資料。 此 cq-cc-thumbnail 類別會放置縮圖影像。 此 cq-cc-store-property-level*x* 類格式化字母數字資料：

呈現一般儲存元件的會話儲存資料 rendering-session-store-data-for-genericstore-components

若要使用一般存放區元件呈現存放區資料，您需要：

標識一般儲存會話儲存 identifying-the-genericstore-session-store

個人化taglib提供 personalization:storePropertyTag 標籤，顯示工作階段存放區中屬性的值。 要使用標籤，請在JSP檔案中包括以下代碼行：

<%@taglib prefix="personalization" uri="https://www.day.com/taglibs/cq/personalization/1.0" %>

標籤的格式如下：

<personalization:storeRendererTag store="store_name"/>

實作工作階段存放區轉譯器方法 implementing-the-session-store-renderer-method

接著，您的工作階段存放區將需要「轉譯器」方法，每次需要轉譯元件時都會呼叫此方法。 會使用兩個參數呼叫轉譯器函式：

與工作階段存放區互動 interacting-with-session-stores

使用javascript與工作階段存放區互動。

存取工作階段存放區 accessing-session-stores

獲取會話儲存對象以讀取或寫入儲存資料。 CQ_Analytics.ClientContextMgr 根據商店名稱提供對商店的訪問。 取得後，請使用 CQ-Analytics.SessionStore 或 CQ-Analytics.PersistedSessionStore 與儲存資料互動。

下列範例會取得 profile 儲存，然後擷取 formattedName 屬性。

function getName(){
   var profilestore = CQ_Analytics.ClientContextMgr.getRegisteredStore("profile");
   if(profilestore){
      return profilestore.getProperty("formattedName", false);
   } else {
      return null;
   }
}

建立偵聽器以響應會話儲存更新 creating-a-listener-to-react-to-a-session-store-update

工作階段會儲存引發事件，因此可以根據這些事件來新增接聽程式和觸發事件。

工作階段存放區是建置在 Observable 模式。 它們延伸 CQ_Analytics.Observable 提供 addListener 方法。

下面的示例將監聽程式添加到 update 事件 profile 工作階段存放區。

var profileStore = ClientContextMgr.getRegisteredStore("profile");
if( profileStore ) {
  //callback execution context
  var executionContext = this;

  //add "update" event listener to store
  profileStore.addListener("update",function(store, property) {
    //do something on store update

  },executionContext);
}

檢查會話儲存是否已定義並初始化 checking-that-a-session-store-is-defined-and-initialized

工作階段存放區必須先載入並透過資料初始化，才能使用。 下列因素可能會影響工作階段存放區可用性的時間：

使用 CQ_Analytics.ClientContextUtils 物件 onStoreRegistered 和 onStoreInitialized 僅在會話儲存可用時訪問這些儲存的方法。 這些方法可讓您註冊對工作階段註冊和初始化事件做出反應的事件偵聽器。

下列範例使用 onStoreRegistered 事件 profile 工作階段存放區。 註冊儲存時，會將監聽程式新增至 update 工作階段存放區的事件。 更新商店時， <div class="welcome"> 頁面上的元素會以 profile 儲存。

//listen for the store registration
CQ_Analytics.ClientContextUtils.onStoreRegistered("profile", listen);

//listen for the store's update event
function listen(){
 var profilestore = CQ_Analytics.ClientContextMgr.getRegisteredStore("profile");
    profilestore.addListener("update",insertName);
}

//insert the welcome message
function insertName(){
 $("div.welcome").text("Welcome "+getName());
}

//obtain the name from the profile store
function getName(){
 var profilestore = CQ_Analytics.ClientContextMgr.getRegisteredStore("profile");
 if(profilestore){
  return profilestore.getProperty("formattedName", false);
    } else {
        return null;
    }
}

將屬性排除在工作階段持續性Cookie之外 excluding-a-property-from-the-sessionpersistence-cookie

防止 PersistedSessionStore 不持續(亦即將其從 sessionpersistence cookie)，將屬性新增至持續工作階段存放區的非持續屬性清單。

請參閱 CQ_Analytics.PersistedSessionStore.setNonPersisted(propertyName)

CQ_Analytics.ClientContextUtils.onStoreRegistered("surferinfo", function(store) {
  //this will exclude the browser, OS and resolution properties of the surferinfo session store from the
  store.setNonPersisted("browser");
  store.setNonPersisted("OS");
  store.setNonPersisted("resolution");
});

配置設備滑桿 configuring-the-device-slider

條件 conditions

目前頁面必須有對應的行動頁面；唯有頁面已以行動轉出設定設定( rolloutconfig.path.toLowerCase 包含 mobile)。

設定 configuration

從案頭頁面切換至行動裝置對應頁面時：

例如：

window.CQMobileSlider["geometrixx-outdoors"] = {
  //CSS used by desktop that need to be removed when mobile
  DESKTOP_CSS: [
    "/etc/designs/${app}/clientlibs_desktop_v1.css"
  ],

  //CSS used by mobile that need to be removed when desktop
  MOBILE_CSS: [
    "/etc/designs/${app}/clientlibs_mobile_v1.css"
  ],

  //id of the content that needs to be removed when mobile
  DESKTOP_MAIN_ID: "main",

  //id of the content that needs to be removed when desktop
  MOBILE_MAIN_ID: "main",

  //body classes used by desktop that need to be removed when mobile
  DESKTOP_BODY_CLASS: [
    "page"
  ],

  //body classes used by mobile that need to be removed when desktop
  MOBILE_BODY_CLASS: [
    "page-mobile"
  ]
};

範例：建立自訂內容存放區元件 example-creating-a-custom-context-store-component

在此範例中，您會建立內容存放區元件，從外部服務擷取資料，並將其儲存在工作階段存放區中：

新增geoloc元件 add-the-geoloc-component

建立CQ應用程式並新增geoloc元件。

建立Geoloc編輯對話框 create-the-geoloc-edit-dialog

上下文儲存元件需要編輯對話方塊。 geoloc編輯對話方塊將包含靜態訊息，指出沒有要設定的屬性。

建立初始化指令碼 create-the-initialization-script

將init.js.jsp檔案新增至geoloc元件，並使用它建立工作階段存放區、擷取位置資料，並將其新增至存放區。

init.js.jsp檔案會在頁面載入用戶端內容時執行。 此時，用戶端內容javascript API已載入，可供您的指令碼使用。

呈現geoloc工作階段存放區資料 render-the-geoloc-session-store-data

將代碼添加到geoloc元件的JSP檔案中，以在客戶端上下文中呈現儲存資料。

將元件新增至用戶端內容 add-the-component-to-client-context

將Location Store元件新增至用戶端內容，以便在頁面載入時初始化元件。

請參閱用戶端內容中的位置資訊 see-the-location-information-in-client-context

以編輯模式開啟Geometrixx Outdoors首頁，然後開啟用戶端內容以查看位置儲存元件中的資料。

建立自訂用戶端內容 creating-a-customized-client-context

若要建立第二個用戶端內容，您需要複製分支：

/etc/clientcontext/default

若要使用自訂的用戶端內容，請編輯屬性
path
（如頁面範本中所包含）。 例如，作為的標準位置：
/libs/cq/personalization/components/clientcontext/design_dialog/items/path