PostMessage 接收触发器

当您运行的 Labvanced 实验通过浏览器的 postMessage API 接收到来自外部源的传入消息时，PostMessage 接收触发器会触发。您可以使用它将您的研究连接到父网页、自定义应用程序或将数据直接发送到实验的嵌入式外部网站。

概述

您可以在触发器选择菜单的API/外部触发器下找到PostMessage 接收触发器。

在 Labvanced 事件编辑器中从 API/外部触发器类别选择 PostMessage 接收触发器.

在事件编辑器中定位PostMessage 接收触发器，位于API/外部触发器下。

常见用例

嵌入网站将用户交互事件（点击、表单填写）转发到 Labvanced，作为结构化的 postMessages。
父应用程序（例如，自定义 LMS 或机构网页门户）发送消息以推进实验或传入参与者数据。
JavaScript 驱动的集成，在这种情况下，外部脚本触发实验逻辑中的特定点。

双向设置

在 Labvanced 和外部页面（例如 iFrame 或父应用程序）之间使用 postMessage 是一个双向过程。Labvanced 处理一侧：该触发器监听传入消息。另一侧是外部页面，必须编程以发送这些消息。

postMessage API 是一种标准的浏览器功能。外部页面使用 window.parent.postMessage(data, targetOrigin) 将数据发送到 Labvanced。您或您的开发人员需要编写该代码。AI 编码工具也可以通过提供上下文快速帮助您设置。

一种常见模式是外部页面监听其自身的用户事件（例如点击、表单提交或注册），然后将每个事件作为 postMessage 转发到 Labvanced。每种事件类型可以使用 Key 字段标记一个标签（例如，click_event，signup_event），以便 Labvanced 可以过滤并分别响应每个事件。

工作原理

当实验运行时，Labvanced 监听传入的 postMessages。每当消息到达时，它会检查两个方面：

源域：此消息是否来自允许的源？
Key：此消息是否携带预期的键值（如果设置了的话）？

如果满足这两个条件，触发器就会触发，该消息有效负载将作为消息内容在您的操作中可用。

外部页面负责发送消息。它通过在其自身代码中调用 window.parent.postMessage(data, targetOrigin) 来实现。它发送的data可以是任何内容：一个普通字符串、一个结构化值或一个事件标签。Labvanced 中的 Key 字段是您匹配该标签特定值的方式，以区分一种消息类型和另一种。

每种消息类型可以在 Labvanced 中具有其自己专用的事件。例如，一个事件使用 Key: click_event 在外部页面报告点击时触发，而另一个使用 Key: signup_event 在报告表单提交时触发。

选择 PostMessage 接收 后，将出现以下对话框：

Labvanced 中的 PostMessage 接收触发器配置对话框，显示源域和密钥字段。

对于PostMessage 接收触发器的配置选项。传入的消息值将作为消息内容导出。

触发器选项

菜单项	PostMessage 接收触发器选项
`源域`	指定哪个域被允许发送消息到此触发器。默认值为``，允许来自任何源的消息。要限制触发器到特定源，请将``替换为完整的源 URL（例如，`https://yoursite.com`）。建议在已知发送源的情况下进行此操作。
`Key`	输入您希望此触发器匹配的特定键值（例如，`click_event`，`signup_event`）。仅当传入的消息携带该确切键值时，触发器才会触发。将字段留空以在任何传入消息上触发，无论内容如何。

注意：传入的消息值将作为消息内容导出，并可以通过值选择菜单在操作中引用。

触发器特定值

在选择了 PostMessage 接收 触发器后，您可以在随后的操作中通过值选择菜单引用以下触发器特定值。

值	描述
`消息内容`	接收到的 postMessage 的数据有效负载。这是外部源发送的值，可存储在变量中，用于驱动逻辑，或记录为数据集的一部分。
`触发器时间戳 (Unixtime)`	触发器触发时的时间戳，以 Unix 时间表示。
`触发器时间 (从帧开始)`	从当前帧开始到触发器触发的毫秒数。

进一步阅读及开放材料

发送 PostMessage 操作：将消息发送回外部源的配对操作。
值选择菜单：如何在操作中引用触发器特定值。
事件概述：Labvanced 中触发器与操作逻辑系统的完整介绍。

目录