In a signal-contingent design, Samply decides when participants are notified. In an event-contingent design, the participant decides — they self-initiate a report immediately after a target event occurs in their life. Samply supports event-contingent designs through named event types that appear inside the Samply Research app.
Setting up event-contingent design
Open your study dashboard, go to the Settings tab, and enable Event-contingent design. Two configuration fields appear:
- Participant-facing instructions
- A text block shown to participants in the Samply app after they join. Explain what kind of event they should report and how to use the links — for example, “Tap the button below each time you experience a stressful event at work.”
- Event types (up to 5)
- Each event type has a caption — the label the participant sees in the app — and a URL — the survey link that opens when they tap that caption. You can define between one and five distinct event types. If your study has only one kind of self-report, define one event type. If participants can report different categories of experience (e.g. positive event, negative event, neutral event), define one type per category, each pointing to a different survey or passing a different parameter.
Once saved, the event types appear in the participant's study screen in the Samply app. Tapping a caption immediately opens the corresponding URL — no notification needed.
URL placeholders in event type links
Each event type URL supports the same %TOKEN% placeholders as scheduled notifications. Samply substitutes them at the moment the participant taps the link:
| Token | Replaced with |
|---|---|
%SAMPLY_ID% | The participant's anonymous Samply ID. |
%PARTICIPANT_CODE% | The custom code entered at enrolment (left unreplaced if no code). |
%GROUP_ID% | The participant's group ID (left unreplaced if no group). |
%TIMESTAMP% | Unix timestamp (milliseconds) at the moment the link is tapped. |
A typical event type URL looks like this:
%TIMESTAMP% captures the tap time — the moment the participant decided to report — not a server-side dispatch time. Use this as your event timestamp in analysis. See URL placeholders for the full token reference.
When to use event-contingent sampling
- Pure event-contingent
- Participants tap an event type whenever a target event occurs — a conflict, a craving, a social interaction. No scheduled notifications needed. The study consists entirely of self-initiated reports.
- Hybrid design
- Combine scheduled notifications (signal-contingent) with event types (event-contingent). Participants receive timed prompts and can self-initiate at any time. Both types of report appear in the history log.
- Multiple event categories
- Use up to five event types to distinguish between categories of experience. Each type can route to a different survey condition or pass a different identifier so responses are automatically sorted in your data.
Tracking self-initiated reports
Taps on event type links are recorded in the history log with the tap timestamp. The CSV export includes the tap time in the event timestamps column, letting you distinguish scheduled sends from self-initiated reports.
To correlate a self-initiated report with the triggering event, pass %TIMESTAMP% to your survey tool and store it as an embedded data field. This gives you a researcher-independent record of when the participant decided to report, regardless of network delays or survey load time.
Event-contingent vs geofencing
Event type links rely on the participant to recognise and report the target event — they are subjective and voluntary. Geofencing detects location events automatically and fires a notification without participant action. Use geofencing when the target event has a precise GPS signature; use event-contingent design when the event is psychological, social, or otherwise not detectable by sensors.