Invitation Behavior - Customized Invitations

Built-in Invitation Configuration

There are a number of options that may be used to customize desktop and mobile invitations that come with the Web SDK. Currently these options can be enabled by an Implementation Engineer during the code configuration process. The article below summarizes the configuration options available in the 19.3.3 code.

Implementation Guide for Survey Invitation Controls

 

How to Create Your Own Survey Invite

Create your own invitation and connect to the ForeSee SDK

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, 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() to 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 appears (desktop browsers only).
    • INSESSION – A survey displays 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 to participate 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 does not perform validation on the email or SMS that you provide. You are responsible for this before handing the value off to the SDK.

Other articles in this section:

  1. Desktop
  2. Mobile
  3. Customized Invitations (current article)