ForeSee Developer Portal

Everything you need to configure and optimize your ForeSee products. Home of developer documentation, implementation guides, and release notes.

Blueprint

Build your own invitation

This article describes how you can build your own custom invitation. First, you need to build an invitation in HTML. Then, using JavaScript, you connect the invitation to the ForeSee® SDK.

❗️

Out of the Box customizations

The Build Your Own Invitation approach described in this article requires JavaScript and HTML programming knowledge. For invitation customization options that can be configured by ForeSee, 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 the ForeSee code know that you are providing your own invitation. Wrap this call in fsReady() to ensure that the ForeSee® 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 site page loads and the invitation criteria have been met, the callback you provide to customInvitationRequested is invoked with these arguments:

  • inviteType (String) Tells you what type of invitation this is supposed to be. This has already been decided earlier on in the implementation process. Possible values include:
  • TRACKER - When the user accepts the invitation, a Tracker window appears (desktop browsers only).
  • INSESSION - A survey displays in a new window when the user accepts the invitation.
  • SMS - You must collect an SMS phone number to send an invitation to.
  • EMAIL - You must collect an email address to send an invitation to later on.
  • SMSEMAIL - You can collect either an email or an SMS phone number.
  • acceptHandler (Function) Call this when the visitor accepts your invitation.
  • declineHandler (Function) Call this when the visitor declines the invitation.
  • abandonHandler (Function) Call this when the visitor abandons your invitation (if applicable).

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

fsReady(function() {
   FSR.customInvitationRequested.subscribe(function(inviteType, 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.

Updated about a year ago

Build your own invitation


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.