Version: latest

快速入门

下面用一个 Hello World 实验带你跑通全流程：写实验 → 打包 zip → 上传到问卷 → 看到数据回收。全程不需要自己的服务器，也不需要写任何数据上传代码。

第一步：添加实验题

在问卷编辑页，左侧题型栏找到「实验嵌入」分类，选择 jsPsych 添加到问卷中。

添加后，题目区域会出现一个「开始实验」按钮，题目下方是实验文件的上传区。这个按钮就是受访者进入实验的入口，由系统生成，文案可在右侧栏的「按钮文案」中修改。

第二步：编写实验

一个实验就是一个普通的静态网页：一个 HTML 入口文件，加上它引用的脚本、样式与素材。

引入 jsPsych

按 jsPsych 官方推荐的 CDN 方式引入即可，本文示例统一使用 unpkg。建议直接用最新版：

<script src="https://unpkg.com/jspsych@8.3.0"></script>
<script src="https://unpkg.com/@jspsych/plugin-html-button-response@2.1.0"></script>
<link rel="stylesheet" href="https://unpkg.com/jspsych@8.3.0/css/jspsych.css" />

jsPsych 本体与插件是分开发布的，用到哪个插件就引哪个。上例只用了 html-button-response（呈现一段 HTML 并记录点击的按钮），完整插件列表见 jsPsych 插件总览。

请锁定版本号

示例里写死了版本号（如 jspsych@8.3.0）。不要用 https://unpkg.com/jspsych 这种不带版本号的写法——它会随上游发版自动升级，可能让已经投放中的实验行为发生变化。

引入腾讯问卷 SDK

这是接入的关键一步。腾讯问卷官方 SDK 负责把 jsPsych 采集的数据回传给问卷：

<script src="https://wj.txresearch.com/psy_task/wj-jspsych-sdk@8.0.0.js"></script>

必须引入

未引入官方 SDK 的实验包无法上传成功。 实验运行在受限沙箱里、没有网络出口去自建服务器，数据只能经由 SDK 回传给问卷，因此这个 script 标签是必需的。

关于版本选择：

SDK 的主版本号与 jsPsych 的主版本号对应。用 jsPsych 8.x 就引 wj-jspsych-sdk@8.0.0.js，用 jsPsych 7.x 就引 wj-jspsych-sdk@7.0.0.js。
SDK 会不定期修复与更新，版本号在主版本内递增（如 8.0.1）。请以 SDK 介绍里的最新版本为准。
若引入的 SDK 与 jsPsych 主版本不匹配，实验仍会运行，但控制台会打印告警并提示应改用哪个版本。

SDK 只要在 initJsPsych() 被调用之前加载即可，与 jsPsych 自身的先后顺序无关。为了避免顺序出错，建议把它放在所有依赖之后、实验代码之前。

编写实验代码

const jsPsych = initJsPsych();

const timeline = [];

// 欢迎页：点击按钮继续
const welcome = {
  type: jsPsychHtmlButtonResponse,
  stimulus: '<h2>Hello World!</h2><p>点击下方按钮开始</p>',
  choices: ['开始'],
};
timeline.push(welcome);

// 试次：记录选择哪个按钮，以及从呈现到点击的反应时
const trial = {
  type: jsPsychHtmlButtonResponse,
  stimulus: '<p>请尽快点击 <strong>红色</strong></p>',
  choices: ['红色', '蓝色'],
};
timeline.push(trial);

jsPsych.run(timeline);

choices 里每一项就是一个按钮，数据中的 response 记录的是被点击按钮在数组里的下标：点「红色」记为 0，点「蓝色」记为 1。

完整的 index.html

把上面几部分拼起来就是可以直接打包上传的实验入口：

<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Hello World 实验</title>

    <!-- 1. jsPsych 本体与插件 -->
    <script src="https://unpkg.com/jspsych@8.3.0"></script>
    <script src="https://unpkg.com/@jspsych/plugin-html-button-response@2.1.0"></script>
    <link rel="stylesheet" href="https://unpkg.com/jspsych@8.3.0/css/jspsych.css" />

    <!-- 2. 腾讯问卷官方 SDK（必须引入，且需在 initJsPsych() 之前加载） -->
    <script src="https://wj.txresearch.com/psy_task/wj-jspsych-sdk@8.0.0.js"></script>
  </head>
  <body>
    <!-- 3. 实验代码，无需编写任何数据上传逻辑 -->
    <script>
      const jsPsych = initJsPsych();

      const timeline = [];

      const welcome = {
        type: jsPsychHtmlButtonResponse,
        stimulus: '<h2>Hello World!</h2><p>点击下方按钮开始</p>',
        choices: ['开始'],
      };
      timeline.push(welcome);

      const trial = {
        type: jsPsychHtmlButtonResponse,
        stimulus: '<p>请尽快点击 <strong>红色</strong></p>',
        choices: ['红色', '蓝色'],
      };
      timeline.push(trial);

      jsPsych.run(timeline);
    </script>
  </body>
</html>

第三步：打包成 zip

以 index.html 为根目录文件，连同素材一起打包成 zip：素材用相对路径引用，整个包不超过 50MB。目录结构如下：

experiment.zip
├── index.html
└── assets/
    ├── cue.png
    ├── bar.css
    └── foo.js

第四步：上传实验文件

回到问卷编辑页，选中实验题，点击题目下方的「点击上传实验文件」，选择刚才的 zip 包。

上传成功后会展示实验文件名。上传的实验文件有效期 90 天，到期后实验地址会失效、无法访问，如需继续投放请在到期前重新上传一次实验文件。

数据是怎么回传的

受访者点击「开始实验」后，实验以全屏形式打开。此后：

每结束一个 trial，SDK 就把该 trial 的数据对象通过 postMessage 回传给问卷一次。
问卷按自定义变量过滤：数据对象的 key 命中已声明变量的才入库，其余静默丢弃。
实验跑完时，SDK 发送结束信号，问卷收起全屏、把本次收集到的数据写为这道题的答案，按钮随即换成一张「已完成实验」的卡片；如需重新作答，点卡片右侧的「重做」。

以上面的 Hello World 为例，两个 trial 会各上报一次，问卷侧收到的数据形如：

[
  [
    { "key": "trial_type", "time": 1737345600000, "value": "html-button-response" },
    { "key": "trial_index", "time": 1737345600000, "value": 0 },
    { "key": "time_elapsed", "time": 1737345600000, "value": 1043 },
    { "key": "rt", "time": 1737345600000, "value": 1021 },
    { "key": "response", "time": 1737345600000, "value": 0 }
  ],
  [
    { "key": "trial_type", "time": 1737345602000, "value": "html-button-response" },
    { "key": "trial_index", "time": 1737345602000, "value": 1 },
    { "key": "time_elapsed", "time": 1737345602000, "value": 2412 },
    { "key": "rt", "time": 1737345602000, "value": 366 },
    { "key": "response", "time": 1737345602000, "value": 0 }
  ]
]

trial_type、trial_index、time_elapsed、internal_node_id、rt、response、stimulus 这些 jsPsych 内置字段问卷已内置声明，开箱即可收集；实验里自定义的字段需要自己声明，详见自定义变量。

数据可在「数据详情」中查看：实验题会显示「查看数据」按钮，点击后以表格展示，每行对应一个 trial。

本地预览

出于安全考虑，SDK 只允许实验在腾讯问卷内运行。直接用浏览器打开 index.html 时，页面会提示「本实验需在腾讯问卷内作答」且实验不会启动——这是预期行为，不是接入失败。

要验证实验本身的流程，可以在开发阶段先不引入 SDK、单独调通实验逻辑，再加上 SDK 打包上传，用问卷的「预览」功能实测一遍完整链路。

下一步

高级选项：自定义变量的配置说明与数据体积限制。
SDK 介绍：各版本适配范围、手动 API 与已知限制。

第一步：添加实验题​

第二步：编写实验​

引入 jsPsych​

引入腾讯问卷 SDK​

编写实验代码​

完整的 index.html​

第三步：打包成 zip​

第四步：上传实验文件​

数据是怎么回传的​

本地预览​

下一步​