内容个性化分析

优化反应 Web SDK

Optimation React Web SDK 提供 React 提供者,钩子,路由器适配器,以及出入口 原始人顶上 优化 Web SDK反应时使用 浏览器应用程序不能管理级别较低的Web SDK实例、状态订阅、条目 并进行人工跟踪.

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

[大

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

开始

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

pnpm install @contentful/optimization-react-web

添加 contentful 也当 OptimizationRoot 将使用您的应用程序 contentful.js 客户端用于 正在获取管理条目.

React and React DOM是应用程序拥有的同级依赖关系. SDK 已经使用 React 运行时间 由您的应用程序安装,而不是安装自己的副本.

挂载 OptimizationRoot 一旦接近您的反应应用程序根 :

import { OptimizationRoot } from '@contentful/optimization-react-web'

function App() {
  return (
    <OptimizationRoot spaceId="your-space-id" environment="master">
      <YourApp />
    </OptimizationRoot>
  )
}

对于获取内容条目的单一本地化应用程序,当 API的反应和事件需要使用同样的语言:

<OptimizationRoot spaceId="your-space-id" environment="master" locale="en-US">
  <YourApp />
</OptimizationRoot>

何时使用此软件包

使用 @contentful/optimization-react-web 用于需要基于提供者的 SDK 反应浏览器应用程序 初始化、钩子、路由器页面跟踪、优化条目渲染、自动交互 跟踪,并实时更新语义. 直接使用下级的 Web SDK 非反应集成 或自定义框架适配器.

通用配置

OptimizationRoot 直接接受大多数 Web SDK 配置道具并添加 React 专用道具 例如 liveUpdates, (中文(简体) ), onStatesReady, (中文(简体) ), handoff,以及 hydration网络 SDK autoTrackEntryInteraction 选项作为反应被曝光 trackEntryInteraction 道具 (英语).

使用 OptimizationProvider 应用程序或框架适配器需要直接提供者时直接 控制,包括提供SDK实例的集成。 用它来代替 OptimizationRoot, (中文(简体) ), 不在内 OptimizationRoot:根已经由提供方和活更新提供方组成. 嵌入提供者可以创建第二个拥有的 SDK 实例或阴影根上下文,包括 移交条目.

<OptimizationProvider sdk={optimization}>
  <YourApp />
</OptimizationProvider>

注射的SDK病例使儿童在初始成形。 何时 handoff 规定 初始渲染使用快照运行时提供商设置被注入的SDK水分. 提供者 仍然让SDK撕毁 给创造这个案例的主人.

对于服务器对浏览器状态交接,通过服务器,静态,或边缘 OptimizationHandoff 结束 handoff 打开 OptimizationRoot 或者说 OptimizationProvider。通过 hydration 关于同一部分 当路径需要覆盖交接的内容演示模式时. 保留 defaults 页:1 配置或默认状态, 如同意政策 :

<OptimizationRoot
  spaceId="your-space-id"
  defaults={{ consent: true }}
  environment="master"
  handoff={handoff}
>
  <YourApp />
</OptimizationRoot>

过 api.location 通过正常 OptimizationRoot 或拥有 OptimizationProvider 配置 :

<OptimizationRoot spaceId="your-space-id" api={{ location: { countryCode: 'DE', city: 'Berlin' } }}>
  <YourApp />
</OptimizationRoot>

对于注入的 SDK ,配置 api.location 当建造SDK。 地点是 初始化范围,不是反应道具. 活动 context.location 优先于匹配 请求字段。 一个空的 api.location: {} 提供明确的空默认, 而不是 API 地理定位; 它没有清除当前配置位置或锁定位置, 覆盖以后的请求. 见 位置输入和简介更新。 。 。 .

对于通过此软件包的每个Web SDK选项,请使用 Web SDK 读取器 生成 参考文件。 。 。 .

在路由器、 i18n 层或应用程序配置中选择应用程序 Contentful locale 。 传过去 值直接转到内容 CDA 请求,并将相同值传递给提供者 locale 道具 当经验 API 响应和事件上下文需要使用相同的语言时. 见 优化 SDK 套件中的位置处理 为完整的地方模型.

对于从提供者/基层配置创建的 SDK 实例,修改 locale 道具调用 sdk.setLocale() 初始化之后, SDK 配置的其余部分仍然保留 初始化范围。 区域更新不获取内容或刷新配置状态; 触发您的 应用正常 page(), (中文(简体) ), identify(),路由加载器,或当本地化数据需要时 CDA 获取流量 变化.

核心工作流程

同意

同意政策仍然是申请权。 对于未实现默认的应用政策 最终用户同意 OptimizationRoot数字 :

<OptimizationRoot spaceId="your-space-id" defaults={{ consent: true }}>
  <YourApp />
</OptimizationRoot>

当应用程序政策取决于用户选择时,请离开 defaults.consent 未设置和呼叫 setConsent() 从 useOptimizationActions() 在相关控制中:

import { useOptimizationActions } from '@contentful/optimization-react-web'

function ConsentButton() {
  const { setConsent } = useOptimizationActions()
  return <button onClick={() => setConsent(true)}>Accept</button>
}

布尔同意呼吁控制事件排放和持久性特征的持久性,方法是 默认。 使用 sdk.consent({ events: true, persistence: false }) 当事件被允许,但 连续性需要只保留会话。 关于跨 SDK 同意指南,见 优化SDK套件中的同意管理。 。 。 .

提供商和钩子接入

OptimizationRoot 拥有Web SDK生命周期. 提供者拥有的初始化运行于 React 之后 承诺,外出实现。 儿童在最初的即兴表演时,然后是布局效果 设置在正常浏览器渲染中第一个可见颜料之前初始化活的 SDK. 优化输入钩子还附加其控制器的收听器,采用当前选项,并连接 在布局阶段,这样加载或承诺的内容在涂料之前就解决。 与 hydration="preserve-server",在条目输入时,服务器发送的内容仍可持续可见 采用活的 SDK 状态; 使用现有的根和条目 API .

当组件需要共同优化动作时使用专用的 React SDK 动作钩:

import { useOptimizationActions } from '@contentful/optimization-react-web'

function ProductCta() {
  const { trackEvent } = useOptimizationActions()

  return <button onClick={() => trackEvent({ event: 'purchase' })}>Buy now</button>
}

使用 useOptimization() 当一个组件需要直接访问 SDK 实例本身时,并选择 useOptimizationActions() 当组件需要可销毁的动作方法时,例如: trackEvent(), (中文(简体) ), identifyUser(), (中文(简体) ), trackPageView(), (中文(简体) ), trackScreen(), (中文(简体) ), flushEvents(), (中文(简体) ), resetUser(),或 setConsent()。 。 。 .

使用诸如 useConsentState(), (中文(简体) ), useProfileState(),以及 useSelectedOptimizationsState() 当组件需要使当前SDK状态。 喜欢那些 签名的钩子 sdk.states.* 直接从组件效果.

使用 useEntryResolver() 当一个组件需要手动解析 OptimizedEntry 包装 :

useOptimization() 返回 SDK 实例本身。 将这个实例放在变量中并调用 方法从它。 不要从返回的值中解析 SDK 方法,因为这些方法依赖 在个案中 this 装订.

import { useOptimization } from '@contentful/optimization-react-web'

function ProductCta() {
  const optimization = useOptimization()

  return <button onClick={() => optimization.track({ event: 'purchase' })}>Buy now</button>
}

直接SDK表面也暴露出手动交互调用,例如: trackView(), (中文(简体) ), trackClick(), (中文(简体) ), trackHover(),以及 trackFlagView()。 。 。 .

// Avoid destructuring SDK methods; this loses the instance binding.
const { track } = useOptimization()

import { useEntryResolver } from '@contentful/optimization-react-web'

function HeroEntry({ baselineEntry }) {
  const { resolveEntryData } = useEntryResolver()
  const resolvedData = resolveEntryData(baselineEntry)

  if (resolvedData.isEmptyVariant) return null
  return <HeroCard entry={resolvedData.entry} />
}

resolveEntry() 当代码仅需要解析的条目时仍然可用。 它不会暴露 空变态,所以使用 resolveEntryData() 或者说 resolveOptimizedEntry() 用于渲染 决定.

对于手动条目,在应用层中获取包含内容的条目,并在通过前使用一个 CDA 语言 他们去 baselineEntry 表面 。 用于管理取取,使用 entryId 可选 entryQuery,或 通过一个 managedEntry 对象为 contentType, (中文(简体) ), slug选项 slugField选择 entryQuery。 。 。 . slugField 默认为 slug。不要通过来自 withAllLocales 或者说 locale=*;这些API期望直接的单地域值. 见 条目优化和变量分辨率 进入合同和 优化 SDK 套件中的位置处理 为更广泛的地方模式.

对于优化的条目内容,选择 OptimizedEntry 使上下文和通过 getMergeTagValue 进入儿童制造器:

import { OptimizedEntry } from '@contentful/optimization-react-web'

function HeroEntry({ baselineEntry }) {
  return (
    <OptimizedEntry baselineEntry={baselineEntry}>
      {(resolvedEntry, { getMergeTagValue }) => (
        <HeroCard entry={resolvedEntry} getMergeTagValue={getMergeTagValue} />
      )}
    </OptimizedEntry>
  )
}

使用 useMergeTagResolver() 用于在外解决合并标签的组件 OptimizedEntry 让道具.

如果合并标签引用本地化配置字段, 如 location.city 或者说 location.country, (中文(简体) ), 它的解析值遵循经验 API 返回的本地化配置值.

供应商管理的国家订阅

使用 onStatesReady 当应用程序代码需要作为提供者的一部分订阅 SDK 状态时 初始化。 这样可以避免与 window.contentfulOptimization,则可能不存在 然而,当应用程序代码运行或可能已经发布数据时,在后一效果之前 订户.

<OptimizationRoot
  spaceId="your-space-id"
  onStatesReady={(states) => {
    const subscriptions = [
      states.eventStream.subscribe((event) => {
        if (event) devToolsPanel.logEvent(event)
      }),
      states.blockedEventStream.subscribe((blocked) => {
        if (blocked) devToolsPanel.logBlockedEvent(blocked)
      }),
    ]

    return () => {
      subscriptions.forEach((subscription) => subscription.unsubscribe())
    }
  }}
>
  <YourApp />
</OptimizationRoot>

只收回电 sdk.states。当布局效果提供者设置初始化时,它会运行 活的状态表面。 初生儿童已经可以按即兴表演时间来制作 订阅仍然可以观察由路由器页面跟踪等儿童效应所释放出的事件. 对于 组件 - 本地 UI 状态, 在提供者下继续使用钩和反应效果.

首页决定前的工作

使用 beforeInitialPage 拥有的 OptimizationRoot 当浏览器身份或自定义体验 事件工作必须在根的初始页面决定前完成。 首页决定是 root 是发送首个浏览器页面事件或跳过它的一个选择, 因为已应用交接 拥有这条路线。 在 root 的自定义运行时间存在后, 回调会接收到接收器的安全性 identify, (中文(简体) ), screen,以及 track 方法,这样你就可以解构和调用它们 而不失去 SDK接收器 :

<OptimizationRoot
  spaceId="your-space-id"
  environment="master"
  routeKey={routeKey}
  buildPagePayload={() => ({ properties: { route: routeKey } })}
  beforeInitialPage={{
    run: async ({ identify }) => {
      await identify({ userId: visitor.id })
    },
    onError: reportBeforeInitialPageError,
  }}
>
  <YourApp />
</OptimizationRoot>

一个根 beforeInitialPage 需求 routeKey 懒惰的 buildPagePayload,它没有 接受 initialPagePayload。应用程序拥有 routeKey 作为当前路线的稳定特征 拥有 buildPagePayload 作为懒于阅读当前页面数据。 根等待着返回的工作 run 或其监督员,为一次直接的页面尝试读取最新路线和有效载荷构建器, 以未排放初始值激活已存在的页面发送器 skip 标记尝试路线, 并通常为以后的路由变化而发出。 成功应用的同路交接方式可以实现 直接页决定a skip; 否则, 直接页面尝试使用 emit。 。 。 .

此根是其子树的唯一页面拥有者 。 也不要挂载反相路由器、 TanStack 路由器, Next.js App路由器,或Next.js Pages路由器自动页面跟踪器. 奥米 beforeInitialPage 当 a 单独的路由器跟踪器拥有页面事件。 该选项只提供给自有内容根; OptimizationProvider,注入提供者,以及 OptimizationAnalyticsRoot 不接受这一点.

何时 maxWaitMs 被省略,默认为3,000毫秒。 它接受积极的有限价值. 0, (中文(简体) ), 负值, NaN, (中文(简体) ), Infinity,以及 -Infinity 同步掷出 TypeError('beforeInitialPage.maxWaitMs must be a positive finite number.') 在供应商之前, 回调、 页面或 onError 运行.

序为最上相. 返回必须在页前完成的所有承诺或可兑现的承诺; 火灾和遗忘的工作随着以后的活动而继续。 拒绝回电或监察到期 结束 onError 当供应。 虽然根仍被挂起 并且拥有相同的实时运行时间是 当前, 页面仍在尝试中 。 监视器停止等待, 但不会取消回调代码 或飞行请求。 如果根卸载或运行时间被替换,则只替换未发送的本地页面和 准备继续被压制.

在直接页面尝试开始后, 路由更改既不取消, 也不启动 竞相尝试。 根会安顿下来,并标出捕捉到的路线,然后允许 页面排放。 仅在飞行中尝试时观察到的航道没有释放;航道变化 准备就绪后正常发射 现有优化的入场期限可承诺基准内容 首先,默认 liveUpdates={false},这个倒置 仍然冻结在之后 初页前的工作后来获得成功.

仅分析的交割

使用 OptimizationAnalyticsRoot 当一条路由已经在服务器上优化了内容时, 在静态生成时, ISR, 或在边缘, 浏览器只需要水合分析, page 跟踪和输入互动跟踪。 交接必须用 hydration: 'analytics-only'· ; 内容能力交割仍属于 OptimizationRoot 或者说 OptimizationProvider。 。 。 .

import { OptimizationAnalyticsRoot } from '@contentful/optimization-react-web'

function App({ handoff, routeKey }) {
  return (
    <OptimizationAnalyticsRoot
      spaceId="your-space-id"
      environment="master"
      handoff={handoff}
      routeKey={routeKey}
    >
      <YourApp />
    </OptimizationAnalyticsRoot>
  )
}

过 initialPagePayload 或者说 buildPagePayload 当初始浏览器页面事件需要路由时 超出默认路由身份的有效载荷字段.

优化输入

OptimizedEntry 以 ID 或 一种 managedEntry 根时描述符 SDK 配置为 contentful: { client },然后使选定的变体或基线. baselineEntry 仍然支持手动路径 :

import { OptimizedEntry } from '@contentful/optimization-react-web'

function HeroEntry({ baselineEntry }) {
  return (
    <OptimizedEntry baselineEntry={baselineEntry}>
      {(resolvedEntry, { getMergeTagValue }) => (
        <HeroCard entry={resolvedEntry} getMergeTagValue={getMergeTagValue} />
      )}
    </OptimizedEntry>
  )
}

模拟不同内容类型的基线和变体条目,见 条目优化和变量分辨率。 。 。 .

何时 OptimizationRoot 使用配置的 Web SDK contentful: { client },反应条目 表面可以按内容类型取取和通过 managedEntry。 。 。 . slugField 当 字段名称 slug数字 :

function HeroEntry() {
  return (
    <OptimizedEntry
      managedEntry={{
        contentType: 'page',
        slug: 'home',
        entryQuery: { locale: 'en-US' },
      }}
      loadingFallback={() => <HeroSkeleton />}
      errorFallback={() => <HeroFallback />}
    >
      {(resolvedEntry) => <HeroCard entry={resolvedEntry} />}
    </OptimizedEntry>
  )
}

使用 prefetchManagedEntries 打开 OptimizationRoot 或者说 OptimizationProvider 暖和客户端 运行 SDK 后管理入库 。 用于安全部门改革的交割,放入 ManagedEntryHandoff[] 数值 内 handoff.entries· ; prefetchManagedEntries(runtime, descriptors) 返回时的形状 服务器上有运行时间 。 将规范的描述符嵌入其中 managedEntry 并保留取入的条目 sys.id 内 entryId,因此匹配浏览器弹片 源水合物不另取取.

Hooks使用相同的管理条目源:

import { useOptimizedEntry } from '@contentful/optimization-react-web'

function HeroEntry() {
  const { entry, error, isLoading } = useOptimizedEntry({
    managedEntry: {
      contentType: 'page',
      slug: 'home',
      entryQuery: { locale: 'en-US' },
    },
  })

  if (isLoading) return <HeroSkeleton />
  if (error || !entry) return <HeroFallback />
  return <HeroCard entry={entry} />
}

baselineEntry 继续支持并选择手动路径。 使用 onEntryError 应用程序时 代码需要日志或报告管理的 CDA 失败。 使用 errorFallback 打开 OptimizedEntry 将提交 对管理的 CDA 失败的倒置 UI 。 使用 onEntryResolved或钩子的 metadata 财务报告和审定财务报表 isResolved 字段,当应用程序代码需要基线 ID,解析的条目 ID, 或优化跟踪属性后的背景。 成功的弹片检查报告以及 跟踪已获取的条目 sys.id而不是子弹.

使用 loadingFallback直接的孩子,包装道具, 和巢状的成分模式 必要时. 对于优化的条目,在优化未解决的情况下,立即开始加载相. 如果 状态在 5 秒后仍未解决, 组件会显示基线内容, 从而加载 而不是永远坚持下去。 没有习惯 loadingFallback,包装器通过隐藏 基线直到暂停。 该基准是其基准条目的第一项内容 ID,因此后期待定或失败状态无法恢复加载. 反应网络指南覆盖这些 上下文中的变体.

条目互动跟踪

OptimizedEntry 发布Web SDK的 data-ctfl-* 跟踪已解决条目的属性。 这个 root 配置观察到视图、单击和默认徘徊;通过 false 用于任何交互类型 您的申请不想遵守:

<OptimizationRoot spaceId="your-space-id" trackEntryInteraction={{ hovers: false }}>
  <YourApp />
</OptimizationRoot>

使用 OptimizedEntry 配置 Web SDK 条目跟踪属性的道具, 不设置 data-ctfl-* 手动操作元数据 :

<OptimizedEntry baselineEntry={entry} clickable trackHovers={false}>
  {(resolvedEntry) => <HeroCard entry={resolvedEntry} />}
</OptimizedEntry>

OptimizedEntry 生成条目ID、基线ID、优化ID、优化上下文ID、粘贴 状态、变量索引和来自已解决的条目状态的重复范围。 查看和徘徊时间使用 web SDK的固定阈值和间隔.

使用 sdk.tracking.enableElement(...) 从 useOptimization() 用于手动元素覆盖.

路由器页面事件

路由器适配器发射 page() 支持客户端路由器的事件 :

这个 next-pages 追踪器仍然可用于低等Pages路由器接线。 完整 Next.js 页面 路由器 SSR 设置 getServerSideProps要求交接 和匿名身份饼干写, 更喜欢 @contentful/optimization-nextjs/pages-router 适配器 路径.

所有适配器都支持静态和动态的页载荷浓缩. 见 反应网络集成指南 用于路由器特定示例.

实时更新和预览

liveUpdates 默认为 false,因此优化了条目,保留了它们的第一个内容 基线条目编号。 设定 liveUpdates 全球或 OptimizedEntry 当条目必须响应配置文件、旗帜或预览时 变化 :

<OptimizationRoot spaceId="your-space-id" liveUpdates={true}>
  <OptimizedEntry baselineEntry={entry} liveUpdates={false}>
    {(resolvedEntry) => <Card entry={resolvedEntry} />}
  </OptimizedEntry>
</OptimizationRoot>

浏览器预览面板由 @contentful/optimization-web-preview-panel当面板是 打开, 现场更新强制为所有人 OptimizedEntry 组件,使作者可以检查变体 立即改变.

Web 组件

React SDK继续渲染React组件. OptimizedEntry 不通过自定义渲染 元素,此软件包不导入或注册 Web 组件.

使用可选 @contentful/optimization-web/web-components 只在非反应应用程序或 一个刻意定制的岛屿需要香草定制元素. 围绕这些框架包装 元素必须指定复杂的 DOM 属性, 如 baselineEntry, (中文(简体) ), defaults, (中文(简体) ), api, (中文(简体) ), sdk,以及 水分后调用回调, 并倾听进入生命周期事件, 而不是试图模仿 React 制造道具。 见 Web SDK 读取器 用于生 定制元素和UMD使用.

利用发展

软件包-本地开发工具来自 packages/web/frameworks/react-web-sdk/dev/发射 从回波根:

pnpm --filter @contentful/optimization-react-web dev:launch

利用这把带来开发软件包. 使用参考执行进行端到端整合 行为.

相关

• 将优化回放Web SDK整合到一个回放应用程序中 - 说吧 一步步前进 反应整合指南
• 优化 Web SDK - 由这个软件包包裹的更低级浏览器SDK
• 优化网络组件 - 可选 从 Web SDK 包中曝光的香草自定义元素
• 优化网络预览面板 - 预览面板软件包 浏览器创建工作流程
• React Web 引用执行 - 说吧 应用程序使用提供者、路由器跟踪、优化条目、实时更新和条目跟踪