[Alpha]{class="badge informative"}

Instances et requêtes

Dans un navigateur , chaque chargement de page lance une nouvelle copie du SDK Web destinée à un seul visiteur. Un serveur est différent. Un processus de longue durée gère les requêtes de nombreux visiteurs et visiteuses, souvent en même temps. Le SDK du serveur sépare le travail qui se produit une fois par processus du travail qui se produit pour la requête de chaque visiteur :

Configurer une seule fois au démarrage du serveur configure-once

Créez une instance et configurez-la avant que votre serveur ne commence à accepter les requêtes. Attendez la résolution de l’configure, car forRequest renvoie une erreur si vous l’appelez avant la fin de la configuration.

import { createInstance } from "@adobe/alloy-node";

const alloy = createInstance();

await alloy.configure({
  datastreamId: "ebebf826-a01f-4458-8cec-ef61de241c93",
  orgId: "ADB3LETTERSANDNUMBERS@AdobeOrg",
  edgeCredentials: {
    clientId: process.env.ADOBE_CLIENT_ID,
    clientSecret: process.env.ADOBE_CLIENT_SECRET,
    scopes: process.env.ADOBE_SCOPES.split(",")
  }
});

Si configure la rejette, par exemple parce qu’une option n’est pas valide, l’instance reste non configurée et forRequest continue de se déclencher jusqu’à ce qu’un appel à configure réussisse.

Appel de requête pour chaque requête for-request

Pour chaque requête entrante, appelez forRequest et transmettez l’objet de requête entrante. Le handle renvoyé a les mêmes méthodes que l’instance, à l’exception de configure et forRequest.

L’exemple suivant utilise le module de node:http intégré Node.js. Le même modèle fonctionne avec tout framework qui vous donne l’objet de requête entrant, comme Express ou Fastify.

import { createServer } from "node:http";

createServer(async (req, res) => {
  const visitor = alloy.forRequest({ request: req });

  try {
    await visitor.sendEvent({
      xdm: {
        eventType: "web.webpagedetails.pageViews",
        identityMap: {
          Email: [{ id: "visitor@example.com", primary: true }]
        }
      }
    });
  } catch (error) {
    console.error("Failed to send event to Adobe", error);
  }

  res.end("OK");
}).listen(3000);

Si votre runtime ou framework transmet une Request d’API de récupération à votre gestionnaire et s’attend à une Response en retour, utilisez le même modèle. Enregistrez le gestionnaire de la manière dont votre runtime ou votre framework le requiert :

async function handleRequest(request) {
  const visitor = alloy.forRequest({ request });

  try {
    await visitor.sendEvent({
      xdm: {
        eventType: "web.webpagedetails.pageViews",
        identityMap: {
          Email: [{ id: "visitor@example.com", primary: true }]
        }
      }
    });
  } catch (error) {
    console.error("Failed to send event to Adobe", error);
  }

  return new Response("OK");
}

Chaque handle est soutenu par sa propre instance SDK configurée avec les mêmes options que celles que vous avez transmises à configure. Les gestionnaires ne partagent pas l’état du visiteur les uns avec les autres, de sorte que l’identité ou le consentement d’un visiteur ne peut pas être divulgué dans la requête d’un autre visiteur.

La transmission du request permet au SDK de transférer les en-têtes du visiteur, tels que User-Agent, Accept-Language et X-Forwarded-For, vers Edge Network. Voir En-têtes contextuels et transférés.

Ce qui est partagé et ce qui est par demande scope

Identité et consentement entre les requêtes identity

Le SDK stocke l’Experience Cloud ID (ECID) et les préférences de consentement du visiteur ou de la visiteuse dans des cookies, de la même manière que le fait Web SDK. Sur un serveur, le SDK lit et écrit ces cookies par le biais d’un service de cookies, que vous transmettez à forRequest en tant que propriété cookie.

Le SDK n’inclut pas de service de cookie qui lit et écrit des en-têtes HTTP Cookie et Set-Cookie. Pour conserver l’identité et le consentement d’un visiteur ou d’une visiteuse dans plusieurs requêtes, fournissez votre propre mise en œuvre de l’interface du service de cookies. Voir Services Platform.

Évitez l’instance de niveau supérieur pour le trafic des visiteurs top-level

Vous pouvez appeler des méthodes telles que sendEvent directement sur l’instance que createInstance renvoie. Cela s’avère utile pour tester votre configuration ou pour envoyer des événements qui n’appartiennent pas à un visiteur spécifique. Cependant, l’instance de niveau supérieur conserve un seul magasin de cookies en mémoire pendant toute la durée de vie du processus. Chaque appel effectué sur celui-ci partage la même identité, quel que soit le visiteur qui l’a déclenché. Utilisez plutôt un handle forRequest pour la requête de chaque visiteur.