Dismissing and persisting surveys

[eliasyishak]

This feature will add the ability to dismiss a survey and have its unique id be persisted locally on disk so that it doesn't get prompted again to the user. A dismissal occurs if the user chooses to open the survey or dismiss it without completing it

Address umbrella issue:

• ☂️ Create a survey handler class to enable package to share surveys #81

Example of usage

// This will grab any available surveys from the remote host and apply
// the sampling rate (if applicable for that survey) and check that the
// the surveys available have not been dismissed or snoozed
final surveyList = analytics.fetchAvailableSurveys();

if (surveyList.length > 0) {
  // Recommended to take the first item in the list since
  // there could be multiple surveys available
  final survey = surveyList.first;

  // pseudo-code to simulate "showing" the survey
  display(survey);

  // Should call the below method to snooze the survey
  analytics.surveyShown(survey);

  // How to handle a permanent dismissal of the survey
  // (ie. the user clicked "No, skip survey"
  if (status == 'dismissed') {
     analytics.dismissSurvey(
       survey: survey,
       acceptedAccepted: status == 'dismissed' ? false : true,
     )
  }
}

---

• I’ve reviewed the contributor guide and applied the relevant portions to this PR.

Contribution guidelines:

• See our contributor guide for general expectations for PRs.
• Larger or significant changes should be discussed in an issue before creating a PR.
• Contributions to our repos should follow the Dart style guide and use dart format.
• Most changes should add an entry to the changelog and may need to rev the pubspec package version.
• Changes to packages require corresponding tests.

Note that many Dart repos have a weekly cadence for reviewing PRs - please allow for some latency before initial review feedback.

[bwilkerson]

I'm fine with these changes, but the description makes it sound like there might be other changes that you intended to include. No problem if that's not the case; just wanted to let you know in case you'd forgotten to git add a file.

[eliasyishak]

I'm fine with these changes, but the description makes it sound like there might be other changes that you intended to include. No problem if that's not the case; just wanted to let you know in case you'd forgotten to git add a file.

Ah thank you for for taking the initiative to review this already, but yes, there are going to be some more changes coming that I was going to run by you. Definitely will need another run through

[eliasyishak]

@bwilkerson sorry for the noise you must have got from this PR, but I am ready for a review. The first review was before most of the functionality was added

[eliasyishak]

@DanTup does this workflow outlined in the PR description seem feasible? No need to review the entire PR if you don't want to by the way, just wanted to confirm the analytics.fetchAvailableSurveys() and analytics.dismissSurvey(...) APIs

[DanTup]

  // How to handle when the survey gets snoozed
  // (ie. the user did not take action on the survey)
  //
  // This will prevent the survey from showing up again for minutes
  // in Survey.dismissForMinutes
  if (status == 'snoozed') {

I think this action needs to occur as soon as a survey is shown (because we need to suppress duplicates starting immediately), so it should probably be more of a "surveyShown" call (and just implied rather than an explicit request by the client).

If it doesn't occur immediately as the notification is being shown, it may result in duplicates if the user opens another IDE window, for example.

Eg.:

• Client asks package for surveys (and surveys in the snooze period are not returned)
• Client picks the first one to show
• Client shows the notification + tells the package it's showing it
• Package records that this survey is snoozed for a period
• If user clicks to complete or dismiss this survey, client tells package to permanently dismiss this survey

[eliasyishak]

Ah that's a great point, how does this sound. Instead of having analytics.dismissSurvey(...) which can either snooze or permanently dismiss the survey... we can instead have analytics.dismissSurvey(...) which will only be responsible for permanently dismissing a survey and introduce a new method analytics.snoozeSurvey(...) which should always be called after displaying a survey.

That way, the first window to go and retrieve a survey will also snooze it so it doesn't show up again if the user opens a new window within 2-3 seconds (or whatever the delay is for a popup in VS Code)?

// Recommended to take the first item in the list since
// there could be multiple surveys available
final survey = surveyList.first;

// pseudo-code to simulate "showing" the survey
display(survey);

// Immediately call the method to snooze the survey
analytics.snoozeSurvey(survey);  // <-- new method to be added

// pseudo-code to simulate the user interacting with it
final status = 'dismissed';

// How to handle a permanent dismissal of the survey
// (ie. the user clicked "No, skip survey"
//
// Ideally the user clicking dismiss would call a function/method
// to handle the below
if (status == 'dismissed') {
   analytics.dismissSurvey(
     survey: survey,
     permanently: true,
   )
}

// And if the user didn't interact with the survey, it will automatically
// observe its snooze period before getting called again

[DanTup]

and introduce a new method analytics.snoozeSurvey(...) which should always be called after displaying a survey.

This sounds good to me, although if you're collecting stats when surveys are shown within the package, perhaps calling it surveyShown() or similar would allow it to record that the survey was shown and snooze it in one step?

Perhaps the same is true for dismissSurvey - if it was two different methods (surveyAccepted and surveyDismissed), it could handle analytics for those cases?

(it's possible you're already handling these, I'm not sure whose responsibility collecting these stats would be)

[eliasyishak]

All great ideas, I'll implement this and push a new update. Thanks @DanTup !

[eliasyishak]

How does this look, the implementation of the two survey apis will send events for when they were snoozed/shown and when the user has interacted with them indicated by the status variable

final Survey survey = ...;

analytics.surveyShown(survey); // <-- this will automatically snooze the survey

.
.
.

// Some process returns the status indicating if the user accepted or rejected the survey
final bool status = true; // <-- this indicates they opened the survey

// The code below will fire when the status is returned
analytics.dismissSurvey(survey: survey, surveyAccepted: status);

[DanTup]

Sounds good to me :-)