createSession(options) → Session
为一个具体的用户和对话创建一个广告会话。
在用户整个生命周期内保持不变的唯一标识(用于个性化、频次封顶、奖励广告)。
本次对话启用的 placement code。默认为 ['inlineAd']。
隐私 / consent 信号。
请求是否受 GDPR 约束。(0 = 否,1 = 是,null = 未知)
IAB 透明度与同意框架(TCF)的 consent 字符串。
请求是否受 COPPA 约束。(0 = 否,1 = 是,null = 未知)
Global Privacy Platform (GPP) consent 字符串。
本次请求适用的 GPP section ID 列表。
美国隐私法规(如 CCPA、LSPA)相关的消费者信号。
每个广告生命周期事件触发时的回调。详见下方”支持的事件”章节。
SDK 内部诊断事件的回调。接收 (name, data?)——在接入期间排查 preload / session 行为时很有用。默认关闭。
Session 方法
session.addMessage(message, options?)
向 SDK 注册一条聊天消息。在合适的时机会触发一次防抖后的预加载。
当为 true 时,preload 请求仍会发出(用于分析),但本条消息不会展示广告。
session.createAd(messageId, options?) → Ad
为特定助手消息创建一个 Ad。该方法不会等待广告——一旦有广告可用就会渲染。对同一个 messageId + code 多次调用会返回同一个实例。
Placement code(默认 'inlineAd')。
传递给广告 iframe 的视觉主题(例如 'light'、'dark')。
session.render(options) → Ad
createAd + mount 的一次性便捷封装。
Placement code(默认 'inlineAd')。
session.updateOptions(partial)
在活跃会话上实时更新与预加载相关的配置。接受的字段:variantId、regulatory、userEmail、advertisingId、vendorId。变更会在下次 /preload 时读取,因此会在下一条用户消息生效——无需重建会话。
publisherToken、userId、conversationId、enabledPlacementCodes 与 character 不可实时更新。会话中途修改它们会让 /init 注册与后续请求不一致,或者让已累积的消息历史指向错误的人设。请改为重建会话。
session.destroy()
清理内部状态、取消进行中的预加载,并停止后续预加载请求。请在对话结束或页面卸载时调用。destroy() 之后,addMessage、createAd、render 等修改型方法会抛出异常。
session.getSessionId() → string | null
服务端分配的 session ID。首次 /preload 成功之前为 null。
session.isDisabled() → boolean
若服务端在 /init 响应中永久关闭了该会话(例如地域限制),返回 true。后续预加载会被跳过。
session.isDestroyed() → boolean
destroy() 被调用过则返回 true。
session.getMessages() → readonly Message[]
会话已记录消息的快照,按插入顺序排列。请勿原地修改,也不要长期缓存——当消息数量超过上限时,内部数组会被替换为裁剪后的副本。
session.getPreloadTimeout() → number
当前 /preload 请求超时(毫秒)。可能由 /init 响应中的服务端配置覆盖。
Ad 方法
ad.mount(element)
把广告 iframe 挂载进指定的 DOM 元素。每个 Ad 实例只能挂载一次——重复挂载会抛出异常。
ad.destroy()
把 iframe 从 DOM 中移除,并释放所有监听器。幂等——可以安全地多次调用。
Message 结构
支持的事件
ad.clicked
用户点击了广告。
ad.viewed
用户已查看广告。
ad.filled
有可投放的广告。
ad.no-fill
没有可投放的广告。
ad.render-started
在第一个 token 到达之前触发。
ad.render-completed
在最后一个 token 到达之后触发。
ad.error
出现错误时触发。
video.started
视频开始播放时触发。
video.completed
视频播放完成时触发。
reward.granted
用户在激励广告流程中获得奖励时触发。