内容个性化分析

优化节点 SDK

优化节点 SDK 在顶端执行无国籍服务器端优化行为 优化核心 SDK。用于服务器渲染、服务器 ,以及需要请求范围剖面评价或事件排放的节点服务.

如果您正在整合一个节点应用程序, 请从 开始,然后使用 将优化节点SDK整合到节点应用中 为分步流出. 此 README 保持软件包取向和常见设置选项的关闭 手动; 生成 参考文件 仍为 导出 API 签名的真伪来源 .

[大

从v1升级? 跟着 v1-v2 迁移指南 在更改软件包版本之前.

开始

使用与国家预防机制兼容的软件包管理器安装,例如:

pnpm add @contentful/optimization-node

添加 contentful 当SDK会使用你的应用软件时 contentful.js 用于管理条目的客户端 取来.

导入优化类;支持CJS和无害环境管理模块系统,无害环境管理优先:

import ContentfulOptimization from '@contentful/optimization-node'

每个模块或进程创建一次SDK,然后在每个路由中绑定同意并请求上下文:

const optimization = new ContentfulOptimization({
  spaceId: 'your-space-id',
  environment: 'master',
  locale: 'en-US',
})

function appPolicyAllowsOptimizationEvent(req: { cookies?: Record<string, string> }): boolean {
  return req.cookies?.['app-personalization-consent'] === 'granted'
}

async function renderRequest(
  req: { cookies?: Record<string, string>; headers: { 'accept-language'?: string } },
  profileId: string,
) {
  const appLocale = getAppLocale(req)
  const requestOptimization = optimization.forRequest({
    consent: {
      events: appPolicyAllowsOptimizationEvent(req),
      persistence: appPolicyAllowsOptimizationEvent(req),
    },
    locale: appLocale,
    eventContext: { locale: appLocale },
    profileId,
  })

  const { accepted, data } = await requestOptimization.page()

  return accepted ? data : undefined
}

何时使用此软件包

使用 @contentful/optimization-node 用于服务器侧渲染、服务器功能和节点服务 需要无国籍人特征评估或事件排放。 使用Web 或 反应Web SDK并列 当浏览器侧面同意、匿名ID持续、自动交互跟踪或实时更新时 属于同一应用程序的一部分.

通用配置

节点SDK是无国籍的 它不维持同意、配置或浏览器持续状态 在请求之间。 关于跨 SDK 同意指南,见 优化SDK套件中的同意管理。 。 。 .

常见 api 选项:

请求范围的经验选项包含在 experienceOptions 当创建请求绑定时 客户端 :

配置共享默认值 api.location,然后以 experienceOptions.location数字 :

const optimization = new ContentfulOptimization({
  spaceId: 'your-space-id',
  api: { location: { countryCode: 'DE', city: 'Berlin' } },
})
const requestOptimization = optimization.forRequest({
  consent: true,
  experienceOptions: { location: { countryCode: 'FR', city: 'Paris' } },
})
await requestOptimization.page()

请求值取代整个默认对象;它不会合并字段. 过 experienceOptions: { location: {} } 将配置的默认值替换为正空 位置而不是 API 地理定位。 活动 context.location 优先于匹配 请求字段。 空位置无法清除现有的配置文件位置, 并请求位置 不将位置锁定在以后的请求中。 见 位置输入和简介更新。 。 。 .

请求范围透视选项属于 insightsOptions数字 :

使用请求范围顶层 locale 打开 forRequest() 作为促进本地化的路径 体验 API 响应和默认事件上下文 . experienceOptions.locale 现为 高级低层通过,当 locale 未提供。 如果两者均提供,则请求 locale 赢了.

常见 fetchOptions 为: fetchMethod, (中文(简体) ), requestTimeout, (中文(简体) ), retries, (中文(简体) ), intervalTimeout, (中文(简体) ), onFailedAttempt,以及 onRequestTimeout。默认重试仅对 HTTP 适用 503 回应.

在路由器中选择应用程序 Contentful locale, i18n 层, 或者请求策略 。 传过去 值直接输入内容 CDA 请求,并将相同值传递给 forRequest({ locale: appLocale }) aPI响应和事件背景应使用 同样的语言。 合并引用本地化配置字段的标签, 如 location.city 财务报告和审定财务报表 location.country 然后用符合所提供内容的语言解决。 见 优化 SDK 套件中的位置处理 为完整的地方模型.

对于每个选项,回调有效载荷和输出类型,使用生成的 节点 SDK 参考。 。 。 .

核心工作流程

请求范围的活动

从收到的请求中构建事件上下文,将应用程序拥有的同意状态与 forRequest(),然后调用 page(), (中文(简体) ), identify(), (中文(简体) ), screen(), (中文(简体) ), track(),或粘着 trackView() 打开 返回的请求对象 :

import type { Request } from 'express'

app.get('/products/:slug', async (req, res) => {
  const appLocale = getAppLocale(req)
  const requestOptimization = optimization.forRequest({
    consent: {
      events: appPolicyAllowsOptimizationEvent(req),
      persistence: appPolicyAllowsOptimizationEvent(req),
    },
    locale: appLocale,
    eventContext: {
      locale: appLocale,
    },
    profileId: req.cookies.profileId,
  })
  const { accepted, data: optimizationData } = await requestOptimization.page({
    properties: { path: req.path },
  })

  if (accepted && requestOptimization.canPersistProfile && optimizationData?.profile.id) {
    persistProfileId(res, optimizationData.profile.id)
  }

  res.render('product', { optimizationData })
})

对于不使最终用户同意的默认应用政策,替换 接受同意后的特定请求同意查询:

const requestOptimization = optimization.forRequest({
  consent: { events: true, persistence: true },
  locale: appLocale,
  eventContext: { locale: appLocale },
  profile,
})

节点 SDK事件调用失败, 除了默认的事先同意的许可列表, identify 财务报告和审定财务报表 page。允许列入清单的事件与 context.gdpr.isConsentGiven: false 请求时 不给予同意。 过 allowedEventTypes: [] 需要严格的选择进入 无国籍事件方法.

在无国籍的运行时间, 非粘滞 trackView, (中文(简体) ), trackClick, (中文(简体) ), trackHover,以及 trackFlagView 需要一个完整的 Profile 通过 forRequest({ profile }) 或由经验返回 调用同一请求客户端。 使用 profileId aPI的连续性.

对于提交前需要事件有效载荷的自定义集成,使用请求客户端的 eventBuilder它会暴露 buildIdentify, (中文(简体) ), buildPageView, (中文(简体) ), buildScreenView,以及 buildTrack 带有请求事件上下文和语言默认值。 在这个例子中, appConsent, (中文(简体) ), appLocale, (中文(简体) ), appUserAgent,以及 appUserId 来源于您的申请请求和身份处理:

const requestOptimization = optimization.forRequest({
  consent: appConsent,
  locale: appLocale,
  eventContext: { userAgent: appUserAgent },
})
const identifyEvent = requestOptimization.eventBuilder.buildIdentify({ userId: appUserId })

建筑不发送事件、检查请求同意、援引拦截器或更新 请求配置或选择。 新建活动使用共享构建器 context.gdpr.isConsentGiven, (中文(简体) ), 这是 false 在节点SDK中,即使请求得到同意。 发送 identifyEvent 通过a 低级API不自动应用请求同意或SDK提交处理. 为了正常 提交, 使用请求 identify(), (中文(简体) ), page(), (中文(简体) ), screen(),或 track()单子 optimization.eventBuilder 任何要求都不受约束.

内容分辨率

当a contentful.js 客户端是可用的, 倾向于通过条目 ID 或内容类型获取 SDK 管理 还有口水 配置客户端一次, 然后调用 fetchOptimizedEntry() 在请求中的客户端上 在被接受的经验API呼叫后. forRequest() 客户端使用最新的选中优化 省去时; 单通呼叫需要明确 selectedOptimizations。 。 。 .

const optimization = new ContentfulOptimization({
  spaceId: 'space-id',
  contentful: { client: contentfulClient },
  environment: 'master',
  locale: appLocale,
})

const requestOptimization = optimization.forRequest({ consent: true, profile })
await requestOptimization.page()
const { baselineEntry, entry } = await requestOptimization.fetchOptimizedEntry({
  contentType: 'productPage',
  slug: req.params.slug,
  entryQuery: { locale: appLocale },
})

使用 fetchContentfulEntries() 或者说 prefetchManagedEntries() 当一个路由知道几个管理 输入来源。 弹出源接受 slugField 当内容模型不使用默认值时 slug 字段。 Slug 搜索执行内容类型、 字段选择器和双结果独有性限制 合并后 entryQuery;成功解析使用已获取条目的 sys.id. 分红 将规范化描述符嵌入 managedEntry 并保留该ID entryId. 同等身份证明 来源保留同干分批和100ID分块.

如果您的应用程序已经获取基线条目, 请继续使用手动解析器 :

const pageResult = await requestOptimization.page()
const resolvedEntry = optimization.resolveOptimizedEntry(
  baselineEntry,
  pageResult.accepted ? pageResult.data.selectedOptimizations : undefined,
)

在任意一条路径中使用一个 CDA 语言 。 对于本地化的应用程序,请配置您的应用程序本地化 。 A 类 请求的客户端用途 forRequest({ locale: appLocale }) 作为管理内容查询区域 当两个 contentful.defaultQuery 或每个呼叫的查询集 locale。将相同的值传递给 应用自有内容 CDA 请求和 forRequest({ locale: appLocale }) 当合并标签时 读取本地化配置字段与已提供条目语言相匹配。 不通过全本地 CDA 答复 withAllLocales 或者说 locale=*; 解析器期望直接的单地字段 数值。 见 条目个性化和变异分辨率 进入合同和 优化 SDK 套件中的位置处理 用于请求语言行为.

使用 getMergeTagValue() 富足富贵 文本合并标签和 getFlag() 自定义旗帜。 如果有的话 合并标签引用本地化配置字段, 如 location.city 或者说 location.country页:1 解析值遵循经验API返回的本地化配置数据。 节点SDK是 无国籍,所以 getFlag() 不自动放出旗帜视图跟踪.

缓存引导

应用层或SDK管理条目的内含载荷 缓存, 不是配置文件评价的 SDK 事件结果 。 使用 clearContentfulEntryCache() 当 SDK 时 实例必须删除缓存的 CDA 条目.

这个 节点 SDK 集成指南 覆盖请求的上下文、配置持续性、内容输入分辨率以及混合节点+浏览器 设置细节.

利用发展

软件包本地 Dev 牵引装置来自 packages/node/node-sdk/dev/ 读取 .env 从此 软件包目录.

1. 从 .env.example 创建或更新 packages/node/node-sdk/.env。 。 。 .

2. 优先重现标准 PUBLIC_... 变量名称显示于 .env.example。 。 。 .

3. 从 repo 根开始拉带 :

   pnpm --filter @contentful/optimization-node dev
   

相关

• 将优化节点SDK整合到节点应用中 - 说吧 逐步服务器侧集成指南
• 节点 SDK 生成引用 - 说吧 导出 API 引用
• 节点参考执行 - 服务器交付 使用请求范围 SDK 调用执行
• 节点+ 网络参考实施 - 说吧 安全部门改革和浏览器混合执行
• 优化 Web SDK - 同一应用程序时使用的浏览器 SDK 还需要客户方的同意、持久性、跟踪或实时更新