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 and 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 that was executed when the event was fired. |
| context | Optional context in which the listener was executed. |
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:
openAppLink(appData)
Opens the application in Speakap, optionally passing in appData.
This only works if the application has defined an entry for the “main” position and is intended for widget positions to link to the main position.
| Argument | Description |
|---|---|
| appData | Optional appData to pass. This data can be read by the opened application. |
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:
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.
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.
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. |