Communicating with the Speakap Frontend

Introduction

Speakap Applications will typically want to communicate with the Speakap Frontend, for example to
get information about the logged in user, to open modal lightboxes, to show error messages or to
respond to events. For this purpose, we have a JavaScript library which we call the Frontend
Library. This library can be found in the Speakap-SDK GitHub repository:
https://github.com/SpeakapBV/Speakap-SDK

Setup

To setup the Frontend Library, you need to include the library itself and jQuery. In order for the
library to initialize itself and gain access to the Speakap Frontend, it also needs to know the
App ID of the application and the parameters from the signed request. This can be achieved by
including the following code in the head of the HTML page:

<script type="text/javascript">
    var Speakap = { appId: "YOUR_APP_ID", signedRequest: "SIGNED_REQUEST_PARAMS" };
</script>
<script type="text/javascript" src="js/jquery.min.js"></script>
<script type="text/javascript" src="js/speakap.js"></script>

Note that the libraries we provide for verifying the signed request
also provide a convenience method which generates the “SIGNED_REQUEST_PARAMS” string from the POST
parameters.

Properties

doHandshake

A promise that will be fulfilled when the handshake has completed. You can use this to make sure you don’t run any code
before the handshake has completed. This construction is typically always used whenever you want to communicate with the
Speakap frontend proxy.

<script type="text/javascript">
    Speakap.doHandshake.then(function() {

        // make calls to the Speakap API proxy...
        Speakap.getLoggedInUser().then(function(user) {
            console.log('Hello '+ user.fullName +'!');
        });
    })
</script>

Methods

Once the library is successfully loaded and authenticated with the Speakap Frontend, you can call
one of the following methods:

ajax(url, settings)

Sends a remote request to the API.

This method can be used as a replacement for $.ajax(), but with a few differences:

  • All requests are automatically signed using the access token of the host application,
    but the app’s permissions may be limited based on the App ID.
  • Error handlers will receive an error object (with code and message properties) as their
    first argument, instead of a jqXHR object.
  • The URL property is interpreted as a path under the Speakap API, limited in scope to
    the current network. Eg. use “/users/” to request
    https://api.speakap.nl/networks/:networkEID/users/”.
  • The only supported HTTP method is GET.

confirm(options)

Presents a confirmation lightbox to the user.

This method provides a convenient way to present a confirmation lightbox, similar to JavaScript’s
native confirm() method, with an API that is much easier than creating a custom lightbox.

Option Description
cancelLabel The label to display on the cancel button (default: localized “Cancel”).
confirmLabel The label to display on the confirm button (default: localized “OK”).
context Context in which to execute the promise callbacks.
text The text to display in the confirmation dialog. Only plain text is
supported, with the exception of <b> and <i> tags and newlines.
title The title to display on the confirmation dialog.

This method returns a jQuery Deferred promise that gets fulfilled when the lightbox is confirmed, or
failed when the lightbox is cancelled.

getLoggedInUser(options)

Retrieves the currently logged in user.

Option Description
context Context in which to execute the promise callbacks.

This method returns a jQuery Deferred promise that is resolved with the user object as first
argument when successful.

The returned user object only contains the EID, name, fullName and avatarThumbnailUrl
properties.

off(event, callback, context)

Stops listening to an event generated by the Speakap host application.

Argument Description
event Event that was being listened to.
callback Callback function that was executed when the event was fired.
context Optional context in which the listener was executed.

on(event, callback, context)

Starts listening to an event generated by the Speakap host application.

Argument Description
event Event to listen to.
callback Callback function to execute when the event is fired.
context Optional context in which to execute the listener.

The following events are currently supported:

resolveLightbox – Emitted in a lightbox when the lightbox is resolved. The lightbox is
expected to reply to this event with a result object containing two properties: status and data.
Status should be “success” or else the resolve action is considered to have failed, and the data
should be the data to be passed back to the caller that opened the lightbox.

saveSettings – Emitted in the “install-wizard” position when the user has requested to save
the settings. For more information, see:

openLightbox(options)

Presents a lightbox to the user.

The lightbox contains an iframe of which the content is provided by your application and
there are three different ways of loading this content, each with their respective advantages
and disadvantages. Depending on your requirements and use case, you should pick one of these:

  1. The lightbox content is loaded remotely from a predefined position defined in the
    application manifest. This method gives you the most freedom to do with the lightbox what
    you want, but its downsides are that you as application developer need to provide a remote
    endpoint that will load the lightbox contents and the extra remote requests will cause a
    delay between the moment the lightbox opens and the display of its contents.
  2. The lightbox content is provided statically through the content parameter. Because the
    content is available right away, there is no delay between the opening of the lightbox and
    the display of the contents. The downside is that by default, no scripts are allowed to be
    executed inside the iframe, thus limiting yourself to mostly static content.
  3. The final method is an extension of the second, but in this case scripts are allowed to be
    executed as well. Unfortunately, for security reasons, this method is currently not
    compatible with Internet Explorer.

Among the following options, “buttonPositioning”, “buttons”, “context”, “height”, “title”
and “width” are supported regardless of how the content is loaded. The “position” and
“appData” options are exclusive to the first mechanism of content loading, and the “content”,
“css” and “includeSpeakapCSS” options are used by the other two mechanisms. The options
“js” and “hasScripts” are exclusive to the third mechanism.

It is possible to supply options for both the first and the third mechanism in a single call
to openLightbox(). In this case, the third mechanism is used if the user’s browser supports
it, and the first mechanism is used as fallback.

Option Description
appData App data that should be POSTed with the signed request when loading
the lightbox content from a manifest position.
buttonPositioning String “top” or “bottom”, depending on whether the given
buttons should be displayed in the header or the footer.
Default is “top”.
buttons

Array of button objects for the buttons to show below the lightbox.
Each button object may have the following properties:

enabled – Boolean indicating whether the button is enabled. Default
is true.

label – String label of the button.

positioning – String “left” or “right”, depending on which side
the button should be displayed. Default is “right”.

primary – Boolean indicating whether the button is the primary
button. The primary button is styled in the call-to-action color
(typically green) and is selected when the user presses Ctrl+Enter.

type – String type of the button, used for identifying the button.
There are two types supported:
“close” – Closes the lightbox when clicked.
“resolve” – Resolves the lightbox when clicked.

content HTML content to display in the body of the iframe. If this option
is provided, the second or third mechanism for loading the content
is used, depending on the value of the hasScripts option.
context Context in which to execute the promise callbacks.
css Array of URLs to CSS resources that should be included by the iframe.
hasScripts If the content option is provided, this option has to be set to
true to enable the execution of scripts in the lightbox. It is
implicitly set to true if any JavaScript URLs are specified, but
has to be explicitly set to true if you specify inline event
handlers in your HTML content, for example. An important caveat
is that when this property is true (whether implicit or
explicit) the lightbox will not work in Internet Explorer,
unless you also a provide a position as fallback.
height Lightbox height in pixels. The minimum permitted height is 100
pixels, and the maximum permitted height is 540 pixels.
includeSpeakapCSS Boolean whether Speakap’s “base.css” and “branding.css”
should be included. Default is true.
js Array of URLs to JavaScript resources that should be loaded by the
iframe. Note that you need to include your own reference to this
speakap.js file if you want to be able to use this API from the iframe.
position Position from the application manifest to load in the iframe. If
this option is provided, the first mechanism for loading the
content is used. For the purpose of validation, the name of the
position should end with “-lightbox”.
title Title of the lightbox.
width Lightbox width in pixels. The minimum permitted width is 100
pixels, and the maximum permitted width is 740 pixels.

This method returns a jQuery Deferred promise that gets fulfilled when the lightbox is resolved, or
failed when the lightbox is closed otherwise.

When the lightbox is resolved, the promise callback receives a data parameter. If you have
used the second method of content loading, this data parameter is populated automatically
to contain key-value pairs for all the input elements inside the lightbox, where the key is
the name of the input element and the value is the value of the input. If you have used the
first or third method of content loading, this data parameter should be populated by the
scripts upon receiving the “resolveLightbox” event.

All URLs given for CSS and JavaScript resources have to be absolute URLs.

Within the iframe, this speakap.js file is available if you include it with the JavaScript
resources, giving you access to the global Speakap object from the iframe (including event
handlers defined on the lightbox). Specifically, the following methods can be used from a
lightbox context:

  • getLoggedInUser()
  • setButtonEnabled()
  • showError()
  • showNotice()

openUrl(url)

Opens a URL in a new window/tab. Subsequent calls to this method will open the method in the
same window or tab.

Because of sandbox restrictions, applications are not allowed to open links. This method still
allows opening of links, if only in a new window.

Argument Description
url The URL to open. Must be an absolute URL.

replyToEvent(event, data)

Sends a reply to an event generated by the Speakap host application.

Argument Description
event Event to reply to.
data Data to send back to the host application.

selectMembers(options)

Opens a lightbox for selecting network members.

Option Description
context Context in which to execute the promise callbacks.
description Description text informing the user what to do.
excludedMemberIds Array of EIDs of members which may not be selected.
By default, only the logged in user may not be selected.
selectedMemberIds Optional array of pre-selected member EIDs.
selectMultiple Boolean determining whether multiple members may be selected
(default: true).
submitButtonLabel Label of the select button.
title Lightbox title.

This method returns a jQuery Deferred promise that gets fulfilled when one or more members have been
selected, or failed when the action is canceled.

When one or more members have been selected, the promise callback receives a data parameter
containing a single property, depending on the value of the selectMultiple option:

Property Description
memberId EID of the selected member.
memberIds Array of EIDs of the selected members.

Note: In some situations when you use the selectedMemberIds option, there may be a short delay
between calling the method and the moment the lightbox opens, so it is advised to display some
loading indicator when you use this option.

selectRole(options)

Opens a lightbox for selecting a network role.

Option Description
context Context in which to execute the promise callbacks.
description Description text informing the user what to do.

This method returns a jQuery Deferred promise that gets fulfilled when a role is selected, or
failed when the action is canceled.

When a role is selected, the promise callback receives a data parameter containing two properties:

Property Description
key Key of the selected role. This can be an EID of a custom role or a
string identifier of a predefined role.
name Name of the role. This is the name of the role as given by the
administrator, or the localized name of a predefined role. Because the
name is locale-dependent, it is only intended for informing the user,
and should not be stored for any other purposes.

setButtonEnabled(type, enabled)

Toggles the enabled state of one of the lightbox’s buttons.

Argument Description
type Type of the button to enable or disable.
enabled True if the button should be enabled, false if it should be disabled.

This method is only available from the content of a lightbox iframe.

showError(message)

Shows an error message to the user.

Argument Description
message Localized message to show the user.

showNotice(message)

Shows a notice or confirmation message to the user.

Argument Description
message Localized message to show the user.