Mettre à niveau 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 d’utiliser at.js 2.x qui ne sont pas disponibles dans les versions précédentes :

Schémas système d’at.js 2.x

Les diagrammes suivants vous aident à comprendre le workflow d’at.js 2.x avec Vues et la manière dont il améliore l’intégration de la SPA. Pour une meilleure présentation des concepts utilisés dans at.js 2.x, voir Implémentation d’applications d’une seule page.

(Cliquez sur l’image pour l’agrandir sur toute la largeur.)

{modal="regular"}

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 l’agrandir sur toute la largeur.)

{modal="regular"}

Déployez at.js 2.x

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

Fonctions d’at.js obsolètes

Plusieurs fonctions ont été abandonnées 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>

at.js 2.x équivalent

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>

at.js 2.x équivalent :

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.

at.js 2.x peut-il être utilisé sur certaines pages tandis qu’at.js 1.x est utilisé 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 de l’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 de Target, vous pouvez filtrer l’onglet Réseau des outils de développement de votre navigateur par « diffusion », « 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 mbox globale n’est plus utilisée

Dans at.js 2.x, vous ne voyez plus « target-global-mbox » de manière visible dans les appels réseau. Au lieu de cela, nous avons remplacé la syntaxe « target-global-mbox » par « execute > pageLoad » dans la payload 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 global via Target > Administration > Implémentation > Modifier les paramètres at.js. 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 que le même nom de mbox globale est configuré sur la page Administration > Compositeur d’expérience visuelle, également, au cas où vous auriez encore des pages utilisant at.js 1.x, comme illustré dans les illustrations suivantes.

et

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

Dans la plupart des cas, oui. Ce paramètre indique à at.js 2.x de déclencher une requête sur les serveurs Edge de 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 de fonctionner, même si le nom de la 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.

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

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. Vous pouvez ainsi 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 sur des domaines uniques. Cette fonctionnalité est liée au comportement des cookies tiers et propriétaires d’Target.

En 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, la méthode HTTP GET n’est pas utilisée. Au lieu de cela, la requête HTTP POST est utilisée via at.js 2.x pour envoyer des payloads JSON aux serveurs Target Edge. L’utilisation de la requête HTTP POST signifie que la requête de redirection visant à 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 (antérieur à la version 2.10) n’est pas pris en charge prêt à l’emploi. Seul at.js 1.x prend en charge le suivi inter-domaines prêt à l’emploi.

Pour utiliser le suivi inter-domaines pour at.js v2.10 ou une 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 antérieures à la version 2.10, vous pouvez implémenter 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 de déclencher une requête aux serveurs Edge de 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 global via Target > Administration > Implémentation > Modifier. 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.

Elle indique que lorsque j’appelle triggerView() avec {"page" : "true"}, une notification est envoyée au serveur principal Target et l’impression est augmentée. 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.

Quels paramètres at.js 1.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 ne sont PAS 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 vst.*

Les clients utilisant at.js 1.x ont pu utiliser les paramètres de mbox vst.* pour créer des audiences. Il s’agissait d’un effet secondaire involontaire de la manière dont at.js 1.x a envoyé les 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 différemment les paramètres de mbox.

Compatibilité at.js

Les tableaux suivants décrivent at.js. compatibilité 2.x avec différents types d’activités, 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 le at-request-succeeded d’événement personnalisé pour faire apparaître les jetons de réponse. Pour des exemples de code utilisant l’événement at-request-succeeded personnalisé, voir Jetons réponse.

Paramètres at.js 1.x pour le mappage de la payload vers at.js 2.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 paramètre at.js 1.x, sa description et la payload JSON 2.x correspondante (le cas échéant) :

at_property

(paramètre at.js 1.x)

Utilisé pour les permissions utilisateur d’entreprise.

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

mboxHost

(paramètre at.js 1.x)

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

Payload JSON at.js 2.x :

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

webGLRenderer

(paramètre at.js 1.x)

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.

Payload JSON at.js 2.x :

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

mboxURL

(paramètre at.js 1.x)

URL de la page.

Payload JSON at.js 2.x :

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

mboxReferrer

(paramètre at.js 1.x)

Référent de la page.

Payload JSON at.js 2.x :

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

mbox (nom) est égal à mbox globale

(paramètre at.js 1.x)

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

Payload JSON at.js 2.x :

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

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

(paramètre at.js 1.x)

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

Payload JSON at.js 2.x :

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

mboxId

(paramètre at.js 1.x)

N’est plus utilisée.

mboxCount

(paramètre at.js 1.x)

N’est plus utilisée.

mboxRid

(paramètre at.js 1.x)

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

Payload JSON at.js 2.x :

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

mboxTime

(paramètre at.js 1.x)

N’est plus utilisée.

mboxSession

(paramètre at.js 1.x)

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

(paramètre at.js 1.x)

L’identifiant TNT est transmis id > tntId.

Payload JSON at.js 2.x :

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

mboxMCGVID

(paramètre at.js 1.x)

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

Payload JSON at.js 2.x :

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

vst.aaaa.id et vst.aaaa.authState

(paramètres at.js 1.x)

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

Payload JSON at.js 2.x :

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

mbox3rdPartyId

(paramètre at.js 1.x)

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

Payload JSON at.js 2.x :

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

mboxMCSDID

(paramètre at.js 1.x)

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

Payload JSON at.js 2.x :

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

vst.trk

(paramètre at.js 1.x)

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

Payload JSON at.js 2.x :

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

vst.trks

(paramètre at.js 1.x)

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

Payload JSON at.js 2.x :

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

mboxMCGLH

(paramètre at.js 1.x)

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

Payload JSON at.js 2.x :

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

mboxAAMB

(paramètre at.js 1.x)

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

Payload JSON at.js 2.x :

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

mboxVersion

(paramètre at.js 1.x)

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 : diagramme architectural d’at.js 2.x

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

Pour plus d’informations🔗 voir Fonctionnement d’at.js 2.x .