[Alpha]{class="badge informative"}

Instanzen und Anfragen

In einem Browser wird beim Laden jeder Seite eine neue Kopie der Web-SDK gestartet, die nur einem einzelnen Besucher dient. Ein Server ist anders. Ein langwieriger Prozess verarbeitet Anfragen vieler Besucher, häufig zur gleichen Zeit. Die Server-SDK trennt die Arbeit, die einmal pro Prozess erfolgt, von der Arbeit, die für die Anfrage jedes Besuchers erfolgt:

Einmal konfigurieren, wenn der Server gestartet wird configure-once

Erstellen Sie eine Instanz und konfigurieren Sie sie, bevor Ihr Server beginnt, Anfragen zu akzeptieren. Warten Sie, bis die configure behoben ist, da forRequest einen Fehler ausgibt, wenn Sie sie vor Abschluss der Konfiguration aufrufen.

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(",")
  }
});

Wenn configure ablehnt, z. B. weil eine Option ungültig ist, bleibt die Instanz nicht konfiguriert und forRequest wird weiterhin ausgelöst, bis ein Aufruf an configure erfolgreich ist.

Call forRequest für jede Anfrage for-request

Rufen Sie für jede eingehende Anfrage forRequest auf und übergeben Sie das Objekt für die eingehende Anfrage. Das zurückgegebene Handle verfügt über dieselben Methoden wie die Instanz, mit Ausnahme von configure und forRequest.

Im folgenden Beispiel wird das integrierte node:http Node.js verwendet. Dasselbe Muster funktioniert bei jedem Framework, das Ihnen das eingehende Anfrageobjekt bereitstellt, z. B. Express oder 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);

Wenn Ihre Laufzeit oder Ihr Framework einen Fetch-API-Request an Ihren Handler übergibt und eine Response erwartet, verwenden Sie dasselbe Muster. Registrieren Sie den Handler so, wie es für die Laufzeit oder das Framework erforderlich ist:

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");
}

Jedes Handle wird durch eine eigene SDK-Instanz gestützt, die mit denselben Optionen konfiguriert ist, die Sie an configure übergeben haben. Der Besucherstatus von -Handles wird nicht gemeinsam verwendet, sodass die Identität oder das Einverständnis eines Besuchers nicht in die Anfrage eines anderen Besuchers einfließen kann.

Durch Übergeben des request kann die SDK die Kopfzeilen der Besucher, wie User-Agent, Accept-Language und X-Forwarded-For, an die Edge Network weiterleiten. Siehe Kontext und weitergeleitete Kopfzeilen.

Was freigegeben wird und was pro Anfrage ist scope

Anfragenübergreifende Identität und Einverständnis identity

Die SDK speichert die Experience Cloud ID (ECID) und die Einverständnisvoreinstellungen des Besuchers in Cookies auf die gleiche Weise wie die Web-SDK. Auf einem Server liest und schreibt der SDK diese Cookies über einen Cookie-Dienst den Sie als cookie-Eigenschaft an forRequest übergeben.

Die SDK umfasst keinen Cookie-Service, der HTTP-Cookie und Set-Cookie-Header liest und schreibt. Um die Identität und das Einverständnis eines Besuchers über Anfragen hinweg zu bewahren, stellen Sie Ihre eigene Implementierung der Cookie-Service-Oberfläche bereit. Siehe Platform-.

Vermeiden der Instanz auf oberster Ebene für Besucher-Traffic top-level

Sie können Methoden wie sendEvent direkt auf der -Instanz aufrufen, die createInstance zurückgibt. Dies ist nützlich, um Ihre Einrichtung zu testen oder Ereignisse zu senden, die nicht zu einem bestimmten Besucher gehören. Die Instanz der obersten Ebene speichert jedoch während der gesamten Lebensdauer des Prozesses ein einzelnes In-Memory-Cookie. Jeder Aufruf an sie hat dieselbe Identität, unabhängig davon, welcher Besucher sie ausgelöst hat. Verwenden Sie stattdessen ein forRequest Handle für die Anfrage jedes Besuchers.