Applications à page unique
Si votre site web est construit comme une 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 de page en réécrivant dynamiquement une seule page web. Cela améliore les performances et donne l'impression que l'application web est plus native.
De plus, les SPAs chargent toutes les ressources du site (à l'exception des éléments tels que les images, les vidéos et le texte) dès l'arrivée sur le site. Ensuite, elles récupèrent simplement les informations pertinentes à la page lorsque l'utilisateur navigue vers cette page. Les SPAs ont généralement un temps de chargement initial plus long, mais des transitions de page quasi instantanées. Des exemples courants de SPAs que vous utilisez tous les jours incluent Gmail, Netflix, Twitter et la plateforme One 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 traditionnels à plusieurs pages. Les différentes SPAs abordent les transitions de page différemment, c'est pourquoi ce guide se concentre sur l'utilisation du Web SDK de manière plus générale. Les développeurs doivent appliquer ces principes à leur framework de choix.
Pour les SPAs, nous proposons 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 le placement et la sélection de l'offre une fois que le client atteint l'endroit où les placements sont rendus.
- Initialisez le Web SDK sur la vue où les placements 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 ressources de Rokt lorsque les clients arrivent pour la première fois sur la SPA, car cela améliorera le temps de chargement des placements. Les deux options sont décrites plus en détail ci-dessous.
Pré-initialisation de Rokt
Première utilisation du Web SDK
Le Lanceur d'intégration du Web SDK doit être initialisé lorsque le 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, le Lanceur d'intégration prépare tout ce dont il a besoin pour afficher un emplacement à l'avance. Cela garantit que lorsque le client arrive au moment sensible de la présentation de l'emplacement, le service n'a besoin de faire que le minimum nécessaire pour afficher l'emplacement.
Pour initialiser le service, vous devez charger l'intégration Rokt sur votre page et créer une instance du Lanceur d'intégration.
Chargement de l'intégration
Comme indiqué dans l'exemple d'application multipage, le lanceur d'intégration Rokt peut être chargé sur votre page en incluant la balise de script Rokt dans la balise <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 code suivant dans la logique JavaScript déjà intégré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 du lanceur d'intégration
Si vous copiez l'exemple ci-dessous, assurez-vous de remplacer roktAccountId par l'identifiant unique de votre compte. Vous pouvez obtenir votre roktAccountId auprès de votre gestionnaire de compte ou sur 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 lanceur doit être stockée afin de pouvoir être réutilisée ultérieurement dans le flux de l'application. Cela peut être fait en l'assignant à un état global, en le fournissant en tant que contexte React, en tant que service Angular ou de toute autre manière appropriée à votre framework de choix.
Une promesse est utilisée dans cet exemple pour se prémunir contre le rafraîchissement de l'application par un utilisateur sur une page où le lanceur est utilisé. Ce scénario pourrait provoquer une condition de concurrence dans laquelle l'instance du lanceur est utilisée par la page avant que l'instance ne soit réellement créée. En stockant une promesse et en la chargeant ultérieurement aux endroits où l'instance du lanceur d'intégration est censée être utilisée, nous pouvons garantir qu'elle sera prête à chaque fois.
Arrivée sur une page avec un emplacement
Lorsque le client arrive sur une page avec un emplacement, il doit se charger de manière transparente. Le service Integration Launcher doit être en cours d'exécution à ce stade et le site doit simplement déclencher la sélection de l'offre.
La sélection peut être déclenchée lorsque la page avec un emplacement se charge. Le SDK Web Rokt offre une période de grâce pour s'assurer que l'élément HTML d'ancrage pour un emplacement intégré a eu une chance d'être rendu.
Si le rendu de l'élément d'ancrage peut être retardé sur votre page, par exemple en raison de demandes 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 crochet 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 crochet 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 emplacement
Avant de quitter une page avec des emplacements Rokt, le site partenaire doit déclencher une méthode sur le service Rokt pour supprimer les emplacements de 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 prendre la forme d'un argument de retour du crochet useEffect() ou de componentWillUnmount().
async function beforeNavigatingAwayFromPage() {
selection.close();
}
Initialisation de Rokt sur une page virtuelle
L'intégration suit les mêmes étapes que l'exemple principal. Cependant, il peut être nécessaire d'ajouter dynamiquement le script Rokt à la page, ainsi que de s'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 permet à Rokt de mesurer les performances par rapport à la transition de votre page SPA. La valeur doit être un objet JavaScript Date qui indique l'horodatage de la transition de la page virtuelle.
L'avantage de fournir ces informations est de pouvoir mesurer avec précision le temps qu'il faut à un client pour commencer à afficher une page jusqu'à ce que le contenu Rokt soit rendu. Nous travaillons en permanence pour améliorer les performances du Web SDK, il est donc essentiel de pouvoir mesurer avec précision le temps de placement jusqu'à l'interaction (TTI) sur votre site afin de surveiller et d'améliorer les temps de chargement et d'optimiser l'expérience de vos clients, maximisant ainsi la valeur que Rokt peut fournir.
// Étapes d'intégration comme dans les autres exemples
const launcher = await launcherPromise;
const launcher = await createLauncher({
accountId: "roktAccountId",
pageInitTimestamp: Date,
});