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 JavaScript de 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 ContextStore. Adobe Experience Manager (AEM) installe plusieurs composants ContextStore 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 sessions session-stores

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

Le framework 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, le développeur ou les deux. 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 CQ 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 du composant ClientContext à une page adding-client-context-to-a-page

Insérez le composant ClientContext dans la section du corps de vos pages web pour activer le contexte client. 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"/>

Avec le composant ClientContext, la page charge les bibliothèques clientes qui implémentent le contexte client.

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

Extension de ClientContext 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 du framework 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 magasins 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 être enregistré à l’aide du gestionnaire de Context Store. 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 de magasin de contexte genericstore et genericstoreproperties que vous pouvez étendre. La structure de vos données de magasin détermine le composant que vous étendez :

Configuration de l’apparence 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 nœud contient les valeurs de propriété configurées à l’aide de la boîte de dialogue de modification du composant.

Ces nœuds sont traités lorsque ClientContext est initialisé.

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 ci-dessous crée le fichier de script init.js.jsp et ajoute le code qui définit le bon type MIME. Le code qui effectue l’initialisation du magasin est mentionné après.

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 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 mettre en forme le code HTML. Le code suivant illustre la structure suggérée à utiliser pour l’affichage des données d’un 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 d’un 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 effectuer les opérations suivantes :

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 œuvre de la méthode de rendu d’un magasin de sessions implementing-the-session-store-renderer-method

Votre magasin de sessions a besoin d’une méthode de « moteur de rendu » qui est appelée chaque fois que le rendu du composant doit être effectué. 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 des magasins. Une fois ceux-ci obtenus, utilisez les méthodes de 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 listener pour réagir à une mise à jour d’un 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 listeners 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](/docs/experience-manager-65/content/implementing/developing/personlization/client-context/ccjsapi.md#addlistener-event-fct-scope).

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 avoir un impact sur le délai de disponibilité du magasin de sessions :

Utilisez les méthodes onStoreRegistered et onStoreInitialized de l’objet CQ_Analytics.ClientContextUtils pour accéder aux magasins de sessions uniquement lorsqu’ils sont disponibles. Ces méthodes vous permettent d’enregistrer les listeners 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)](/docs/experience-manager-65/content/implementing/developing/personlization/client-context/ccjsapi.md#setnonpersisted-name).

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 du poste de travail à 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 d’un composant geoloc add-the-geoloc-component

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

Création de la boîte de dialogue Modifier geoloc create-the-geoloc-edit-dialog

Le composant de magasin de contexte nécessite une boîte de dialogue Modifier. La boîte de dialogue Modifier geoloc 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 stockage de sessions, récupérer les données d’emplacement et l’ajouter au stockage.

Le fichier init.js.jsp est exécuté lorsque le contexte client est chargé par la page. À ce moment-là, l’API JavaScript du ClientContext est alors chargée et disponible pour votre script.

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

Ajoutez le code au fichier JSP du composant geoloc pour retourner les données de magasin dans ClientContext.

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

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

Voir les informations de localisation dans ClientContext see-the-location-information-in-client-context

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

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

Pour créer un second ClientContext, dupliquez la branche :

/etc/clientcontext/default

Pour utiliser votre contexte client personnalisé, modifiez la propriété
path
dans le style de conception du composant contexte client, tels qu’il est inclus dans le modèle de page. Par exemple, comme emplacement standard de :
/libs/cq/personalization/components/clientcontext/design_dialog/items/path