[Alpha]{class="badge informative"}

Instancias y solicitudes

En un explorador, cada carga de página inicia una nueva copia de Web SDK que sirve a un único visitante. Un servidor es diferente. Un proceso de larga duración administra las solicitudes de muchos visitantes, a menudo al mismo tiempo. Server SDK separa el trabajo que se produce una vez por proceso del trabajo que se produce con la solicitud de cada visitante:

Configure una vez cuando se inicie el servidor configure-once

Cree una instancia y configúrela antes de que el servidor empiece a aceptar solicitudes. Espere a que configure se resuelva, ya que forRequest genera un error si lo llama antes de que finalice la configuración.

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 rechaza (por ejemplo, porque una opción no es válida), la instancia permanecerá sin configurar y forRequest seguirá iniciando sesión hasta que se realice correctamente una llamada a configure.

Llamada para solicitud para cada solicitud for-request

Para cada solicitud entrante, llame a forRequest y pase el objeto de solicitud entrante. El identificador devuelto tiene los mismos métodos que la instancia, excepto configure y forRequest.

El ejemplo siguiente utiliza el módulo node:http integrado de Node.js. El mismo patrón funciona con cualquier marco de trabajo que le proporcione el objeto de solicitud entrante, como Exprés o 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 el motor en tiempo de ejecución o el marco de trabajo pasan una API de recuperación Request al controlador y esperan un Response a cambio, utilice el mismo patrón. Registre el controlador de la forma que requiera el tiempo de ejecución o el marco de trabajo:

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

Cada identificador está respaldado por su propia instancia de SDK configurada con las mismas opciones que pasó a configure. Los identificadores no comparten el estado del visitante entre sí, por lo que la identidad o el consentimiento de un visitante no puede filtrarse a la solicitud de otro visitante.

Al pasar request, SDK reenvía los encabezados del visitante, como User-Agent, Accept-Language y X-Forwarded-For, a Edge Network. Ver Contexto y encabezados reenviados.

Qué se comparte y qué es por solicitud scope

Identidad y consentimiento entre solicitudes identity

SDK almacena el Experience Cloud ID (ECID) y las preferencias de consentimiento del visitante en cookies, del mismo modo que lo hace Web SDK. En un servidor, SDK lee y escribe estas cookies a través de un servicio de cookies, que pasa a forRequest como la propiedad cookie.

SDK no incluye un servicio de cookies que lee y escribe los encabezados HTTP Cookie y Set-Cookie. Para conservar la identidad y el consentimiento de un visitante entre solicitudes, proporcione su propia implementación de la interfaz de servicio de cookies. Consulte Servicios de plataforma.

Evite la instancia de nivel superior para el tráfico de visitantes top-level

Puede llamar a métodos como sendEvent directamente en la instancia que devuelve createInstance. Esto resulta útil para probar la configuración o para enviar eventos que no pertenecen a un visitante específico. Sin embargo, la instancia de nivel superior mantiene un único almacén de cookies en memoria durante la duración del proceso. Cada llamada que se realiza en él comparte la misma identidad, independientemente de qué visitante lo haya activado. En su lugar, use un identificador forRequest para la solicitud de cada visitante.