Step 3. Modifying Our Templates to Run Your Study
⚠️ Before using any of the templates below, you must first complete your own GPT server configuration. This includes deploying a secure backend using your personal OpenAI API key. Please follow the instructions in our Getting Started guide and the full setup instructions in our GitHub repository.
Requirements
If you've completed Steps 1 and 2, you should now have:
- 📄 A .qsf template file
- 🔗 A backend server URL (e.g., https://yourname.vercel.app/lucid)
1. Import into Qualtrics
Log in to Qualtrics. Create a new project and choose “From a File”. Upload your downloaded `.qsf` file.
2. Configure the Survey Flow
Open your Survey Flow. Find the group labeled LUCID VERCEL BACKEND URL. In the LUCIDBackendURL field, paste your deployed backend URL from Vercel. This must end in /lucid.
📸 Show Screenshot: Paste Your LUCID Backend URL
Next, configure the embedded data fields which control your GPT agent’s behavior and appearance. These settings appear in the Survey Flow.
📸 Show Screenshot: Embedded Field Settings
🧠 Prompts
- LUCIDPromptInitial: Defines the AI's role or goal (e.g., "friendly recruiter"). Required.
- LUCIDPromptReinforcement: Optional secondary instruction sent with every message.
- LUCIDIntroMessage: Optional first message shown to participants.
💬 Interface Settings
- LUCIDAIAgentLabel / LUCIDUserLabel: Customize name labels for the AI and the user.
- LUCIDAIBubbleColor / LUCIDUserBubbleColor: Hex colors for chat bubbles (e.g., #dbe6ef).
⏳ Interaction Limits
- LUCIDRoundLimit: Max number of user turns (default: 8).
- LUCIDTimeLimitSeconds: Time limit in seconds (e.g., 600). Leave blank or use 0 for unlimited.
- LUCIDRoundLimitDisplayed: Set to 1 to show message count; 0 to hide.
- LUCIDRoundLimitMessage / LUCIDTimeLimitMessage: Custom messages for when limits are hit.
🧪 Model Parameters
- LUCIDGPTModel: Choose a model (e.g.,
gpt-4o). Leave blank for default.
- LUCIDModelTemperature: Set randomness (0 = deterministic, 2 = very creative). Default: 1.0.
- LUCIDModelSeed: Optional integer seed for reproducibility. Leave blank for varied output.
- LUCIDAIAgentLabel / LUCIDUserLabel: Customize name labels for the AI and the user.
- LUCIDAIBubbleColor / LUCIDUserBubbleColor: Hex colors for chat bubbles (e.g., #dbe6ef).
⏳ Interaction Limits
- LUCIDRoundLimit: Max number of user turns (default: 8).
- LUCIDTimeLimitSeconds: Time limit in seconds (e.g., 600). Leave blank or use 0 for unlimited.
- LUCIDRoundLimitDisplayed: Set to 1 to show message count; 0 to hide.
- LUCIDRoundLimitMessage / LUCIDTimeLimitMessage: Custom messages for when limits are hit.
🧪 Model Parameters
- LUCIDGPTModel: Choose a model (e.g.,
gpt-4o). Leave blank for default.
- LUCIDModelTemperature: Set randomness (0 = deterministic, 2 = very creative). Default: 1.0.
- LUCIDModelSeed: Optional integer seed for reproducibility. Leave blank for varied output.
- LUCIDGPTModel: Choose a model (e.g.,
gpt-4o). Leave blank for default. - LUCIDModelTemperature: Set randomness (0 = deterministic, 2 = very creative). Default: 1.0.
- LUCIDModelSeed: Optional integer seed for reproducibility. Leave blank for varied output.
When you are done, click Save Flow to save your changes.
3. Review Survey Content
Review your survey blocks:
- QID107: Update the consent language for your study.
- QID106: This contains the LUCID HTML/JavaScript. ⚠️ Only edit if you are confident in JS.
- QID102: Customize any follow-up questions or feedback items.
💡 Tip: Always preview your survey to confirm the chatbot appears and communicates with your server.
4. Run Your Study and Look at Your Data
⚠️ SPSS Users: When exporting your dataset, click More Options and set string width to 32,000. This prevents conversation logs from being truncated.
Each completed survey includes embedded metadata and logs that capture how participants interacted with the GPT agent. These outputs help with analysis, debugging, and reproducibility.
🔗 Server Configuration
- LUCIDBackendURL: The backend URL used by this session.
- Other Config Fields: The values you set for prompts, model parameters, limits, etc.
📄 Conversation Log
- LUCIDStructuredLog: A machine-readable JSON string capturing all GPT exchanges, including inputs, outputs, timestamps, and any error data. Requires parsing for analysis.
- LUCIDUserFacingHistory: A plain text version of the conversation in chat format (e.g., "AI: Hello...\nYou: Hi there").
- LUCIDTotalConvTimeMs: Total time (in milliseconds) the participant spent interacting with the GPT agent.
⚙️ Model Settings Used
- LUCIDGPTModel: The model used (e.g., gpt-4o), based on what was set in the Flow or the default.
- LUCIDModelTemperature: The temperature setting applied (default is 1.0 if not specified).
- LUCIDModelSeed: The seed value used, or blank if none was set (non-deterministic).
Using LUCID in your research? Cite us
Garvey, Aaron G. and Simon J. Blanchard (2025). Generative AI as a Research Confederate: The LUCID Methodological Framework and Toolkit for Controlled Human-AI Interactions in Survey Research. Working Paper at SSRN.