Présentation détaillée de ClientContext client-context-in-detail

ClientContext représente un ensemble de données utilisateur assemblées de manière dynamique. Vous pouvez utiliser les données pour déterminer le contenu à afficher sur une page web dans une situation donnée (ciblage du contenu). Les données sont également disponibles pour les analyses de site web, ainsi que pour tout code JavaScript sur la page.

ClientContext se compose principalement des aspects suivants :

Pour créer un magasin de sessions autonome et l’ajouter à ClientContext, ou créer un magasin de sessions lié à un composant Boutique de contexte. AEM installe plusieurs composants de magasin de contexte que vous pouvez utiliser immédiatement. Vous pouvez utiliser ces composants comme base de vos composants.

Pour plus d’informations sur l’ouverture de contexte client, la configuration des informations affichées et la simulation de l’expérience utilisateur, consultez Contexte client.

Magasins de session session-stores

ClientContext comprend divers magasins de sessions contenant des données utilisateur. Les données de magasin proviennent des sources suivantes :

La structure ClientContext fournit une API javascript que vous pouvez utiliser pour interagir avec les magasins de sessions afin de lire et d’écrire des données utilisateur, ainsi que d’écouter les événements de magasin et d’y réagir. Vous pouvez également créer des magasins de sessions pour les données utilisateur que vous utilisez pour le ciblage de contenu ou à d’autres fins.

Les données du magasin de sessions restent sur le client. ClientContext n’écrit pas de données sur le serveur. Pour envoyer des données au serveur, utilisez un formulaire ou développez du code JavaScript personnalisé.

Chaque magasin de sessions est un ensemble de paires de type propriété-valeur. Le magasin de sessions représente un ensemble de données (de n’importe quel type), dont la signification conceptuelle peut être déterminée par le concepteur et/ou le développeur. L’exemple de code JavaScript suivant définit un objet qui représente les données de profil que le magasin de sessions peut contenir :

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

Un magasin de sessions peut être conservé entre deux sessions de navigateur ou prendre fin avec la session au cours de laquelle il a été créé.

Composants de magasin de contexte context-store-components

Un composant de magasin de contexte est un composant AEM qui peut être ajouté à ClientContext. En règle générale, les composants de magasin de contexte affichent les données d’un magasin de sessions auquel ils sont associés. Toutefois, les informations affichées par les composants de magasin de contexte ne se limitent pas aux données du magasin de sessions.

Les composants de magasin de contexte peuvent inclure les éléments suivants :

Pour obtenir une description des composants de magasin de contexte installés que vous pouvez ajouter au magasin de contexte, voir Composants ClientContext disponibles.

Diffusion de contenu ciblée targeted-content-delivery

Des informations de profil sont également utilisées pour diffuser du contenu ciblé.

Ajout De ClientContext À Une Page adding-client-context-to-a-page

Insérez le composant ClientContext dans la section body de vos pages web pour activer ClientContext. Le chemin d’accès du nœud de composant de contexte client est /libs/cq/personalization/components/clientcontext. Pour inclure le composant, ajoutez le code suivant au fichier JSP de votre composant de page situé juste en dessous de l’élément body de la page :

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

Le composant clientcontext entraîne le chargement de la page par les bibliothèques clientes qui implémentent ClientContext.

L’interface utilisateur de ClientContext n’est disponible que sur l’instance de création.

Extension du contexte client extending-client-context

Pour étendre ClientContext, créez un magasin de sessions et affichez éventuellement les données du magasin :

Création d’un magasin de sessions creating-a-session-store

Créez un magasin de sessions pour les données que vous devez ajouter à et récupérer à partir de ClientContext. En règle générale, vous utilisez la procédure suivante pour créer un magasin de sessions :

L’inclusion du code JavaScript dans la bibliothèque cliente personalization.stores.kernel entraîne la création du magasin lors du chargement de la structure ClientContext.

Types de magasins de sessions types-of-session-stores

Les magasins de sessions sont créés et disponibles au cours d’une session de navigateur, ou sont conservés dans l’espace de stockage du navigateur ou les cookies. L’API JavaScript ClientContext définit plusieurs classes qui représentent les deux types de entrepôts de données :

L’API fournit également des extensions de ces classes qui sont spécialisées pour le stockage des données JSON ou JSONP :

Création de l’objet de magasin de sessions creating-the-session-store-object

Le code JavaScript de votre dossier de bibliothèques clientes crée et initialise le magasin de sessions. Le magasin de sessions doit ensuite être enregistré à l’aide du gestionnaire de magasin de contexte. L’exemple suivant crée et enregistre un objet 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)
}

Pour stocker des données JSON, l’exemple suivant crée et enregistre un objet CQ_Analytics.JSONStore.

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

Création d’un composant de magasin de contexte creating-a-context-store-component

Créez un composant de magasin de contexte pour effectuer le rendu des données de magasin de sessions dans ClientContext. Une fois créé, vous pouvez faire glisser votre composant de magasin de contexte sur ClientContext pour effectuer le rendu des données d’un magasin de sessions. Les composants de magasin de contexte se composent des éléments suivants :

Extension des composants de magasin de contexte fournis extending-the-provided-context-store-components

AEM fournit les composants genericstore et genericstoreproperties context store que vous pouvez étendre. La structure de vos données de magasin détermine le composant que vous étendez :

Configuration de l’aspect dans le sidekick configuring-the-appearance-in-sidekick

Lors de la modification de ClientContext, les composants de magasin de contexte apparaissent dans le sidekick. Comme c’est le cas avec tous les composants, les propriétés componentGroup et jcr:title du composant contexte client déterminent son groupe et son nom.

Tous les composants dont la valeur de propriété componentGroup est définie sur Client Context sont affichés, par défaut, dans le sidekick. Si vous utilisez une autre valeur pour la propriété componentGroup, vous devez ajouter manuellement le composant au sidekick à l’aide du mode Création.

Instance du composant de magasin de contexte context-store-component-instances

Lorsque vous ajoutez un composant de magasin de contexte de contexte client, un nœud représentant l’instance du composant est créé sous /etc/clientcontext/default/content/jcr:content/stores. Ce noeud contient les valeurs de propriété configurées à l’aide de la boîte de dialogue de modification du composant.

Lorsque ClientContext est initialisé, ces noeuds sont traités.

Initialisation du magasin de sessions associé initializing-the-associated-session-store

Ajoutez un fichier init.js.jsp à votre composant afin de générer le code JavaScript qui initialise le magasin de sessions utilisé par votre composant de magasin de contexte. Utilisez, par exemple, le script d’initialisation pour récupérer les propriétés de configuration du composant et les utiliser pour remplir le magasin de sessions.

Le code JavaScript généré est ajouté à la page lorsque ClientContext est initialisé au chargement de la page sur les instances de création et de publication. Ce JSP est exécuté avant le chargement et le rendu de l’instance du composant de magasin de contexte.

Le code doit définir le type MIME du fichier sur text/javascript, sans quoi il ne sera pas exécuté.

La procédure suivante crée le fichier de script init.js.jsp et ajoute le code qui définit le type MIME correct. Le code qui effectue l’initialisation du magasin suit.

Rendu des données du magasin de sessions pour les composants genericstoreproperties rendering-session-store-data-for-genericstoreproperties-components

Affichez les données du magasin de sessions dans ClientContext dans un format cohérent.

Affichage des données de propriété displaying-property-data

La bibliothèque de balises de personnalisation fournit la balise personalization:storePropertyTag qui affiche la valeur d’une propriété à partir d’un magasin de sessions. Pour utiliser la balise , insérez la ligne de code suivante dans votre fichier JSP :

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

Le format de la balise est le suivant :

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

L’attribut propertyName est le nom de la propriété de magasin à afficher. L’attribut store est le nom du magasin enregistré. L’exemple de balise suivant affiche la valeur de la propriété authorizableId du magasin profile :

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

Structure de HTML html-structure

Le dossier de bibliothèque cliente personalization.ui (https://experienceleague.adobe.com/etc/clientlibs/foundation/personalization/ui/themes/default?lang=fr) fournit les styles CSS que ClientContext utilise pour formater le code de HTML. Le code suivant illustre la structure suggérée à utiliser pour l’affichage des données de magasin :

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

Le composant de magasin de contexte /libs/cq/personalization/components/contextstores/profiledata utilise cette structure pour afficher des données issues du magasin de sessions profile. La classe cq-cc-thumbnail place la miniature. Les classes cq-cc-store-property-level*x* mettent en forme les données alphanumériques :

Rendu des données du magasin de sessions pour les composants genericstore rendering-session-store-data-for-genericstore-components

Pour effectuer le rendu des données de magasin à l’aide d’un composant genericstore, vous devez :

Identification du magasin de sessions genericstore identifying-the-genericstore-session-store

La bibliothèque de balises de personnalisation fournit la balise personalization:storePropertyTag qui affiche la valeur d’une propriété à partir d’un magasin de sessions. Pour utiliser la balise , insérez la ligne de code suivante dans votre fichier JSP :

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

Le format de la balise est le suivant :

<personalization:storeRendererTag store="store_name"/>

Mise en oeuvre de la méthode de rendu du magasin de sessions implementing-the-session-store-renderer-method

Votre magasin de sessions aura alors besoin d’une méthode "renderer" qui sera appelée chaque fois que le composant doit être rendu. La fonction de rendu est appelée avec deux paramètres :

Interaction avec les magasins de sessions interacting-with-session-stores

Utilisez JavaScript pour interagir avec les magasins de sessions.

Accès aux magasins de sessions accessing-session-stores

Procurez-vous un objet de magasin de sessions pour lire ou écrire des données dans le magasin. CQ_Analytics.ClientContextMgr permet d’accéder aux magasins en fonction du nom du magasin. Une fois obtenus, utilisez les méthodes de la variable CQ-Analytics.SessionStore ou CQ-Analytics.PersistedSessionStore pour interagir avec les données du magasin.

L’exemple suivant récupère le magasin profile et ensuite la propriété formattedName depuis le magasin.

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

Création d’un écouteur pour réagir à une mise à jour de magasin de sessions creating-a-listener-to-react-to-a-session-store-update

La session stocke des événements de déclenchement. Il est donc possible d’ajouter des écouteurs et de déclencher des événements en fonction de ces événements.

Les magasins de sessions s’articulent autour du motif Observable. Ils étendent la propriété CQ_Analytics.Observable qui fournit la méthode addListener.

L’exemple suivant ajoute un écouteur à l’événement update du magasin de sessions 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);
}

Vérification de la définition et de l’initialisation d’un magasin de sessions checking-that-a-session-store-is-defined-and-initialized

Les magasins de sessions ne sont pas disponibles tant qu’ils ne sont pas chargés et initialisés avec des données. Les facteurs suivants peuvent affecter le délai de disponibilité du magasin de sessions :

Utilisez la variable CQ_Analytics.ClientContextUtils de onStoreRegistered et onStoreInitialized pour accéder aux magasins de sessions uniquement lorsqu’ils sont disponibles. Ces méthodes vous permettent d’enregistrer les écouteurs d’événements qui réagissent aux événements d’enregistrement et d’initialisation de session.

L’exemple suivant utilise l’événement onStoreRegistered du magasin de sessions profile. Lorsque le magasin de sessions est enregistré, un écouteur est ajouté à l’événement update correspondant. Lorsque le magasin est mis à jour, le contenu de l’élément <div class="welcome"> sur la page est mis à jour avec le nom issu du magasin 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;
    }
}

Exclusion d’une propriété du cookie sessionpersistence excluding-a-property-from-the-sessionpersistence-cookie

Pour empêcher qu’une propriété d’un PersistedSessionStore soit conservée (c’est-à-dire, pour l’exclure du cookie sessionpersistence), ajoutez la propriété à la liste des propriétés non persistantes du magasin de sessions persistant.

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

Configuration du curseur de périphérique configuring-the-device-slider

Conditions conditions

La page en cours doit être associée à une page pour mobiles correspondante ; cela est déterminé uniquement si la page possède une Live Copy configurée pour un déploiement sur mobiles (rolloutconfig.path.toLowerCase contient mobile).

Configuration configuration

Lors du passage de la page de bureau à son équivalent mobile :

Par exemple :

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"
  ]
};

Exemple : Création d’un composant de magasin de contexte personnalisé example-creating-a-custom-context-store-component

Dans cet exemple, vous créez un composant de magasin de contexte qui récupère les données d’un service externe et les stocke dans le magasin de sessions :

Ajout du composant geoloc add-the-geoloc-component

Créez une application CQ et ajoutez le composant geoloc.

Création de la boîte de dialogue de modification géographique create-the-geoloc-edit-dialog

Le composant de magasin de contexte nécessite une boîte de dialogue de modification. La boîte de dialogue de modification géographique contient un message statique indiquant qu’il n’y a aucune propriété à configurer.

Création du script d’initialisation create-the-initialization-script

Ajoutez un fichier init.js.jsp au composant geoloc et utilisez-le pour créer le magasin de sessions, récupérer les données d’emplacement et l’ajouter au magasin.

Le fichier init.js.jsp est exécuté lorsque ClientContext est chargé par la page. L’API JavaScript ClientContext est alors chargée et disponible pour votre script.

Rendu des données du magasin de sessions geoloc render-the-geoloc-session-store-data

Ajoutez le code au fichier JSP du composant geoloc pour effectuer le rendu des données de magasin dans ClientContext.

Ajout du composant à ClientContext add-the-component-to-client-context

Ajoutez le composant Location Store à ClientContext afin qu’il soit initialisé au chargement de la page.

Voir Informations sur l’emplacement dans ClientContext see-the-location-information-in-client-context

Ouvrez la page d’accueil des Geometrixx Outdoors en mode d’édition, puis ouvrez ClientContext pour afficher les données du composant Location Store.

Création d’un contexte client personnalisé creating-a-customized-client-context

Pour créer un second contexte client, vous devez dupliquer la branche :

/etc/clientcontext/default

Pour utiliser votre contexte client personnalisé, modifiez la propriété
path
dans le style de conception du composant ClientContext, comme inclus dans le modèle de page. Par exemple, comme emplacement standard de :

/libs/cq/personalization/components/clientcontext/design_dialog/items/path