ForeSee Developer Portal

Everything you need to set up and optimize your ForeSee product. Home of developer documentation, implementation guides, and question/answer forums.

Blueprint

Build your own invitation

This article describes how you can build your own custom invitation. Some experience with JavaScript programming is required in order to build the invite.

Out of the Box customizations

For invite customization options that don't require building your own invite, refer to the guide on How To Personalize Your ForeSee Survey Invitation

Create your own invitation and connect to the ForeSee SDK

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:

fsReady(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 is 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.

fsReady(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);
   });
});

It'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.

Build your own invitation