@ contentful/ 经验- 节点

用于获取和解决的节点Js SDK 内容丰富的经验。它是用于请求处理器、服务器发送应用程序和其他节点进程的服务器配置软件包。 它能产生 PortableRenderPlan 值; 与框架适配器一起使应用程序使用.

安装

npm install @contentful/experiences-node

会话预览

在任何事件或交接工作之前, 傳出即将到来的 URL 会话 ID :

const url = new URL(incomingRequest.url);
const request = sdk.forRequest({
  isPreview: Boolean(url.searchParams.get('preview_session_id')?.trim()),
  consent: visitorConsent,
});
await request.page(); // { accepted: false, reason: 'preview' } in Session preview

isPreview: true 修正只读 request.isPreview 为此项请求独立提供 协议的配置和套接字状态。 它默认为虚假; 主机决定 呼叫前预览意图 forRequest()。所有事件在建构或 配置查询, 报告 onEventBlocked 有理无据 preview,不能影响其他请求. 预览获取省略个性化, 不附加/ 采纳配置 。 手提包准备 返回范围/缓存 skipped: 'preview',无飞行前或回放; canPersistProfile 仍然反映了持续的同意。 经同意,文件 cookie helper 留下一个已存在的身份未被更改,因为交接没有配置文件ID. 其他预览上下文可以明确选择使用 isPreview: true原始内容 sdk.api 电话 独立免费领取者仍不在此政策之列.

创建 SDK 实例, 然后绑定每个请求

创建进程长度 ContentfulExperiences 从稳定的配置。 打电话 forRequest() 每个请求的边界。 返回的外观带有请求本地获取和解析设置 .

import { ContentfulExperiences } from '@contentful/experiences-node';

const experiences = new ContentfulExperiences({
  spaceId: process.env.CONTENTFUL_SPACE_ID!,
  environmentId: 'master',
  delivery: { accessToken: process.env.CONTENTFUL_DELIVERY_TOKEN! },
  preview: process.env.CONTENTFUL_PREVIEW_TOKEN
    ? { accessToken: process.env.CONTENTFUL_PREVIEW_TOKEN }
    : undefined,
  locale: 'en-US',
  resolveDefaults: {
    debug: false,
    metadata: { application: 'storefront' },
  },
});

// In each route or request handler:
const request = experiences.forRequest({
  locale: requestLocale,
  resolveOptions: {
    metadata: { requestId },
  },
});

const plan = await request.fetchExperience({ experienceId }, { config: experienceConfig });

SDK实例只保留了稳定的配置和可再用交付运输. 每个接取或解析的电话都会收到自己的 config因此,一个实例可以解决不同组成部分登记册的不同经验。 仅限事件的电话,例如 prepareRequestHandoff() 不需要注册。 使用 forRequest() 应请求的边界,因此,请求区划和解决选项不能在同时提出的请求中漏出。 多个节点SDK实例可以并存;在构建另一个之前不需要拆卸. 每个请求外观属于它的创建实例.

运行时间参数

每个代号获取的供给值 。 《经验》宣布接受身份证明 Experience.parameters,绑定值为 $parameters/<id>. 交付强制执行 名称、要求、倒置和价值验证.

const plan = await request.fetchExperience(
  { experienceId, parameters: { featuredPosts: { limit: 6, order: '-fields.title' } } },
  { config: experienceConfig }
);

// Change parameters, refetch the same Experience, then replace the renderer's plan.
const nextPlan = await request.fetchExperience(
  { experienceId, parameters: { featuredPosts: { limit: 12, order: 'sys.createdAt' } } },
  { config: experienceConfig }
);

值是字符串,数字,或字符串/数字叶的一等记录. 收藏单是签名的 fields.<apiName> 或者说 sys.<id> 路径,使用 - 为降序. ExperienceParameters, (中文(简体) ), ExperienceParameterValue, (中文(简体) ), ExperienceParameterRecord,以及 ExperienceParameterOrder 是公共类型. 获取发送 parameter.<id>[.<field>]; 空记录、个性化或定义 扩展选择带有无前置结构图的 POST . locale 保持分开. 直接 preview: true 获取者接受相同的选项 。 预览会话保留 服务器拥有 context.parameters 和WebSocket更新. 见 渲染/调试示例。 。 。 .

个性化

让 XDA 评估个性化, 并解决体验:

const request = experiences.forRequest({
  locale: requestLocale,
  consent: visitorConsent,
  eventContext: { page: pageProperties, userAgent },
});
const plan = await request.fetchExperience(
  {
    experienceId,
    personalization: {
      profileId,
      events: [
        request.eventBuilder.buildIdentify({
          userId,
        }),
        request.eventBuilder.buildPageView({
          properties: pageProperties,
        }),
      ],
    },
  },
  { config: experienceConfig }
);

请求外观在代理ID获取未指定时提供当前配置文件 ID 。 明确的召见 personalization.profileId 赢了 XDA回来了 plan.personalization.profileId 更新此请求的外观以备日后获取和事件使用,除非更新的配置响应已经获得所有权。 提供配置文件或事件将 XDA 调用切换到 POST 。 客户端层去除不支持的事件字段( E)context.gdpr, (中文(简体) ), context.screen 财务报告和审定财务报表 context.page.title)),包括"优化-仅同意"上下文,在发送请求之前;原始已建事件不变. 要在同一调用中请求一个源地图,请添加 extensions: { sourceMap: {} }. XDA取取自与不承诺的接取准备分开.

计划也可能暴露可选 deliveryDiagnostics,其公众 ExperienceDeliveryDiagnostic 记录只包含字符串 fieldPath 财务报告和审定财务报表 message 从确认的上游实地分辨率出错。 原始分辨率和 正在获取同一核心常态。 有用的内容, 概况 收养、例外和现有的当地 diagnostics: Error[] 保留 不变。 缺席并不能证明个性化的成功或没有出错的交付. 字符串可能包含私人信息;显示通用警告/计数和 明确检查细节,使其远离日志和公用拖带/手 载荷。 见 分娩诊断指导。 。 。 .

以请求方式构建事件

request.eventBuilder 曝光情况 buildIdentify, (中文(简体) ), buildPageView,以及 buildTrack, (中文(简体) ), 使用已有的 SDK 构建器,并在事件前应用此请求的上下文 建筑业。 明确的活动输入优先于请求上下文; forRequest({ locale }) 覆盖 eventContext.locale,然后是 SDK 构建器的现有默认值. 合并为浅:一个提供页面取代整个请求页面. 明确 undefined 替换请求字段,并使用构建者的正常倒计时, 匹配直接事件方法。 页面活动 properties 仍然是单独的投入; 通过 properties: pageProperties 当它描述请求页时.

公众 ExperiencesNodeEventBuilder 类型只显示这些建筑 方法。 。 。 大楼不提交事件、申请同意、援引事件 截取器,或更新剖面. 这些行动在提交后进行。 共享 experiences.eventBuilder 仍可供无限制建造。 提交 已经建成 personalization.events 不将请求上下文合并到它们中. 使用请求构建器而不是在共享截取器中保留访问者数据 关闭。 见 已承诺的服务器渲染食谱 用于第一页,相继的相向流.

当前 XDA 行为限制此整合: 仅配置请求可以返回 基线内容,尽管受众是成员; 初步确定请求,不 配置文件可以返回个性化超时;和 未修改的事件构建器 拒绝同意。 节点参考文件以下列方式确定其简介: 直接页面事件,包括与每个个性化获取的标识,并依赖 客户端生成-schema序列化. 见参考文献 工作搬运标准 在上游修复后拆除这些住所.

目前的XDA客户端对于POST没有不参加飞行前选项. prepareRequestHandoff() 通过单独的个性化预览事件 API; 它不会在稍后的 XDA 中获取这些未承诺的更改 。 一个 通过两个操作独立发送相同事件的应用程序 可能会重复。 SDK不压制或贬低这些电话.

请求范围的活动

事件方法在请求外观上直播,从未在过程长的SDK实例上直播. 供应 当前配置和请求生成的事件值在创建外观时;事件调用更新 外表的剖面 不影响同时提出的请求.

const experienceRequest = experiences.forRequest({
  locale: requestLocale,
  profile: currentProfile,
  eventContext: { page: pageProperties, userAgent },
  consent: { events: hasAnalyticsConsent },
});

const identified = await experienceRequest.identify({ userId });
const evaluatedProfile = identified.accepted ? identified.data?.profile : undefined;
// Persist experienceRequest.profile if your application stores profiles between requests.

await experienceRequest.track({ event: 'checkout_started' });
await experienceRequest.trackClick({
  entityId: 'checkout-button',
  entityKind: 'Experience',
});

identify, (中文(简体) ), page,以及 track 直接发送并返回 { accepted: true, data } ; 拒绝运输错误。 它们的结果类型也允许为未来的排队发送者提供没有响应数据的被接受的工作. 这些呼叫更新了个人化API响应中的请求配置. trackView, (中文(简体) ), trackClick, (中文(简体) ), trackHover,以及 trackFlagView 发送分析事件并返回 EventEmissionResult数字 : { accepted: true } 被录取和 { accepted: false } 同意时 挡住他们 接受不报告运输成功。 接到被封锁的电话 onEventBlocked四者都需要当前概况, 因为无国籍者的请求必须满足一项要求;否则,他们提出 EventProfileRequiredError。事件区域优先 运行时间默认值, eventContext.locale, (中文(简体) ), forRequest({ locale }),然后一种方法的清晰 locale。 。 。 . 个性化请求本地化用途 forRequest({ locale }) 将构造器定位为 倒计时。 事件明确的地块只改变其正文;不改变内容评价 或个性化请求语言. consent.events 发送和设置大门 context.gdpr.isConsentGiven。直到它成为 true,仅限 allowedEventTypes (默认) identify 财务报告和审定财务报表 page)是发送的;一个被屏蔽的个人化呼叫 决定 { accepted: false }. 被封锁的解析器呼叫 解决同样的结果。 被封锁的事件 投出,不再重播,然后报告到运行时间 onEventBlocked配置 allowedEventTypes 财务报告和审定财务报表 onEventBlocked 运行时间allowedEventTypes: [] 严格选入; 同意本身是每个请求。 布尔 consent 将事件和持续同意放在一起. 同意的范围局限于请求的外表,从未在请求中共享或坚持. 检查 request.canPersistProfile 在存储配置文件 ID 之前。 一个载着 身份定义 ctfl-opt-aid 饼干读到 forRequest({ profile }) 和用途 canPersistProfile 写或过期的响应 cookie; 饼干的出现永远不会 服务器端同意 。 见 节点示例。所传递的事件 fetchExperience({ personalization: { events } }) 被同一请求过滤 发出请求前的同意 profileId 还在旅行. eventConsent 已贬值 别名用于 consent.events个性化方法的解决 { accepted, data? }。 。 。 .

prepareRequestHandoff() 过滤其可选 initialEvents 在建立批次前,一个接一个, 报告未获准的每个 onEventBlocked,所以一个被屏蔽 track 不停止一个 允许 page 从预览到重放。 批次总是以一页结束, 所以当 页面本身没有被允许 。 浏览器仍然 承认一批已经全部准备或根本没有准备的.

没有请求事件队列: 等待 identify, (中文(简体) ), page,或 track 在此之前 启动另一个 production 或 Analytics 调用相同的请求外观 .

事件拦截器

experiences.interceptors.event 一个SDK公司拥有的 InterceptorManager<OptimizationEventStreamEvent>,与其请求相通. 每个外观都保持自己的外观,同意,以及事件背景. 节点没有状态 拦截器登记册。 登记册转换为 add() 并保留返回的 编号为 remove()· ; clear() 删除所有处理器 count() 报告 编号。 处理器按插入顺序运行, 可能是同步的, 并接收克隆 投入。 运行的链条会快照它的处理器, 因此注册更改会影响以后 来文.

const interceptorId = experiences.interceptors.event.add((event) => {
  // Each handler receives its own deep clone; caller-owned events stay unchanged.
  event.context.userAgent = 'redacted';
  return event;
});
// At the owning application's cleanup boundary:
experiences.interceptors.event.remove(interceptorId);

连锁店每一次 直接个人化或分析活动, 用于每个明确的 XDA 事件提交,或用于准备每个回放事件. XDA 事件链同时运行 Promise.all,保留输入数组 顺序;每个链条内的处理器仍按顺序排列。 筹备进程活动 相接相续. 在另一个获取中重用一个已建标识是另一个提交. 检索和浏览器准备重放,以保存被评价的机构、ID和 时间戳而不重运行事件钩。 以下仅限国有制片人引用 没有事件钩。 Hooks 转换事件; 直接方法保持其个性化 或分析传输,而不累积等待 XDA 获取的事件.

原始同意门在钩子前运行. SDK 然后验证转换 对照目的计划输出,并对照 在发布或发送前的当前同意。 无效的输出是计划失败, 不是拒绝同意 报告一项经同意被阻止的有效转变事件 结束 onEventBlocked 及其被改变的方法/类型和被屏蔽的现有 返回合同。 在XDA电话中,这些被封锁的事件被删除,同时保留 命令和配置文件/内容获取;在传输前拒绝钩或计划错误. 客户端仍负责XDA序列化并去除不支持的字段. 此最终类型检查关闭了优化引用中的原类型唯一同意绕行 70dfa7f。 。 。 .

节点根导出 InterceptorManager, (中文(简体) ), Interceptor, (中文(简体) ), InterceptorMerge, (中文(简体) ), MaybePromise,以及 OptimizationEventStreamEvent,使用与Web相同的名称; 运行时间拥有它们的共享执行和类型. 无国籍的自由获取函数 没有全球拦截器登记册.

制作仅限状态浏览器的交接

完成所有相继的 profile 生成操作后, 包装最终 request.profile 具有公共节点自由功能:

import { createRequestHandoffFromData } from '@contentful/experiences-node';

const handoff = createRequestHandoffFromData({
  spaceId,
  environmentId,
  data: { profile: request.profile },
  // cache: { scope: 'private-request' }, // default; optional private key allowed
});

投入需要明确 spaceId 财务报告和审定财务报表 environmentId选项 data: { profile?: EventProfile },以及可选的私人请求缓存值. 只使用ID的配置文件是有效的 。 它返回一个有效的 ExperiencesHandoff 与 state.profile 提供时没有顶层 profileId 或重弹. 缺少数据 或者说 profile: undefined 省略 state 完全,包括在JSON系列化之后; 将它水化保存了已有的浏览器配置 。 明确的非私人缓存 瞄准镜抛出 TypeError; Runtime 范围/ profile 校验错误被传播.

此函数包只包含数据: 它释放出没有事件, 没有引用事件钩子, 没有网络请求, 没有突变请求状态, 没有设置 cookie 或 头. 使用 hydrateHandoffState() 在不发生浏览器页面事件的情况下将其消耗. 单独的同名运行时助手需要 { handoff, data? } 并且能够 保存重放; 内部API保持不变。 见 完成启动 顺序 用于序列化和跟踪激活.

准备浏览器交接

打电话 prepareRequestHandoff 在请求的外表 建造命令 identify 编号 : track 前缀和最后一个 page预览整个批次 与 preflight: true 一次,不发生来自节点的事件:

const { handoff, data } = await experienceRequest.prepareRequestHandoff({
  routeKey: '/products?category=chairs',
  initialEvents: [{ type: 'track', event: 'experience_rendered' }],
  page: { properties: { title: 'Chairs' } },
});

路由键是可见路径名加搜索,必须从 /。 。 。 . 准备的批次的运输地块使用请求地块,回到 建筑工区。 交接会抓住这个选择,包括缺席 语言,用于浏览器重放. 明确事件 page.locale 保留 在事件主体中,不覆盖准备或重放运输区域. SDK交接限制为100项总事件,包括最后一页, 最多50个识别事件,只在该页之前识别/跟踪事件. 在飞行前拒绝无效或过量批次; SDK 不拆分或截断。 有效的交接仍然可能被 当整个批量不符合其剩余队列容量时浏览器. 无效的输入、 勾钩失败或无效的转换输出返回私密 在不重放或预览数据的情况下移交并记录诊断。 商定 选项前缀事件被省略; 最终事件必须保持有效, 被承认 页面或准备使用同一事件无倒计时。 预览传输失败 保留已经评估过的重放, 使用相同的 事件标识和省略 data,所以打电话者可以使倒计时。 一个成功的 预览仅更新请求本地评价配置文件状态;其数据及 继续识别并不意味着这些事件已经发生。 交还是 浏览器可见的敏感数据:在私密的, 无储存反应,不要登录或持续.

普通类 identify, (中文(简体) ), page, (中文(简体) ), track,而分析电话仍然是直接服务器 不加入准备的批次。 Web SDK 接受这个交接 结束 hydrateAndTrackCurrentPage(handoff, { routeKey }) 在已有浏览器上 举个例子 其收治结果不等个人化HTTP交付.

优先发言

对于在一个以上范围内发生的设置,后期范围胜出:

false 仍然有意义 debug:SDK使用无产阶级倒置而非真实. 解决者 config 每次取回或解析调用时都要求,而且从不 在SDK或请求外观上保留.

交货、预览和目的地

fetchExperience({ experienceId }, { config: experienceConfig }) 默认使用交付客户端。 过 preview: true 以使用 SDK 实例上配置的预览客户端 :

const draft = await request.fetchExperience(
  {
    experienceId,
    preview: true,
  },
  { config: experienceConfig }
);

预览只用于代理体验获取 。 如果SDK案没有 preview 客户端, preview: true 丢出一个错误。 目的地终点仍然是只交付:

const result = await request.fetchByDestinationPath(
  {
    destinationId,
    path: requestPath,
  },
  { config: experienceConfig }
);

if ('redirect' in result) {
  // Route using result.redirect.path.
} else {
  // result is a PortableRenderPlan.
}

目标节点和路径请求接受 personalization (一个 profile id and caller- built events) 就像 by- ID 获取 。 同意和事件截取器适用于事件,请求的剖面标识被发送,除非 personalization.profileId 设置,并保存 profile id XDA 返回以备日后调用。 重定向结果不包含配置 。 SDK 不在目标请求上发送一个地块或环境标识符 。 它们仍然使用请求范围解析设置,例如元数据和调试.

运行时间拥有它的"交付与预览"客户端. 配置每个 accessToken,或通过提供明示来配置一个无符号可信任的代理 host;运行时间禁用生成了后者的无记名认证 . 对于装有标志的运输,无记名标志发送到配置的 终点. environmentId 是用于 by-ID 请求; 这不是生成的发送客户端的可选 environment 端点设置 。 明确 host 胜过生成的客户端 environment, (中文(简体) ), 它胜过交付或预览默认值。 直接 CPA 预览获取为 不同于预览会话的活版更新,这些更新是属于 @contentful/experiences-live-preview。 。 。 .

运行时间拥有其优化API客户端. 配置信任的自定义 personalizationBaseUrl 或者说 analyticsBaseUrl 结束点通过 构造器 optimization 选项;这些端点收到完整的事件 和配置有效载荷,因此仅在明确本地之外使用可信任的HTTPS源头 发展.

错误

NotFoundError 以缺失的经验再出口。 其他发送和解析错误向呼叫者传播,允许您框架应用其正常的错误处理.

import { NotFoundError } from '@contentful/experiences-node';

try {
  return await request.fetchExperience({ experienceId }, { config: experienceConfig });
} catch (error) {
  if (error instanceof NotFoundError) {
    // Use the framework's not-found response.
  }
  throw error;
}

请求隔离

请求范围提交选项

forRequest() 还接受 experienceOptions 财务报告和审定财务报表 insightsOptions,与每个呼吁分享 永远不要跨越请求 当表面被创建时,它们会被复制.

• experienceOptions: { ip, plainText, locale } 与每个个性化电话和 请求处理预览,该预览仍然添加 preflight: true递给访客 ip 从a 信任的源如您的代理, 因为 API 否则会分析服务器的 IP .
• experienceOptions.locale 是一个个性化运输选项,如优化:它设置了 locale 经验 API 用于翻译配置位置字段, 并重播 语言。 它不会改变内容语言. request.locale 和内容获取使用 forRequest({ locale }) 或仅建构方位。 等两个都安排好了, forRequest({ locale }) 亦以交通地块取胜.
• insightsOptions: { beacon } 与每个分析电话一起发送.

在创建请求之外不要存储请求外观 。 每个 forRequest() 调用返回带有其本地地址的单独对象并解析选项;同时提出的请求不共享这些值.

forRequest() 是唯一触发事件表面。 长寿级保留了稳定的运输能力 配置和无上下文基础 EventBuilder; 它不保留请求配置文件、 地方、 区域、 区域、 区域, 页面、用户代理、同意或其他请求敏感事件状态.

建筑边界

这个套件是一个公共节点专用叶子 覆盖内部 @contentful/experiences-runtime, (中文(简体) ), @contentful/experiences-client,以及 @contentful/experiences-sdk-core 软件包。 运行时间只保留了稳定的配置、可再利用的交付和优化运输以及一个基地 EventBuilder 配置有明确的平台频道 。 客户端提供生成的"交付"边界和免费取取取功能. 节点SDK将事件行为和多变的剖面状态与每个请求相接. @contentful/experiences-web 是它在同一下层的公共兄弟姐妹,而不是这个节点SDK的子类:它拥有浏览器状态,同时继承了共享运行时的可信任的传输,并引导了by-ID预览能力.

许可证

麻省理工学院. 见寄存器 LICENSE 财务报告和审定财务报表 NOTICE 完全归属.