Survey lifecycle events

Available Events

Event name	Trigger	Data
SURVEY_SHOWN	When a survey appears to the user.	survey_id,platform,respondent_id,respondent_attributes, timestamp
SURVEY_STARTED	When user answers the first question of the survey.	survey_id,platform,respondent_id,respondent_attributes,next_survey_after (only for recurring surveys), timestamp
SURVEY_CLOSED	When user closes a survey by clicking on “X” button.	survey_id,platform,respondent_id,respondent_attributes,next_survey_after (only for recurring surveys),timestamp
SURVEY_COMPLETED	When user completes all the survey questions and reaches thank you screen.	survey_id,platform,respondent_id,respondent_attributes,timestamp

Implementation

React/Next.js Applications

import spark, { FSEVENTS } from "feedbackspark";;

useEffect(() => {
spark('addEventListener', FSEVENTS.SURVEY_SHOWN, function(data) {
 // Handle survey shown
 console.log('Survey was shown:', data);
});

spark('addEventListener', FSEVENTS.SURVEY_COMPLETED, function(data) {
 // Handle survey completion
 console.log('Survey completed:', data);
});

// Clean up listeners when component unmounts
return () => {
 spark('removeEventListener', FSEVENTS.SURVEY_SHOWN, callback);
 spark('removeEventListener', FSEVENTS.SURVEY_COMPLETED, callback);
};
}, []);

HTML/JavaScript Applications

<script>
spark('addEventListener', spark.EVENTS.SURVEY_SHOWN, function(data) {
 // Handle survey shown
 console.log('Survey was shown:', data);
});

spark('addEventListener', spark.EVENTS.SURVEY_COMPLETED, function(data) {
 // Handle survey completion
 console.log('Survey completed:', data);
});
</script>

Event Data

Each event callback receives a data object containing relevant information:

{
  survey_id: 303,                                         // Unique identifier for the survey
  environment: "production",                              // Indicates whether the event occurred in production or sandbox
  platform: "web",                                        // Distribution channel of the survey (web, email, link, mobile)
  next_survey_after: "2025-02-14T05:35:24.334123Z",       // ISO 8601 date string indicating when respondent can receive next survey. Available only for recurring surveys.
  respondent_id: "7c079bf2-b1d0-4154-ac51-3a5e57e7df9e", // Unique identifier for the respondent set via setUser API
  respondent_attributes: {                                // JavaScript object containing respondent attributes
    plan: "Free",                                        // Set via setAttributes API or link survey URL
    Paid: "No"
  },
  timestamp: "2025-01-29T13:13:22.038Z"                  // ISO 8601 string of when event occurred
}

Notes:

1. next_survey_after is available only for recurring surveys AND if there is a next survey scheduled. It is an ISO 8601 date string and will be available in SURVEY_STARTED and SURVEY_CLOSED events.
2. respondent_attributes are set via setAttributes API or link survey URL.

Common Use Cases

1. Analytics Integration

   spark('addEventListener', SPARK_EVENTS.SURVEY_COMPLETED, function(data) {
     analytics.track('Survey Completed', {
       surveyId: data.surveyId,
       timestamp: data.timestamp
     });
   });

2. CRM Updates

   spark('addEventListener', SPARK_EVENTS.SURVEY_COMPLETED, function(data) {
     updateUserProfile({
       lastSurveyCompleted: data.timestamp,
       surveyId: data.surveyId
     });
   });

3. Custom UI Updates

   spark('addEventListener', SPARK_EVENTS.SURVEY_SHOWN, function() {
     // Hide conflicting UI elements
     document.getElementById('chat-widget').style.display = 'none';
   });
   
   spark('addEventListener', SPARK_EVENTS.SURVEY_CLOSED, function() {
     // Restore UI elements
     document.getElementById('chat-widget').style.display = 'block';
   });

Best Practices

1. Always remove event listeners when they’re no longer needed to prevent memory leaks.
2. Handle errors in your event callbacks to prevent survey functionality disruption.
3. Keep event handlers lightweight to maintain survey performance.
4. Test event integration in development environment before deploying.

Troubleshooting

1. If events aren’t firing, ensure the SDK is properly initialized.
2. Check browser console for any errors in event callbacks.
3. Verify event names match exactly (e.g., SURVEY_SHOWN not SURVEY_SHOW).
4. For React apps, ensure event listeners are properly cleaned up in useEffect.