内容个性化分析

优化 Web SDK

此 SDK 执行浏览器在顶端的优化行为 优化核心 SDK。直接用于非反应浏览器 应用程序、框架适配器和需要同意状态的客户端运行时间、匿名身份 持久、自动输入交互跟踪和浏览器边事件发送.

如果您正在整合浏览器应用程序, 请从 开始,则 使用情况 在网络应用中整合优化 Web SDK 为分步流出. 此 README 保持软件包取向和常见设置选项的关闭 手动; 生成 参考文件 仍为 导出 API 签名的真伪来源 .

[大

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

开始

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

pnpm install @contentful/optimization-web

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

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

import ContentfulOptimization from '@contentful/optimization-web'

配置和初始化优化 Web SDK 每页运行时间一次 :

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

[大

初始化 Web SDK 每页运行时间一次 。 重用 window.contentfulOptimization 或属于自己的 单吨容器装订,而不是创建额外的实例.

Vanilla JS网页的使用情况

未使用捆绑器的 HTML 页面可使用 UMD 构建 :

<script src="https://cdn.jsdelivr.net/npm/@contentful/optimization-web@latest/dist/contentful-optimization-web.umd.js"></script>
<script>
  window.contentfulOptimization = new ContentfulOptimization({
    spaceId: 'your-space-id',
    environment: 'master',
    locale: 'en-US',
  })
</script>

使用网络组件

可选的Web组件入口提供了同一包中的香草自定义元素:

import { defineContentfulOptimizationElements } from '@contentful/optimization-web/web-components'

defineContentfulOptimizationElements()

导入 @contentful/optimization-web/web-components 是无副作用的。 自定义元素是 仅在 defineContentfulOptimizationElements() 运行,主运行 @contentful/optimization-web 入境点不出口或登记它们.

使用 <ctfl-optimization-root> 在共享一个 SDK 实例的条目周围:

<ctfl-optimization-root space-id="your-space-id" environment="master" locale="en-US">
  <ctfl-optimized-entry id="hero-entry" hidden>
    <article>Baseline content rendered by your app</article>
  </ctfl-optimized-entry>
</ctfl-optimization-root>

用本地语 hidden 在原始的 HTML 中,当基线或静态内容之间 个人化解决前,不得出现打开和关闭标记。 要件保留: 演示文稿装入时由生产者自有隐藏,并在选定内容时删除, 基线内容,或已准备返回。 设置 hidden 稍后从注册 JavaScript 无法 防止浏览器在自定义元素注册之前将原始标签内容涂上. 选中的选项, 其配置的条目 ID 仍为空 .

将复杂值指定为 DOM 属性, 而不是字符串属性 :

const root = document.querySelector('ctfl-optimization-root')
const entry = document.querySelector('ctfl-optimized-entry')

root.defaults = { consent: true }
root.api = { preflight: false }
root.contentful = { client: contentfulClient }
root.trackEntryInteraction = { hovers: false }
root.prefetchManagedEntries = [{ contentType: 'page', slug: 'home' }]
root.onStatesReady = (states) => {
  const subscription = states.profile.subscribe((profile) => {
    console.log(profile?.id)
  })

  return () => {
    subscription.unsubscribe()
  }
}

entry.baselineEntry = baselineEntry
entry.addEventListener('ctfl-entry-resolved', (event) => {
  renderHero(event.detail.entry, event.detail.metadata)
})

baselineEntry 和根键 contentful 仅因内容条目和客户端 结构对象。 当 Web SDK 配置时 contentful: { client }, (中文(简体) ), ctfl-optimized-entry 也可以从 entry-id编号 :entryId 或通过 content-type 财务报告和审定财务报表 slug编辑 选项 slug-field 属性默认值为 slug,则 entryQuery 财产用品 CDA 查询值 . baselineEntry 优于任一管理来源。 设置根 prefetchManagedEntries 属性,用于在根 SDK 准备好后为配置的 SDK 缓存取暖。 对于 框架包装, 指定 baselineEntry, (中文(简体) ), entryQuery, (中文(简体) ), sdk, (中文(简体) ), defaults, (中文(简体) ), api调用 属性,然后听 ctfl-entry-loading, (中文(简体) ), ctfl-entry-resolved,以及 ctfl-entry-error 使框架拥有的UI。 习惯要素故意不提供 框架中性渲染介质 API。 没有自定义元素但可渲染的框架包装器 仍然使用 Web 演示文稿助手可以导入 OptimizedEntrySourceController 财务报告和审定财务报表 createOptimizedEntryLoadingEntry 从 @contentful/optimization-web/presentation 共享 相同的管理入源生命周期。 只有核心或非网络自定义运行时间适配器可以导入这些 直接从 @contentful/optimization-core/entry-source 不取决于 在网络SDK.

更改一个被管理的源属性可追溯到该条目并忽略 stale results. 成功的一击 使用取回的条目查找 sys.id 在解决事件和 data-ctfl-* 互动跟踪, 不是子弹 只配置一个管理到的源; 将非空条目 ID 与完整的 swit 合并 源输出 Optimized entry source cannot include both entryId and managedEntry. 获取 也没有.

每个基线条目编号,第一个选定、基线、保留或超时/倒计时 结果变为显示的内容。 超时或故障是诚实的基准结果:装载结束, 基线内容和跟踪元数据也表示同意。 随着有效的现场更新被禁用, 稍后 定义选择, undefined中,待处理状态,失败状态不会替换该内容或 恢复装入。 有效的活性更新接受后来定义的选择. 一个空的 selectedOptimizations 数组( r)[])表示不应用选择并解决基线内容 匹配基线跟踪。 此例不同于所选择的选项,其配置的条目 ID 是空的,它仍然隐藏。 不同的基线条目ID开始新的演示文稿.

对于脚本-tag使用,加载主Web SDK UMD捆绑和单独的Web组件 UMD捆绑:

<script src="https://cdn.jsdelivr.net/npm/@contentful/optimization-web@latest/dist/contentful-optimization-web.umd.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@contentful/optimization-web@latest/dist/contentful-optimization-web-components.umd.js"></script>
<script>
  ContentfulOptimizationWebComponents.defineContentfulOptimizationElements()
</script>

SSR输出可以包括惰性自定义元素标记. 在客户端,打电话 defineContentfulOptimizationElements() 并指定对象属性,然后才会期望条目 决心。 root 共享 SDK 准备状态和预览- panel 活更新状态与后人条目; 项 diff data-ctfl-* 主机属性和在断开时清理订阅。 偏好一个根 每个 SDK 实例,除非一个页面真的需要单独的 SDK 所有权 .

何时使用此软件包

使用 @contentful/optimization-web 用于需要状态化 Web 运行时间的浏览器应用程序 直接,包括同意状态,匿名身份持续,自动进入互动跟踪, 和浏览器边事件发送.

我们建议启动反应应用 @contentful/optimization-react-web,将这个SDK包起来 与回放提供者,钩子,路由器适配器,和入放原始.

通用配置

Web SDK与经验API通信,用于配置和优化选择,并与 insights API用于事件摄入.

常见 api 选项:

设定 api.location 在正常 SDK 初始化时, 当应用程序提供请求时 地点 :

const optimization = new ContentfulOptimization({
  spaceId: 'your-space-id',
  api: { location: { countryCode: 'DE', city: 'Berlin' } },
})
await optimization.page()

与 Web 组件根的配置相同 api DOM财产. 摆玡 根初始化。 位置被初始化范围,而不是被动设置. 活动 context.location 以比对请求字段为准。 一个空的 api.location: {} 提供明确的空默认值, 而不是 API 地理定位; 它没有清除现有的配置文件 位置或锁定位置跨越以后的请求。 见 位置输入和简介更新。 。 。 .

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

配置 allowedEventTypes 是一个有意的允许名单,而不是临时状态。 网络默认 允许 identify 财务报告和审定财务报表 page 同意是不确定或虚假的。 设定 allowedEventTypes: [] 严格 当任何优化活动都不得在接受同意之前发出时,选择进入.

在路由器、 i18n 层或应用程序配置中选择应用程序 Contentful locale 。 传过去 值直接到内容 CDA 请求。 使用顶级 SDK locale 当体验 API 响应和事件背景需要使用相同的语言. 见 优化 SDK 套件中的位置处理 为完整的地方模型.

使用 optimization.setLocale(nextLocale) 当应用程序本地化更改时。 方法验证 明确输入、更新 optimization.locale 财务报告和审定财务报表 optimization.states.locale,并修改 默认体验 API 语言 。 它不获取内容或刷新配置状态; 调用 page(), (中文(简体) ), identify(),或者当应用程序需要本地化数据用于新地块时,CDA再次使用.

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

核心工作流程

同意和概况活动

同意是申请政策。 SDK 存储事件同意, 屏蔽事件之前不被允许的事件 同意被接受,并故意允许配置 allowedEventTypes 在每一个同意状态. 它可以分别跟踪持久性特征-持久性同意。 用于跨 SDK 同意 指导,见 优化SDK套件中的同意管理。 。 。 .

对于不使最终用户同意的默认应用政策,种子接受同意 启动时 :

const optimization = new ContentfulOptimization({
  spaceId: 'your-space-id',
  defaults: { consent: true },
})

optimization.consent(true)

optimization.consent({ events: true, persistence: false })

const { accepted, data } = await optimization.page({
  properties: { path: window.location.pathname },
})

启动默认和布尔同意要求给予或撤销事件同意和持久 默认配置连续性 。 取消事件同意仍然允许配置 allowedEventTypes; 使用 allowedEventTypes: [] 严格选入。 对象形式同意允许事件 保存配置、选中的优化、更改和匿名的 ID 会话时发送到 给予持久性同意.

page(), (中文(简体) ), identify(), (中文(简体) ), screen(), (中文(简体) ), track()粘贴 trackView() 调用返回事件 结果. { accepted: false } 表示同意或SDK卫士封锁事件. { accepted: true, data } 表示 SDK 接受事件; 接受队列或离线事件可能 还没有数据。 需要流道分解的路由器集成可以调用 trackCurrentPage()直接手册 page() 电话仍为不中断事件.

内容分辨率

当a contentful.js 客户端是可用的, 倾向于通过条目 ID 或内容类型获取 SDK 管理 和弹片 :

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

const { baselineEntry, entry } = await optimization.fetchOptimizedEntry({
  contentType: 'page',
  slug: 'home',
  entryQuery: { locale: appLocale },
})

fetchOptimizedEntry(source) 获取基线条目并用 Web SDK 的当前解决 selectedOptimizations 当省略时. fetchContentfulEntry() 只执行管理的 CDA 抓取 . 使用 fetchContentfulEntries() 或者说 prefetchManagedEntries() 当一个页面知道几个管理 来源. slugField 默认为 slug; 成功的弹片检查和交接使用取来 条目 sys.id将规范的描述符嵌入 managedEntry 并保留 身份确认 entryId等效的ID源保留同干分批和100ID分块.

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

const { accepted, data: optimizationData } = await optimization.page({
  properties: { path: location.pathname },
})
const resolvedEntry = optimization.resolveOptimizedEntry(
  baselineEntry,
  accepted ? optimizationData?.selectedOptimizations : undefined,
)

不同内容模式的打字和缩小,见 条目优化和变量分辨率。 。 。 .

在任意一条路径中使用一个 CDA 语言 。 对于本地化的应用程序, 请配置您的应用程序本地化并传递它 电话前直接 getEntry(), (中文(简体) ), getEntries(),或者 SDK 管理的条目获取。 不要通过 全地CDA响应来自 withAllLocales 或者说 locale=*; 解析器期望直接 单局部字段值。 见 条目优化和变量分辨率 进入合同和 优化 SDK 套件中的位置处理 为更广泛的地方模式.

使用 getMergeTagValue() 富足富贵 文本合并标签和 getFlag() 自定义旗帜。 如果有的话 合并标签引用本地化配置字段, 如 location.city 或者说 location.country页:1 解析值遵循经验API返回的本地化配置数据。 网络 SDK 是 状态,所以读出一面旗帜,可以在同意或允许列表时发出去除的旗帜视图跟踪 允许它和配置状态.

条目互动跟踪

在条目元素遵循标准数据属性模式时启用了自动跟踪. 过 false 对于您应用程序不想观察到的任何交互类型:

const optimization = new ContentfulOptimization({
  spaceId: 'your-space-id',
  autoTrackEntryInteraction: { hovers: false },
})

当 DOM 结构不符合自动观察时使用手动元素覆盖 :

optimization.tracking.enableElement('views', element, {
  data: {
    entryId: resolvedEntry.entry.sys.id,
    optimizationId: resolvedEntry.selectedOptimization?.experienceId,
    optimizationContextId: resolvedEntry.optimizationContextId,
    variantIndex: resolvedEntry.selectedOptimization?.variantIndex ?? 0,
  },
})

optimizationContextId 是SDK拥有的用于后续事件浓缩和诊断的背景. 没错 不是一个 API 事件有效载荷域 .

对于检测阈值,数据属性,点击并徘徊行为,以及手动覆盖,使用 Web SDK 集成指南。 。 。 .

国家订阅

状态Web SDK 曝光可观测状态用于UI反馈和集成胶:

const unsubscribe = optimization.states.profile.subscribe((profile) => {
  console.log(profile?.id)
})

常见状态流包括 consent, (中文(简体) ), persistenceConsent, (中文(简体) ), profile, (中文(简体) ), selectedOptimizations, (中文(简体) ), blockedEventStream, (中文(简体) ), eventStream状态。 优化变化是内部的 通过旗帜和进入分辨率消耗的状态,而不是 optimization.states.changes 流线。 使用 完整的参考文献 states 表面.

运行时间笔记

• 浏览器存储持久性是最佳的。 若为 localStorage 写入失败, SDK 继续使用 记忆状态,并重复在后续写作中的持久性.
• reset() 清除内部状态和排队事件,但同意和持久性同意除外 防止未完成的工作公布陈旧状态。 当活动配置改变时使用它 .
• flush() 排出排队的 Insights API 和经验 API 事件.
• 浏览器生命周期事件使用 navigator.sendBeacon() 为了最后的春斯洞察力.
• destroy() 处理内部反应效应、释放听众和单吨所有权,用于诸如测试之类的明确拆解路径 或热重装工作流程.
• 寿命周期截取器为第一党SDK和预览-平面集成而存在. 大多数应用程序 代码并不直接需要.

相关

• 在网络应用中整合优化 Web SDK - 说吧 分步浏览器集成指南
• Web SDK 生成参考 - 说吧 导出 API 引用
• 反应 Web SDK - 反应提供者、钩子、路由器和 OptimizedEntry 构造于此 SDK 的层
• 网络香草参考实施 - 静态网络 页面使用 vanilla JS 即时设置
• Web SDK 反应适配器引用执行 - 说吧 直接在此SDK上方建立本地适配层的反相应用程序