Mise à niveau d’at.js 1.x vers at.js 2.x

La dernière version d’at.js Adobe Target propose des ensembles de fonctionnalités riches qui permettent à votre entreprise d’exécuter la personnalisation sur les technologies de nouvelle génération côté client. Cette nouvelle version vise à mettre à niveau at.js afin d’établir des interactions harmonieuses avec les applications monopages (SPA).

Voici quelques avantages de l’utilisation d’at.js 2.x qui ne sont pas disponibles dans les versions précédentes :

at.js 2.Diagrammes système x

Les diagrammes suivants vous aident à comprendre le processus d’at.js 2.x avec vues et comment cela améliore l’intégration SPA. Pour une meilleure présentation des concepts utilisés dans at.js 2.x, voir Implémentation d’application monopage.

(Cliquez sur l’image pour agrandir l’image en largeur réelle.)

Désormais, où que soit implémenté triggerView() sur votre application d’une seule page, les vues et actions sont récupérées depuis le cache et présentées à l’utilisateur sans appel au serveur. triggerView() envoie également une demande de notification au serveur principal Target afin d’incrémenter et d’enregistrer le nombre d’impressions.

(Cliquez sur l’image pour agrandir l’image en largeur réelle.)

Déployer at.js 2.x

Déployer at.js 2.x via des balises dans l’extension Adobe Experience Platform.

Fonctions d’at.js obsolètes

Il existe plusieurs fonctions obsolètes dans at.js 2.x.

Les fonctions obsolètes et leurs contreparties sont présentées ci-après. Pour obtenir la liste complète des fonctions, voir Fonctions at.js.

mboxCreate(mbox,params)

Description  :

Exécute une requête et applique l’offre au DIV le plus proche avec le nom de classe mboxDefault.

Exemple  :

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

Équivalent at.js 2.x

Une alternative à mboxCreate(mbox, params) est getOffer() et applyOffer().

Exemple  :

<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() et mboxUpdate()

Description  :

Crée un mappage interne entre un élément et le nom d’une mbox, mais n’exécute pas la demande. Utilisé conjointement avec mboxUpdate(), qui exécute la requête et applique l’offre à l’élément identifié par le nodeld dans mboxDefine(). Cette fonction peut être également utilisée pour mettre à jour une mbox initiée par mboxCreate.

Exemple  :

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

Équivalent at.js 2.x  :

Une alternative à mboxDefine() et mboxUpdate, est getOffer() et applyOffer(), avec l’option de sélecteur utilisée dans applyOffer(). Cette approche permet de mapper l’offre à un élément à l’aide d’un sélecteur CSS, et pas seulement avec un identifiant.

Exemple  :

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

Description  :

Propose une méthode standard pour enregistrer une extension spécifique.

Ce paramètre n’est plus pris en charge et ne doit pas être utilisé.

Résumé des fonctions at.js obsolètes, nouvelles et prises en charge dans 2.x

Limites et légendes

Gardez à l’esprit les limites et légendes suivantes :

Suivi des conversions

Les clients qui utilisent mboxCreate() le suivi de conversion doivent utiliser trackEvent() ou getOffer().

Présentation des offres

Clients qui ne remplacent mboxCreate() pas les getOffer() offres ou applyOffer() ne les risquent pas.

Peut-on utiliser at.js 2.x sur certaines pages pendant que at.js 1.x se trouve sur d’autres pages ?

Oui, le profil du visiteur est conservé sur plusieurs pages à l’aide de différentes versions et bibliothèques. Le format de cookie est identique.

Nouvelle utilisation des API dans at.js 2.x

at.js 2.x utilise une nouvelle API que nous appelons l’API de diffusion. Pour déboguer si at.js appelle correctement le serveur Edge Target, vous pouvez filtrer l’onglet Réseau des outils de développement de votre navigateur en "livraison", "tt.omtrdc.net" ou votre code client. Vous remarquerez également que Target envoie une charge utile JSON plutôt que des paires clé-valeur.

Target La mbox globale n’est plus utilisée

Dans at.js 2.x, vous ne voyez plus "target-global-mbox" dans les appels réseau. À la place, nous avons remplacé la syntaxe "target-global-mbox" par "execute > pageLoad" dans la charge utile JSON envoyée aux serveurs Target, comme illustré ci-dessous :

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

Essentiellement, le concept de mbox globale a été introduit pour faire savoir à Target si les offres et le contenu doivent être récupérés au chargement de la page. Cela a donc été plus explicite dans notre nouvelle version.

Le nom de la mbox globale dans at.js est-il plus volumineux ?

Les clients peuvent spécifier un nom de mbox globale via Target > Administration > Implementation > Edit at.js Settings. Ce paramètre est utilisé par les Target serveurs Edge pour convertir exécuter > pageload en nom de mbox globale, qui apparaît dans Target l’interface utilisateur. Ainsi, les clients peuvent continuer à utiliser les API côté serveur, le compositeur basé sur les formulaires, les scripts de profil et créer des audiences à l’aide du nom de mbox globale. Nous vous recommandons vivement de vous assurer également que le même nom de mbox globale est configuré sur la page Administration > Visual Experience Composer , au cas où vous auriez toujours des pages utilisant at.js 1.x, comme illustré dans les illustrations suivantes.

et

Le paramètre de la mbox globale créée automatiquement doit-il être activé pour at.js 2.x  ?

Dans la plupart des cas, oui. Ce paramètre indique à at.js 2.x pour déclencher une requête aux serveurs Edge Target au chargement de la page. La mbox globale étant traduite pour exécuter > pageload, ce paramètre doit être activé si vous souhaitez déclencher une requête au chargement de la page.

Les activités du compositeur d’expérience visuelle existantes continueront-elles à fonctionner, même si le nom de mbox globale cible n’est pas spécifié à partir d’at.js 2.x  ?

Oui, car exécuter > pageload est traité sur le Target serveur principal comme target-global-mbox.

Si mes activités basées sur des formulaires sont ciblées sur target-global-mbox, ces activités continueront-elles à fonctionner ?

Oui, car exécuter > pageload est traité sur les Target serveurs Edge comme target-global-mbox.

Pris en charge et non pris en charge par at.js 2.Paramètres x

Prise en charge du suivi inter-domaines dans at.js 2.x

Le suivi inter-domaines permet de regrouper les visiteurs dans différents domaines. Un nouveau cookie devant être créé pour chaque domaine, il est difficile de suivre les visiteurs lorsqu’ils passent d’un domaine à l’autre. Pour effectuer le suivi inter-domaines, Target utilise un cookie tiers pour suivre les visiteurs entre les domaines. Cela vous permet de créer une activité Target qui s’étend sur siteA.com et siteB.com et les visiteurs restent dans la même expérience lorsqu’ils naviguent entre des domaines uniques. Cette fonctionnalité est liée au comportement des cookies tiers et propriétaires de Target.

Dans Target, le cookie tiers est stocké dans <CLIENTCODE>.tt.omtrdc.net. Le cookie propriétaire est stocké dans clientdomain.com. Première requête de renvoi des en-têtes de réponse HTTP qui tentent de définir des cookies tiers nommés mboxSession et mboxPC tandis qu’une requête de redirection est renvoyée avec un paramètre supplémentaire (mboxXDomainCheck=true). Si le navigateur accepte les cookies tiers, la requête de redirection inclut ces cookies et l’expérience est renvoyée. Ce processus est possible car nous utilisons la méthode HTTP GET.

Toutefois, dans at.js 2.x, le GET HTTP n’est pas utilisé. À la place, le POST HTTP est utilisé via at.js 2.x pour envoyer des charges utiles JSON aux Target serveurs Edge. L’utilisation du POST HTTP signifie que la requête de redirection pour vérifier si un navigateur prend en charge les cookies tiers sera interrompue. Cela est dû au fait que les requêtes HTTP GET sont des transactions idempotentes, tandis que HTTP POST est non idempotent et ne doit pas être répété arbitrairement. Par conséquent, le suivi inter-domaines dans at.js 2.x (avant la version 2.10) n’est pas pris en charge par défaut. Seul at.js 1.x assure la prise en charge par défaut du suivi inter-domaines.

Pour utiliser le suivi inter-domaines pour at.js v2.10 ou version ultérieure, vous pouvez effectuer l’une des opérations suivantes :

Pour utiliser le suivi inter-domaines pour les versions d’at.js v2.x avant la version 2.10, vous pouvez mettre en oeuvre l’option #1 ci-dessus (installer la bibliothèque ECID).

La création automatique de la mbox globale est prise en charge

Ce paramètre indique à at.js 2.x pour déclencher une requête aux serveurs Edge Target au chargement de la page. Etant donné que la mbox globale est convertie pour exécuter > pageLoad, et que cela est interprété par les serveurs Edge Target, les clients doivent activer cette fonction s’ils souhaitent déclencher une requête au moment du chargement de la page.

Le nom de la mbox globale est pris en charge

Les clients peuvent spécifier un nom de mbox globale via Target > Administration > Implementation > Edit. Ce paramètre est utilisé par les serveurs Edge Target pour convertir exécuter > pageLoad en nom de la mbox globale saisi. Cela permet aux clients de continuer à utiliser les API côté serveur, le compositeur basé sur les formulaires, les scripts de profil et de créer les audiences qui ciblent la mbox globale.

Les événements personnalisés at.js ci-dessous sont-ils applicables à triggerView() ou n’est-ce que pour applyOffer() ou applyOffers() ?

Oui, les événements personnalisés at.js s’appliquent à triggerView() également.

Il indique lorsque j’appelle triggerView() avec &location;"page" : "true"&brace;, il enverra une notification au serveur principal Target et augmentera l’impression. Cela entraîne-t-il également l’exécution des scripts de profil ?

Lorsqu’un appel de pré-récupération est effectué au Target principal, les scripts de profil sont exécutés. Ensuite, les données de profil impactées seront chiffrées et retransmises côté client. Après l’appel de triggerView() avec {"page": "true"}, une notification est envoyée avec les données de profil chiffrées. C’est alors que l’arrière-plan Target déchiffrera les données de profil et les stockera dans les bases de données.

Devons-nous ajouter un prémasquage du code avant d’appeler triggerView() pour gérer le scintillement ?

Non, il n’est pas nécessaire d’ajouter un prémasquage du code avant d’appeler triggerView(). at.js 2.x gère la logique de prémasquage et de scintillement avant l’affichage et l’application de la vue.

Lequel at.js 1.Les paramètres x pour la création d’audiences ne sont pas pris en charge dans at.js 2.x  ?

Les paramètres at.js 1.x suivants sont NOT actuellement pris en charge pour la création d’audiences lors de l’utilisation d’at.js 2.x  :

at.js 2.x ne prend pas en charge la création d’audiences à l’aide de paramètres.* parameters

Clients sur at.js 1.x ont pu utiliser vst.* Paramètres mbox pour créer des audiences. Il s’agissait d’un effet secondaire involontaire de la façon dont at.js 1.x a envoyé des paramètres de mbox au serveur principal Target. Après la migration vers at.js 2.x, vous ne pouvez plus créer d’audiences à l’aide de ces paramètres car at.js 2.x envoie les paramètres de mbox différemment.

Compatibilité at.js

Les tableaux suivants décrivent at.js. 2.x compatible avec différents types d’activité, intégrations, fonctionnalités et fonctions at.js.

Types d’activités

Intégrations

Fonctionnalités

Paramètres de chaîne de requête

Jetons de réponse

at.js 2.x, tout comme at.js 1.x, utilise l’événement personnalisé at-request-succeeded pour les jetons de réponse de surface. Pour des exemples de code utilisant l’événement at-request-succeeded personnalisé, voir Jetons réponse.

Paramètres at.js 1.Paramètres x vers at.js 2.Mappage de la payload x

Cette section décrit les mappages entre at.js 1.x et at.js 2.x.

Avant de passer à la correspondance des paramètres, les points d’entrée que ces versions de bibliothèque utilisent ont changé :

Une autre différence majeure réside dans le fait que :

Les sections suivantes répertorient chaque at.js 1.Paramètre x, sa description et le 2 correspondant.x Charge utile JSON (le cas échéant) :

at_property

(at.js 1.x paramètre)

Utilisé pour les permissions utilisateur d’entreprise.

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

mboxHost

(at.js 1.x paramètre)

Domaine de la page sur laquelle s’exécute la bibliothèque Target.

at.js 2.x Charge utile JSON :

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

webGLRenderer

(at.js 1.x paramètre)

Fonctionnalités du rendu WEB GL du navigateur. Ce mécanisme est utilisé par notre mécanisme de détection d’appareil pour déterminer si l’appareil du visiteur est un ordinateur, un iPhone, un appareil Android, etc.

at.js 2.x Charge utile JSON :

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

mboxURL

(at.js 1.x paramètre)

URL de la page.

at.js 2.x Charge utile JSON :

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

mboxReferrer

(at.js 1.x paramètre)

Référent de la page.

at.js 2.x Charge utile JSON :

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

mbox (nom) est égal à mbox globale

(at.js 1.x paramètre)

L’API de diffusion n’a plus de concept de mbox globale. Dans la charge utile JSON, vous devez utiliser execute > pageLoad.

at.js 2.x Charge utile JSON :

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

mbox (nom) n’est pas égale à la mbox globale

(at.js 1.x paramètre)

Pour utiliser un nom de mbox, transmettez-le execute > mboxes. Une mbox requiert un index et un nom.

at.js 2.x Charge utile JSON :

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

mboxId

(at.js 1.x paramètre)

N’est plus utilisée.

mboxCount

(at.js 1.x paramètre)

N’est plus utilisée.

mboxRid

(at.js 1.x paramètre)

ID de requête utilisé par les systèmes en aval pour faciliter le débogage.

at.js 2.x Charge utile JSON :

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

mboxTime

(at.js 1.x paramètre)

N’est plus utilisée.

mboxSession

(at.js 1.x paramètre)

L’ID de session est envoyé en tant que paramètre de chaîne de requête (sessionId) au point d’entrée de l’API de diffusion.

mboxPC

(at.js 1.x paramètre)

L’identifiant TNT est transmis id > tntId.

at.js 2.x Charge utile JSON :

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

mboxMCGVID

(at.js 1.x paramètre)

L’identifiant visiteur Experience Cloud est transmis id > marketingCloudVisitorId.

at.js 2.x Charge utile JSON :

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

vst.aaaa.id et vst.aaaa.authState

(at.js 1.x paramètres)

Les identifiants de client doivent id > customerIdsêtre transmis.

at.js 2.x Charge utile JSON :

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

mbox3rdPartyId

(at.js 1.x paramètre)

ID tiers du client utilisé pour lier différents Target ID.

at.js 2.x Charge utile JSON :

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

mboxMCSDID

(at.js 1.x paramètre)

SDID, également appelé identifiant de données supplémentaires. Doit être transmis experienceCloud > analytics > supplementalDataId.

at.js 2.x Charge utile JSON :

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

vst.trk

(at.js 1.x paramètre)

Analytics serveur de suivi. Doit être transmis experienceCloud > analytics > trackingServer.

at.js 2.x Charge utile JSON :

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

vst.trks

(at.js 1.x paramètre)

Serveur de suivi Analytics sécurisé. Doit être transmis experienceCloud > analytics > trackingServerSecure.

at.js 2.x Charge utile JSON :

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

mboxMCGLH

(at.js 1.x paramètre)

Conseil d’emplacement d’Audience Manager. Doit être transmis experienceCloud > audienceManager > locationHint.

at.js 2.x Charge utile JSON :

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

mboxAAMB

(at.js 1.x paramètre)

Blob Audience Manager. Doit être transmis experienceCloud > audienceManager > blob.

at.js 2.x Charge utile JSON :

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

mboxVersion

(at.js 1.x paramètre)

La version est envoyée en tant que paramètre de chaîne de requête via le paramètre de version.

Vidéo de formation : at.js 2.Diagramme architectural x

at.js 2.x améliore la prise en charge d’Adobe Target pour SPA et s’intègre à d’autres solutions Experience Cloud. Cette vidéo explique comment tout se connecte.

Voir Comprendre comment at.js 2.x fonctionne pour plus d’informations.