
PostMessage 接收触发器
PostMessage Received 触发器在您运行的 Labvanced 实验通过浏览器的 postMessage API 接收到来自外部来源的传入消息时触发。使用它将您的研究连接到父网页、定制应用程序或发送数据直接到实验的嵌入外部网站。
概述
PostMessage Received 触发器可以在触发器选择菜单的 API/External Trigger 下找到。

常见用例
- 嵌入的网站将用户交互事件(点击、表单完成)作为结构化 postMessages 转发到 Labvanced。
- 一个父应用程序(例如,定制的 LMS 或机构网站门户)发送消息以推进实验或传入参与者数据。
- 一个基于 JavaScript 的集成,外部脚本在实验逻辑的特定点触发。
双向设置
在 Labvanced 和外部页面(如 iFrame 或父应用程序)之间使用 postMessage 是一个 双向过程。Labvanced 处理一侧:该触发器监听传入消息。另一侧是外部页面,必须编程以发送这些消息。
postMessage API 是一个标准的浏览器功能。外部页面调用 window.parent.postMessage(data, targetOrigin) 将数据发送到 Labvanced。您或您的开发人员需要编写该代码。AI编码工具也可以通过提供上下文来帮助您快速设置。
常见模式是外部页面监听其自身的用户事件(如点击、表单提交或注册),然后将每一个作为 postMessage 转发到 Labvanced。每种事件类型可以使用 click_event, signup_event 来标记,通过 Key 字段来使 Labvanced 能够过滤并单独响应每一个。
工作原理
当实验运行时,Labvanced 监听传入的 postMessages。每当消息到达时,它会检查两件事情:
- 来源域:这条消息来自允许的来源吗?
- 键:这条消息是否携带预期的键值(如果设置了)?
如果两个条件都满足,触发器将触发,消息有效载荷将可以在您的操作中作为 Message Content 使用。
外部页面负责发送消息。它通过在其自身代码中调用 window.parent.postMessage(data, targetOrigin) 来做到这一点。它发送的 data 可以是任何内容:普通字符串、结构化值或事件标签。Labvanced 中的 Key 字段是您匹配该标签的特定值的方式,以区分不同类型的消息。
每种消息类型可以在 Labvanced 中拥有自己的专用事件。例如,一个事件使用 Key: click_event 在外部页面报告点击时触发,另一个使用 Key: signup_event 在报告表单提交时触发。
选择 PostMessage Received 后,将出现以下对话框:

触发器选项
| 菜单项 | PostMessage 接收触发器选项 |
|---|---|
Origin Domain | 指定允许哪个域发送消息到此触发器。默认值为 *,接受来自任何来源的消息。为了将触发器限制为特定来源,请用完整的源 URL(例如 https://yoursite.com)替换 *。建议在发送源已知的情况下使用。 |
Key | 输入您希望该触发器匹配的特定键值(例如 click_event, signup_event)。仅在传入的消息携带该确切键值时,触发器才会触发。若要在任何传入消息上触发,无论内容如何,请将字段留空。 |
注意: 传入消息值将导出为 消息内容,并可以在操作中通过 值选择菜单 引用。
PostMessage 接收的触发器特定值
选择 PostMessage Received 触发器后,您可以在后续操作中通过 Value-Select Menu 引用以下触发器特定值。
| 值 | 描述 |
|---|---|
Message Content | 接收的 postMessage 的数据有效载荷。这是由外部来源发送的值,可以存储在变量中,用于逻辑驱动,或作为数据集的一部分记录。 |
Trigger Timestamp (Unixtime) | 触发器触发时的时间戳,以 Unix 时间格式。 |
Trigger Time (From Frame Onset) | 从当前帧开始到触发器触发的时间,以毫秒为单位。 |