Web SDK - Custom Survey Invitations

It’s possible to create custom survey invitations by connecting ForeSee’s JavaScript¬†SDK to your own unique HTML-based invitation that matches your company’s brand.

This feature is only available in client code versions 19.2.0 and up.

First, you’ll want to connect to our customInviteRequested event listener to let our code know that you’ll be providing your own invitation. Wrap this call in an acsReady() so that you’ll ensure that our API is ready at the time you execute this step:

acsReady(function() {
   FSR.customInvitationRequested.subscribe(function(inviteType, acceptHandler, declineHandler, abandonHandler) {
      // Display your HTML invitation here
   });
});

When the page loads, and the invitation criteria have been met, the callback you provide to customInvitationRequested will be invoked with four arguments:

  • inviteType (String) Tells you what type of invitation this is supposed to be. This will have been decided earlier on in the implementation process. Possible values include:
    • TRACKER – When the user accepts the invite, a tracker window will appear (desktop browsers only)
    • INSESSION – A survey will pop in a new window when the user accepts the invitation
    • SMS – You need to collect an SMS phone number so we can send an invitation later to do the survey
    • EMAIL – You need to collect an email address so we can email an invitation later on
    • SMSEMAIL – You can collect either an email¬†or an SMS phone number
  • acceptHandler (Function) Call this when the user accepts your invitation
  • declineHandler (Function) Call this when the user declines the invite
  • abandonHandler (Function) Call this when the user abandons your invite (if applicable)

Then, build your invitation and display it. The following example uses jQuery to create a mock invitation and bind to the accept button.

acsReady(function() {
   FSR.customInvitationRequested.subscribe(function(acceptHandler, declineHandler, abandonHandler) {
      var invite = $("<div><p>Do our survey?</p><p><button>Yes!</button></p></div>");
      invite.css({
         position: 'absolute',
         top: '1em',
         left: '1em',
         display: 'inline-block',
         padding: '2em',
         border: '3px solid black',
         backgroundColor: '#f0f0f0'
      });
      invite.find("button").click(function(e) {
         e.stopPropagation();
         e.preventDefault();
         acceptHandler();
      });
      $(document.body).append(invite);
   });
});

Screen Shot 2016-11-25 at 7.26.48 PMIt’s important that you call the accept handler in the same execution thread that is triggered by the mouse click or the touch event. This is to allow the tracker window to open, which under normal circumstances would be blocked by modern browser security settings.

Collecting SMS or Email Addresses

For SMS, EMAIL, and SMSEMAIL invitation types – which are normally only deployed for mobile devices – you need to collect some information in your invitation, and pass it to the acceptHandler like so:

invite.find("button.submit").click(function(e) {
   e.stopPropagation();
   e.preventDefault();
   var emailAddr = $("input[type=email]").first().val();
   acceptHandler(emailAddr);
});

The SDK will not perform validation on the email or SMS that you provide. You’ll be responsible for this before handing the value off to the SDK.

Other articles in this section:

  1. Frequently Asked Questions
  2. Testing
  3. Replay Masking
  4. Custom Survey Invitations (current article)
  5. Legacy Trigger Code (<18x)
  6. Mobile Invite
  7. The ForeSee Cookies