Applications à page unique
Si votre site web est construit en tant qu'application à page unique (SPA), suivez ces directives pour une intégration fluide.
Qu'est-ce qu'une application à page unique ?
Une application à page unique est une application web (ou un site web) qui facilite les transitions entre les pages en réécrivant dynamiquement une seule page web. Cela améliore les performances et donne à l'application web une sensation plus native.
De plus, les SPA chargent toutes les ressources du site (en dehors des éléments tels que les images, les vidéos et le texte) dès leur arrivée sur le site. Ensuite, elles récupèrent simplement les informations pertinentes pour la page lorsque un client navigue vers cette page. Les SPA ont généralement un temps de chargement initial du site plus long, mais des transitions de page presque instantanées. Des exemples courants de SPA que vous utilisez chaque jour incluent Gmail, Netflix, Twitter et la One Platform de Rokt.
En revanche, les applications multi-pages conventionnelles déchargent chaque page entre les navigations et rechargent toutes les ressources lorsque vous arrivez sur la page suivante.
Si votre site n'est pas une application à page unique, suivez nos instructions d'intégration standard.
Options d'intégration
Si votre SPA est construit en utilisant React, vous pouvez suivre ces instructions.
Le processus d'intégration de Rokt avec une SPA diffère du processus d'intégration avec des sites web multi-pages traditionnels. Différentes SPAs abordent les transitions de page de manière différente, donc ce guide se concentre sur la manière d'utiliser le Web SDK de manière plus générale. Les développeurs devraient appliquer ces principes à leur framework de choix.
Pour les SPAs, nous offrons deux options d'intégration.
- (Recommandé) Pré-initialisez le Web SDK lorsque les clients arrivent pour la première fois sur la SPA, puis déclenchez l'affichage et la sélection des offres une fois que le client atteint l'endroit où les affichages sont rendus.
- Initialisez le Web SDK sur la vue où les affichages sont rendus. Assurez-vous d'inclure le timestamp pour la transition de page virtuelle.
- Pour cette option, nous recommandons également d'utiliser l'iframe préparatoire pour précharger les actifs de Rokt lorsque les clients arrivent pour la première fois sur la SPA, car cela améliorera le temps de chargement des affichages. Les deux options sont détaillées plus bas.
Pré-initialisation de Rokt
Premier lancement du Web SDK
Le Web SDK Integration Launcher doit être initialisé lorsque un client arrive pour la première fois sur une SPA. Le service peut être réutilisé tout au long du parcours du client sur le site.
Lors de la première initialisation, l'Integration Launcher prépare tout ce dont il a besoin pour afficher un placement à l'avance. Cela garantit que, lorsque le client arrive au moment critique de la présentation du placement, le service n'a besoin de faire que le minimum requis pour afficher le placement.
Pour initialiser le service, vous devez charger l'intégration Rokt sur votre page et créer une instance de l'Integration Launcher.
Chargement de l'intégration
Comme dans l'exemple d'application multipages, le Rokt Integration Launcher peut être chargé sur votre page en incluant la balise script Rokt dans le <head> du site web.
<head>
<script
async
crossorigin="anonymous"
id="rokt-launcher"
fetchpriority="high"
src="https://apps.rokt.com/wsdk/integrations/launcher.js"
type="module"
></script>
</head>
Alternativement, vous pouvez ajouter le snippet de code suivant dans la logique JavaScript déjà livrée à votre application.
const target = document.head || document.body;
const script = document.createElement("script");
script.type = "text/javascript";
script.src = "https://apps.rokt.com/wsdk/integrations/launcher.js";
script.fetchpriority = "high";
script.crossOrigin = "anonymous";
script.async = true;
target.appendChild(script);
Création d'une instance de l'Intégration Launcher
Si vous copiez l'exemple ci-dessous, assurez-vous que rokt-account-id est remplacé par l'identifiant unique de votre compte. Vous pouvez obtenir votre rokt-account-id auprès de votre responsable de compte ou dans One Platform.
const launcherPromise = new Promise((resolve, reject) => {
script.onload = () =>
resolve(window.Rokt.createLauncher({ accountId: "rokt-account-id" }));
script.onerror = (error) => reject(error);
});
La référence à la promesse du launcher doit être stockée afin d'être réutilisée plus tard dans le flux de l'application. Cela peut être fait en l'assignant à un état global, en le fournissant comme un contexte React, un service Angular ou de toute manière appropriée à votre framework de choix.
Une promesse est utilisée dans cet exemple pour se prémunir contre un utilisateur rafraîchissant votre application sur une page où le launcher est utilisé. Ce scénario pourrait provoquer une condition de compétition dans laquelle l'instance du launcher est utilisée par la page avant que l'instance ne soit réellement créée. En stockant une promesse et en la chargeant plus tard dans des endroits où l'instance de l'Intégration Launcher doit être utilisée, nous pouvons garantir qu'elle sera prête à chaque fois.
Arrivée sur une page avec un placement
Lorsque le client arrive sur une page avec un placement, elle doit se charger sans problème. Le service Integration Launcher doit être en cours d'exécution à ce stade et le site doit uniquement déclencher la sélection des offres.
La sélection peut être déclenchée lorsque la page avec un placement se charge. Le Rokt Web SDK fournit une période de grâce pour s'assurer que l'élément HTML d'ancrage pour un placement intégré ait eu la chance d'être rendu.
Si le rendu de l'élément d'ancrage peut être retardé sur votre page, par exemple, s'il est susceptible de réponse XHR supplémentaires qui pourraient le retarder davantage, vous voudrez peut-être attendre que l'élément d'ancrage soit rendu avant de déclencher une sélection.
La plupart des frameworks ont un hook de cycle de vie indiquant que la vue a été rendue.
Par exemple : Dans Angular, les développeurs utiliseraient ngAfterViewInit(), et dans React, les développeurs peuvent utiliser le hook useEffect() ou la méthode componentDidMount().
async function afterPageElementsHaveRendered() {
const launcher = await launcherPromise;
const selection = await launcher.selectPlacements({
attributes: {
email: "j.smith@example.com",
},
identifier: "checkout.page",
});
}
Quitter une page avec un placement
Avant de quitter une page avec des placements Rokt, le site partenaire doit déclencher une méthode sur le service Rokt pour supprimer les placements sur la page actuelle et effectuer un nettoyage.
La plupart des frameworks ont un crochet de cycle de vie indiquant qu'une page est sur le point d'être quittée. Par exemple : Dans Angular, les développeurs utiliseraient ngOnDestroy(), et dans React, cela peut être sous la forme d'un argument de retour de crochet useEffect() ou componentWillUnmount().
async function beforeNavigatingAwayFromPage() {
selection.close();
}
Initialisation de Rokt sur une page virtuelle
L'intégration suit les mêmes étapes que le exemple principal. Cependant, cela peut nécessiter que vous ajoutiez dynamiquement le script Rokt à la page, ainsi que vous assurer que les utilisateurs ne créent pas d'instances supplémentaires du Lanceur d'Intégration lorsqu'ils revisitent la page.
Ajouter pageInitTimestamp à l'initialisation sur une page virtuelle aide Rokt à mesurer la performance par rapport à la transition de page de votre SPA. La valeur doit être un objet Date JavaScript qui indique le timestamp du moment où la transition de page virtuelle s'est produite.
Le bénéfice de fournir cette information est de pouvoir mesurer avec précision le temps qu'il faut à un client pour commencer à visualiser une page, jusqu'au moment où le contenu Rokt est rendu. Nous travaillons en continu pour améliorer la performance du Web SDK, donc pouvoir mesurer avec précision le temps de placement jusqu'à l'interaction (TTI) sur votre site est crucial pour surveiller et améliorer les temps de chargement et optimiser l'expérience de vos clients, maximisant la valeur que Rokt peut fournir.
// Étapes d'intégration selon d'autres exemples
const launcher = await launcherPromise;
const launcher = await createLauncher({
accountId: "rokt-account-id",
pageInitTimestamp: Date,
});