faviconDeveloper    API    Embedding

Suomeksi

Survey Embedding

Embed zeffi surveys into your webpage as a part of the page via iframe, or as a popup survey. Communicate with your surveys using our easy client API.

 

Make sure your survey is in Published state. The embeddings are disabled if the survey is in Unpublished or Offline state. 

Embedding via iframe

You can embed the survey via iframe using the following sample code.

<iframe src="https://survey.zef.fi/KEY/" width="100%" height="640px" hspace="0" vspace="0" scrolling="no" frameborder="0" marginwidth="0" marginheight="0" style="min-width: 320px; max-width: 960px" onmousewheel=""></iframe>
Make sure to replace the `KEY` with your web embed key that you get when you create a web embed
art-embed

Popup via JavaScript

To create a popup survey, put the following script inside your page header tag.

<script src="https://zef.fi/s/zeffi.js?key=KEY1,KEY2,KEY3" async defer></script>
Make sure to replace the `KEY*` with your survey's popup key that is generated when you create a new popup. You only need as many keys as the number of surveys you wish to add as popups.
Popup functions
zeffi.openPopup()

Opens the survey popup. In case of multiple keys, the first survey is opened.

zeffi.openPopup(key?: string, startConfig?: SurveyStartConfig)

Opens a specific survey popup, identified by the KEY. There can only be one survey opened at a time, this closes any other survey if currently open.

zeffi.closePopup()

Closes the currently open popup.

zeffi.togglePopup()

Toggles the open / close state of the popup. In case of multiple keys, the first survey is opened.

zeffi.togglePopup(key?: string, startConfig?: SurveyStartConfig)

Toggles the open / close state of the popup. When opening, the specific survey is opened identified by the KEY.

zeffi.showBubble()

Shows the clickable bubble. In case of multiple keys, clicking the bubble opens the first survey.

zeffi.showBubble(KEY)

Shows the clickable bubble. Clicking the bubble opens the specific survey identified by the KEY.

zeffi.hideBubble()

Hides the clickable bubble if visible.

Note: Without bubble the user cannot open the popup, and it needs to be opened via code.

 

Abstract models
interface SurveyStartConfig {
  // this will restart the survey with a new answerer instance
  restart?: boolean;
  // language code to start the survey with (eg. 'fi')
  language?: string;
  // start in accessibility mode
  accessibilityMode?: boolean;
  // zeffi contact identifier
  zefId?: string
  // background information to attach to the answerer session
  respondentFields?: Record<string, string>;
}
art-popup

Survey communication

Make your embed or popup talk with your website by listening to events.

Note: Make sure to specify an origin in Zeffi, otherwise no event will be sent. You can find this under the advanced settings of your embed or popup.

The wildcard (*) is allowed, but strongly discouraged.

Read more here about the proper usage.


window.addEventListener('message', onMessageReceived);

function onMessageReceived(message) {
  if (message.origin === 'https://survey.zef.fi') {
    // you have received a message from the survey
    // use message.data.type to get the message type
    // use message.data.data to get the message payload
  }
}


Example code to listen for an event

Abstract models
interface SurveyEvent {
  type: SurveyEventType;
  data: SurveyEventData;
}

The data property on all events sent from the survey will have the SurveyEvent structure.

interface SurveyEventData {
  team: string;
  survey: string;
  linkKey: string;
  answererId: string;
  timestamp: number;
}

Base data sent with every event.

enum SurveyEventType {
  Start = 'start',
  Answer = 'answer',
  Complete = 'complete',
  Restart = 'restart',
  Outcome = 'outcome'
}

The event type, set on the SurveyEvent.

Possible events
start
interface SurveyStartEventData extends SurveyEventData {}

Will be emitted when a survey is started.

answer
interface SurveyAnswerEventData extends SurveyEventData {
  question: QuestionData;
  answer: string;
  progress: number;
  answerType: string;
}

Will be emitted when an answer is given.

complete
interface SurveyCompleteEventData extends SurveyEventData {
  progress: number;
}

Will be emitted when a survey is completed.

outcome
interface SurveyOutcomeEventData extends SurveyEventData {
  outcomes: SurveyOutcomeData[];
}

interface SurveyOutcomeData {
  score: number;
  outcome: OutcomeData;
}

Will be emitted when a survey outcome changes. This will be fired throughout the answering of the survey.

restart
PlayerRestartEventData extends SurveyEventData {}

Will be emitted when a survey is restarted.