[Alpha]{class="badge informative"}
实例和请求
在浏览器中，每次页面加载都会启动一个面向单个访客的Web SDK的新副本。 服务器不同。 一个长时间运行的进程通常同时处理来自许多访客的请求。 服务器SDK将每个流程发生一次的工作与每个访客请求发生的工作分开：
- 每个进程一次：创建一个实例，并在服务器启动时调用
configure。 - 每个请求一次：调用
forRequest以获取一个作用域为发出请求的访客的句柄，然后调用该句柄上的sendEvent等方法。
服务器启动时配置一次 configure-once
在服务器开始接受请求之前，创建一个实例并对其进行配置。 等待configure进行解析，因为在配置完成之前调用forRequest会引发错误。
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(",")
}
});
如果configure拒绝（例如因为某个选项无效），实例将保持未配置状态，forRequest将一直抛出，直到调用configure成功。
为每个请求调用forRequest for-request
对于每个传入请求，调用forRequest并传递传入请求对象。 返回的句柄与实例具有相同的方法，但configure和forRequest除外。
以下示例使用Node.js内置node:http模块。 相同的模式适用于任何可为您提供传入请求对象的框架，例如Express或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);
如果运行时或框架将Fetch API Request传递给处理程序并要求Response返回，请使用相同的模式。 按照运行时或框架要求的方式注册处理程序：
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");
}
每个句柄都由其自身的SDK实例支持，该实例配置的选项与传递给configure的选项相同。 句柄不会彼此共享访客状态，因此一个访客的身份或同意不会泄露给另一个访客的请求。
通过传递request，SDK可将访客的标头（如User-Agent、Accept-Language和X-Forwarded-For）转发到Edge Network。 请参阅上下文和转发的标头。
共享的内容和每个请求的内容 scope
configure设置一次。 每个句柄使用相同的配置。forRequest的cookie服务。storage服务传递给forRequest，否则每个句柄都会获得新的内存存储区。forRequest的request中读取。跨请求的身份和同意 identity
SDK将访客的Experience Cloud ID (ECID)和同意首选项存储在Cookie中，与Web SDK的方式相同。 在服务器上，SDK通过 Cookie服务 读取和写入这些Cookie，您将该服务作为cookie属性传递给forRequest。
- 如果不传递
cookie服务，则每个句柄都将以空的内存中Cookie存储开头。 Edge Network会在每个请求时分配一个新的ECID，并且访客的下一个请求中不会记住您使用setConsent设置的同意。 - 如果您在访客的每个请求中传递相同的Cookie数据，SDK会将存储的身份发送到Edge Network，以便访客保留相同的ECID。 同意偏好设置也会延续。
SDK不包括读取和写入HTTP Cookie和Set-Cookie标头的Cookie服务。 为了在不同的请求中保留访客的身份和同意，请提供您自己实施的Cookie服务界面。 查看平台服务。
sendEvent发送的事件都必须在xdm.identityMap中包含主标识。 仅使用ECID无法满足此要求。避免使用访客流量的顶级实例 top-level
您可以在createInstance返回的实例上直接调用sendEvent等方法。 这样做对于测试您的设置或发送不属于特定访客的事件很有用。 但是，顶级实例会在进程的生命周期内保留单个内存中Cookie存储。 无论由哪个访客触发，对其进行的每次调用都会共享相同的标识。 请为每个访客的请求改用forRequest句柄。