[Alpha]{class="badge informative"}

Instâncias e solicitações

Em um navegador, cada carregamento de página inicia uma nova cópia do Web SDK que serve um único visitante. Um servidor é diferente. Um processo de longa duração lida com solicitações de muitos visitantes, geralmente ao mesmo tempo. O SDK do servidor separa o trabalho que ocorre uma vez por processo do trabalho que ocorre para cada solicitação do visitante:

Configurar uma vez quando o servidor for iniciado configure-once

Crie uma instância e a configure antes que o servidor comece a aceitar solicitações. Aguarde configure resolver, pois forRequest aciona um erro se você chamá-lo antes de concluir a configuração.

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

Se configure for rejeitado, por exemplo, porque uma opção é inválida, a instância permanece não configurada e forRequest continua sendo acionada até que uma chamada para configure seja bem-sucedida.

Chamada para solicitação para cada solicitação for-request

Para cada solicitação de entrada, chame forRequest e passe o objeto de solicitação de entrada. O identificador retornado tem os mesmos métodos que a instância, exceto configure e forRequest.

O exemplo a seguir usa o módulo node:http interno Node.js. O mesmo padrão funciona com qualquer estrutura que forneça o objeto de solicitação de entrada, como 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);

Se o tempo de execução ou a estrutura passar uma API Fetch Request para o manipulador e esperar um Response de retorno, use o mesmo padrão. Registre o manipulador da maneira que seu tempo de execução ou estrutura exige:

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 tem o suporte de sua própria instância do SDK configurada com as mesmas opções que você passou para configure. Os usuários não compartilham o estado do visitante entre si, portanto, a identidade ou o consentimento de um visitante não podem vazar para a solicitação de outro visitante.

Passar o request permite que o SDK encaminhe os cabeçalhos do visitante, como User-Agent, Accept-Language e X-Forwarded-For, para o Edge Network. Consulte Contexto e cabeçalhos encaminhados.

O que é compartilhado e o que é por solicitação scope

Identidade e consentimento em solicitações identity

O SDK armazena a Experience Cloud ID (ECID) e as preferências de consentimento do visitante em cookies, da mesma forma que o Web SDK. Em um servidor, o SDK lê e grava esses cookies por meio de um serviço de cookies, que você passa para forRequest como a propriedade cookie.

A SDK não inclui um serviço de cookie que lê e grava cabeçalhos HTTP Cookie e Set-Cookie. Para manter a identidade e o consentimento de um visitante em todas as solicitações, forneça sua própria implementação da interface do serviço de cookies. Consulte Serviços da plataforma.

Evite a instância de nível superior para o tráfego de visitantes top-level

Você pode chamar métodos como sendEvent diretamente na instância que createInstance retorna. Isso é útil para testar sua configuração ou para enviar eventos que não pertencem a um visitante específico. No entanto, a instância de nível superior mantém um único armazenamento de cookies na memória durante toda a vida do processo. Cada chamada feita nela compartilha a mesma identidade, independentemente de qual visitante a acionou. Em vez disso, use um identificador forRequest para cada solicitação do visitante.