[Alpha]{class="badge informative"}

Istanze e richieste

In un browser, ogni caricamento di pagina avvia una nuova copia del Web SDK che serve un singolo visitatore. Un server è diverso. Un processo a esecuzione prolungata gestisce le richieste di più visitatori, spesso contemporaneamente. Il Server SDK separa il lavoro che viene eseguito una volta per ogni processo dal lavoro che avviene per ogni richiesta del visitatore:

Configurare una volta all’avvio del server configure-once

Crea un’istanza e configurala prima che il server inizi ad accettare le richieste. Attendi la risoluzione di configure, perché forRequest genera un errore se lo chiami prima del termine della configurazione.

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 rifiuta, ad esempio perché un’opzione non è valida, l’istanza rimane non configurata e forRequest continua a generare finché non viene eseguita una chiamata a configure.

Richiama richiesta per ogni richiesta for-request

Per ogni richiesta in ingresso, chiamare forRequest e passare l’oggetto della richiesta in ingresso. L’handle restituito ha gli stessi metodi dell’istanza, tranne configure e forRequest.

Nell’esempio seguente viene utilizzato il modulo predefinito node:http di Node.js. Lo stesso modello funziona con qualsiasi framework che ti fornisca l’oggetto di richiesta in ingresso, ad esempio Express 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);

Se il runtime o il framework trasmette un’API di recupero Request al gestore e prevede un Response in cambio, utilizza lo stesso pattern. Registra il gestore nel modo in cui il runtime o il framework richiede:

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

Ogni handle è supportato dalla propria istanza di SDK configurata con le stesse opzioni passate a configure. Gli handle non condividono tra loro lo stato del visitatore, pertanto l’identità o il consenso di un visitatore non possono sfuggire alla richiesta di un altro visitatore.

Il passaggio di request consente al SDK di inoltrare le intestazioni del visitatore, come User-Agent, Accept-Language e X-Forwarded-For, all’Edge Network. Vedi Intestazioni contestuali e inoltrate.

Cosa è condiviso e cosa è per richiesta scope

Identità e consenso tra le richieste identity

SDK memorizza l’ECID del visitatore e le preferenze di consenso in cookie, nello stesso modo in cui lo archivia il Web SDK. Su un server, SDK legge e scrive questi cookie tramite un servizio cookie, che passi a forRequest come proprietà cookie.

SDK non include un servizio cookie che legge e scrive le intestazioni HTTP Cookie e Set-Cookie. Per mantenere l’identità e il consenso di un visitatore in tutte le richieste, fornisci la tua implementazione dell’interfaccia del servizio cookie. Consulta Servizi Platform.

Evita l’istanza di livello principale per il traffico del visitatore top-level

È possibile chiamare metodi come sendEvent direttamente sull’istanza restituita da createInstance. Questa operazione è utile per testare la configurazione o per inviare eventi che non appartengono a un visitatore specifico. Tuttavia, l’istanza di primo livello mantiene un singolo archivio di cookie in memoria per la durata del processo. Ogni chiamata effettuata condivide la stessa identità, indipendentemente da quale visitatore l’abbia attivata. Utilizza invece un handle forRequest per ogni richiesta del visitatore.