内容个性化分析

优化核心 SDK

优化核心SDK拥有平台-可知优化状态机器,事件构建器, sDKs使用的排队、解析器和截取器。 Web, 反应 Web, 节点, 反应 原生地和原生地的桥梁地层以这个包为基础.

我们建议用一个SDK平台而不是Core直接开始应用代码. 使用这个 在建立或维护 SDK 层时读取 EADME, 并使用 选择正确的 SDK 在决定集成中属于哪个应用软件包时。 已生成 参考文件 仍然是真相的来源 导出 API 签名.

[大

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

开始

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

pnpm install @contentful/optimization-core

根据您正在构建的运行时间层选择状态或无国籍的核心类 :

import { CoreStateful, CoreStateless } from '@contentful/optimization-core'

const statefulOptimization = new CoreStateful({
  spaceId: 'your-space-id',
})
const statelessOptimization = new CoreStateless({
  spaceId: 'your-space-id',
})

国有运行时间拥有持久的SDK状态. 无国籍的运行时间约束了请求范围的同意, 调用事件方法前的配置状态、事件上下文和经验 API 选项:

const requestOptimization = statelessOptimization.forRequest({
  consent: true,
  locale: 'en-US',
  eventContext: { locale: 'en-US' },
  experienceOptions: { preflight: false },
  profileId: 'f0837d7dc6344c36a3a0a06c4cde754b',
})

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

何时使用此软件包

使用 @contentful/optimization-core 当您正在建造或维护一个 SDK 层时,需要 共享优化状态机器,事件构建器,队列,解析器,或截取器. 多数 应用程序代码使用 SDK 平台, 如 Web, React Web, Node, 或 React Intext 而不是 直接取决于核心.

核心变体

状态核心

CoreStateful 是SDK在状态 JavaScript 运行的基础,例如浏览器, 移动 JavaScript 容器,和本土桥跑时. 它维持同意,配置,选择 优化,旗帜,事件流,被屏蔽的事件,以及预览-板块状态作为只读可观察.

reset() 丢弃队列事件, 并取消状态更新 。 撤销事件同意 在用户运行前完成清理. destroy() 尝试最后排队交付和释放 在另一个实例启动前进行内部订阅;应用程序订阅仍保留 呼叫者拥有。 见 核心国家管理 对于生命周期和可观察的行为.

[大

CoreStateful 设计时使用模块-全局状态。 初始化 : JavaScript 运行时间并重用.

无国籍核心

CoreStateless 是在诸如节点服务器和 服务器侧函数 。 它不存储请求之间的同意或配置状态。 消费者打电话 forRequest() 将同意、事件背景和经验选项约束在收到的一项请求中. 过 profileId 经验连续性或全经验 Profile 结束 profile 为入想. 经验答复更新了请求-地方概况,以便日后发出呼吁.

请求客户端还显示只读 eventBuilder 用于构建标识的外表,页, 屏幕,并跟踪带有请求上下文和语言默认的有效载荷。 建筑使用共享 构建器的元数据和提供商未经申请同意,运行提交截取器, 或更新请求状态。 对正常提交使用直接请求事件方法; 低级 API 已建事件的电话不会自动应用此处理。 SDK的根头 eventBuilder 是无约束的。 见 节点请求范围事件示例。 。 。 .

通用配置

共享核心配置 :

同意和事件配置 :

核心本身未能在同意前关闭。 平台 SDKs 为事件设定运行时间的默认值 在该运行时间中有意义的类型,例如浏览器 identify编号 :page,服务器 identify编号 :page, (中文(简体) ), 移动 identify编号 :screen。 。 。 .

只有状态配置 :

持久性同意控制具有运行时间存储的 SDK 的持久配置-连续存储 : 配置文件、匿名ID、更改和选定的优化缓存。 事件同意,存储同意 决定和调试状态分别跟踪.

常见 api 选项:

两个核心构建器都接受 api.location; 平台 SDKs继承了该配置. 无国籍请求客户通过它覆盖 forRequest({ experienceOptions: { location } })数字 :

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

请求位置取代整个构造器默认值,包括明确 {}活动 context.location 继续分开,并优先于 API 的匹配请求字段. 空请求位置提供空默认, 而不是 API 地理定位; 它不清晰 现有配置文件位置。 这是请求评价输入, 而不是永久配置文件锁定 。 对于 后端优先级和配置连续性,参见 位置输入和简介更新。 。 。 .

何时 plainText 被省略,使用单相标注的经验突变/事件请求 text/plain。 。 。 . 过 plainText: false 派JSON来 经验批量剖面更新仍然默认为JSON.

在无国籍环境中,通过 ip, (中文(简体) ), locale, (中文(简体) ), plainText,以及 preflight 作为 experienceOptions 当创建请求绑定的客户端而不是构建器配置时。 传递特定请求的透视 API 选项, 如最后的尝试 beacon 发送者, 如 insightsOptions。 。 。 .

核心支持状态的 SDK 可以接受初始顶级 locale 和运行时间 setLocale(locale) 打电话 他们揭露了SDK体验 API和默认事件 locale通过直播 locale 获取器 财务报告和审定财务报表 states.locale 可见. 无国籍服务器 SDKs 应当通过请求扫描的 SDK 语言 forRequest({ locale }); 高级呼叫者仍然可以通过 experienceOptions.locale 没有请求时 locale 提供.

应用程序拥有Contentful CDA 语言选择,并将该语言直接传递到其内容 客户端。 完整的语言模式见: 优化 SDK 套件中的位置处理。 。 。 .

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

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

运动归属

事件构建者明确使用 campaign 提供数据时。 否则,他们推断 context.campaign 从 utm_campaign, (中文(简体) ), utm_source, (中文(简体) ), utm_medium, (中文(简体) ), utm_term,以及 utm_content 参数 page.url。它们不检查 page.referrer。 。 。 .

对于一个页面活动, properties.url 提供至少包含一个运动的推断运动 支持 UTM 参数。 否则,建造者使用已解决的 context.page.url解决 URL来自一个明确 page.url,或从 getPageProperties() 当事件输入不 超过它。 如果两个符合条件的 URL 解析一个支持的 UTM 参数,则推断的战役是 空无相.

软件包表面

核心曝光 SDK 层的可再用原始:

Schema 切入点

@contentful/optimization-core/api-schemas 拥有Contentful CDA计划,推断类型,以及 core 所用的助手 。 它还通过经验API和Insights API验证表面 从 @contentful/optimization-api-client/api-schemas,因此 SDK 层可以保留单个集合 有用时导入方案 :

import { OptimizationConfig, ExperienceResponse } from '@contentful/optimization-core/api-schemas'

对于直接经验API或Insights API的工作,从 @contentful/optimization-api-client/api-schemas 使用他们自己的包。 不添加导入 从被掠夺的 @contentful/optimization-api-schemas 兼容软件包.

当a contentful.js 客户端是可用的, 更喜欢 SDK 管理的获取 。 配置 contentful: { client, defaultQuery?, cache? },然后通过ID或内容类型识别每个条目 和弹片 :

await sdk.fetchOptimizedEntry({
  contentType: 'page',
  slug: 'home',
  slugField: 'slug',
  entryQuery: { locale: 'en-US' },
})

slugField 默认为 slug。管理电话合并 defaultQuery, (中文(简体) ), entryQuery,SDK或请求 locale 倒计时 include: 10。然后强制检查 content_type, (中文(简体) ), fields.<slugField>,以及 limit: 2,因此,这些选择者将超过相冲突的查询值。 这个 当结果不独有时, 丢出这些错误 :

Contentful entry not found for content type "<contentType>" where "fields.<slugField>" equals "<slug>".
Multiple Contentful entries found for content type "<contentType>" where "fields.<slugField>" equals "<slug>".

ID 检查保留相同平滑未标记条目的分批处理,并将大批分为 100 ID 块. 结果保持描述顺序和重复。 每个 SDK 管理取取缓存条目 默认实例; 设置 contentful.cache: false 以禁用缓存或调用 clearContentfulEntryCache() 来清理它。 粘住先发制人 固定的描述符 下级 managedEntry 并保留取入的条目 sys.id 内 entryId。 。 。 . resolveOptimizedEntry() 仍然是已获取的应用程序条目的手工路径 。 状态核心 在省略时使用当前选择, 受请求的无国籍客户使用最近接受的 选择和请求地方回落,而根无国籍者通过明确的选择.

解析器类型接受一个骨架或每个可能的基线和变异骨架的结合. 见 条目优化和变量分辨率 用于不同条目的打字和收缩.

框架 SDK 在服务器、 静态或边缘渲染时使用 Core 选择手动帮助 了解选中的优化 . createHandoffFromSelections() 明确选择的记录 状态和缓存元数据而不选择浏览器水合行为。 可缓存的公共布局 可使用 createPublicPermutationCacheMetadata() 确定性键和可选的呼叫者 无效标记 . resolveEntriesForSelections() 解决一组输入中的基线条目 服务器上加号的命令,以及 createSelectionFingerprint(), (中文(简体) ), createOptimizationCacheKey(), (中文(简体) ), getOptimizationCacheSafetyWarnings(),以及 assertOptimizationCacheSafety() 支持客户拥有的缓存密钥和诊断.

不要通过全本地 CDA 回复 withAllLocales 或者说 locale=*; 优化字段 作为 fields.nt_experiences 财务报告和审定财务报表 fields.nt_variants 必须是直接的单地字段值。 见 条目优化和变量分辨率 进入合同和 优化 SDK 套件中的位置处理 为更广泛的地方模式.

自定义条目源适配器

@contentful/optimization-core/entry-source 自定义 JavaScript 运行时间的高级子路径 或 框架适配器不能使用正式的 Web, React Web, React 原生,节点,或原生SDK 表面。 它不是根核心 API 态势的一部分, 也不是优先应用的路径 一体化.

导入 OptimizedEntrySourceController 当适配器接受直接 baselineEntry,管理 条目ID,或管理的内容类型/污名源。 控制器拥有源生命周期和查询 键入、SDK准备/装入/反射快照、Stale请求保护,以及 disconnect() 清净相. 在取出弹片后,快照和下游追踪使用取取入的条目 sys.id。 。 。 . createOptimizedEntryLoadingEntry(entryId) 创建稳定的占位符 装入状态.

输入源控制器不拥有渲染,变异分辨率,跟踪,同意, 体验 API 调用,或 内容丰富的客户端创建 。 在一个快照后 baselineEntry,则 适配器仍然调用 resolveOptimizedEntry(),生成结果,并给任何运行时间指定线条 追踪.

生成的引用拥有方法参数、返回类型、召回有效载荷形状并继承 成员。 保持这个README专注于包角色和维护者取向.

预览支持

Preview-panel 助手在内部居住 preview-support 输入。 它们被第一当事方预览表面用来注册预览状态桥,应用 优化本地作者工作流程的功能, 并绘制内容条目 .

应用程序代码不能直接使用预览支持, 除非它正在构建先行预览 表面.

相关

• 选择正确的 SDK - 说吧 应用程序集成软件包选择指南
• 核心 SDK 生成参考 - 说吧 导出 API 引用
• 优化 Web SDK - 浏览器SDK CoreStateful
• 优化节点 SDK - 服务器SDK基于 CoreStateless
• 优化反应原生 SDK - 移动式SDK CoreStateful
• API 客户端 - API直接运输和经验 API和Insights API 计划所有权
• API 斯克马斯 - 贬值的相容外观和进口迁移 指导
• 核心预览支持 - 内部预览帮助条目