Kommunikation mit dem Speakap-Frontend

Einführung

Speakap-Anwendungen werden typischerweise mit dem Speakap-Frontend kommunizieren wollen, zum Beispiel um Informationen über den eingeloggten Nutzer zu erhalten, um modale Lightboxen zu öffnen, um Fehlermeldungen anzuzeigen oder um auf Ereignisse zu reagieren. Zu diesem Zweck haben wir eine JavaScript-Bibliothek, die wir die Frontend-Bibliothek nennen. Diese Bibliothek kann im Speakap-SDK GitHub Speicher gefunden werden:
https://github.com/SpeakapBV/Speakap-SDK

Einrichtung

Um die Frontend-Bibliothek einzurichten, müssen Sie die Bibliothek selbst und jQuery aufnehmen. Um die Bibliothek zu initialisieren und Zugang zum Speakap-Frontend zu erhalten, ist es erforderlich, die App-ID der Anwendung und die Parameter der bestätigten Anfrage zu kennen. Dies läßt sich erreichen, indem der folgende Code in den Kopf der HTML Seite aufgenommen wird:

<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>

Beachten Sie, dass die Bibliotheken, die wir anbieten, um die signed request zu prüfen, auch eine bequeme Methode bieten, welche die “SIGNED_REQUEST_PARAMS” Zeichenfolge aus den SENDEN-Parametern generiert.

Funktionen

doHandshake

Ein Versprechen, das erfüllt wird, wenn der Abschluss (Handschlag) stattgefunden hat. Diese Funktion können Sie nutzen, um sicher zu gehen, keinen Code auszuführen, bevor der Handschlag stattgefunden hat. Diese Einrichtung wird typischerweise immer genutzt, wenn Sie mit dem Speakap-Frontend-Proxy kommunizieren wollen.

<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>

Methoden

Wenn die Bibliothek erst einmal erfolgreich geladen und mit dem Speakap-Frontend authentifiziert wurde, können Sie eine der folgenden Methoden aufrufen:

ajax(url, settings)

Sendet eine Fernabfrage an den API.

Diese Methode kann als Ersatz für $.ajax()genutzt werden, aber mit ein paar Unterschieden:

  • Alle Anfragen werden automatisch durch Nutzen des  access token des Host-Programms bestätigt, aber die Anwendungsrechte können basierend auf der App ID eingeschränkt werden
  • Fehlerbehandlungsmethoden erhalten ein Fehlerobjekt (mit Code und Nachrichteneigenschaften) als ihr erster Parameter, anstelle eines jqXHR Objekts.
  • Die URL Eigenschaft wird als ein Pfad unter der Speakap-API ausgeführt, begrenzt im Umfang des aktuellen Netzwerks. Nutze “/users/” für die Anfrage “https://api.speakap.nl/networks/:networkEID/users/”.
  • Die einzige unterstützte HTTP Methode ist GET.

confirm(options)

Zeigt dem Nutzer eine Bestätigungs-Lightbox.

Diese Methode bietet einen bequemen Weg, um eine Bestätigungs-Lightbox dazustellen, ähnlich wie JavaScripts

Ursprüngliche confirm() Methode, mit einer API, die viel einfacher ist, als eine benutzerdefinierte Lightbox zu erstellen.

Option Beschreibung
cancelLabel Das Label für die Anzeige auf der Abbrechen Schaltfläche (Standard: lokalisiert “Abbrechen”).
confirmLabel Das Label für die Anzeige auf der Bestätigen Schaltfläche (Standard: lokalisiert “OK”).
context Kontext, in welchem die versprochenen Rückrufe ausgeführt werden.
text Der Text für die Anzeige des Bestätigungsdialogs. Es wird nur einfacher Text unterstützt, mit der Ausnahme von <b> und <i> Kürzeln und Zeilenumbrüche.
title Die Überschrift für die Anzeige der Bestätigungsdialog.

Diese Methode sendet eine jQuery verzögerte Vereinbarung zurück, die erledigt wird, wenn die Lightbox bestätigt wurde, oder fehlschlägt wenn die Lightbox abgebrochen wurde.

getLoggedInUser(options)

Ruft den gerade eingeloggten Nutzer auf.

Option Beschreibung
context Kontext, in dem die versprochenen Rückrufe ausgeführt werden.

Diese Methode sendet eine jQuery als verzögerte Vereinbarung zurück, die mit dem Nutzerobjekt als erstem Parameter gelöst wird, falls erfolgreich.

Das zurückgebrachte Nutzerobjekt beinhaltet die EID, name, fullName und avatarThumbnailUrl Eigenschaften.

off(event, callback, context)

Stoppt die Beobachtung eines vom Speakap Hostprogramm generierten Ereignisses.

Argument Beschreibung
event Ereignis, das beobachtet wurde.
callback Rückruffunktion, die ausgeführt wurde, als das Ereignis entlassen wurde.
context Alternativer Kontext, bei welchem der Beobachter ausgeführt wurde.

on(event, callback, context)

Startet die Beobachtung eines Ereignisses, dass vom Speakap-Hostprogramm generiert wurde.

Argument Beschreibung
event Ereignis, das verfolgt werden soll.
callback Rückruffunktion zum Ausführen, wenn das Ereignis entlassen wird.
context Alternativer Kontext, in welchem der Beobachter ausgeführt werden soll.

Die folgenden Ereignisse werden momentan unterstützt:

resolveLightbox – Ausgegeben in einer Lightbox, wenn die Lightbox aufgelöst wird. Die Lightbox wird vorausgesetzt, um auf dieses Ereignis mit einem Ergebnisobjekt zu antworten, das die beiden Merkmale: status und data beinhaltet.

Status sollte auf “success” stehen oder aber die Auflöseaktion wird als fehlgeschlagen gewertet, und die data sollten die Daten sein, die zurück an den Abfragenden weitergegeben werden, der die Lightbox geöffnet hat.

saveSettings – Ausgegeben in der “install-wizard”.Position wenn der Nutzer die Anfrage gestartet hat, um die Einstellungen zu speichern. Für mehr Informationen siehe auch:

openLightbox(options)

Zeigt dem Nutzer eine Lightbox an.

Die Lightbox beinhaltet ein iFrame, dessen Inhalt von Ihrer Anwendung zur Verfügung gestellt wird. Es gibt drei verschiedene Wege, diesen Inhalt zu laden, jeweils verbunden mit Vor- und Nachteilen. Abhängig von Ihren Anforderungen und dem Anwendungsfall sollten Sie einen von diesen wählen:

  1. Der Lightbox-Inhalt wird von einer externen vordefinierten Position im Anwendungs-manifest geladen. Diese Methode verleiht Ihnen die größte Ruhe, um mit der Lightbox zu machen, was Sie wollen, aber die Minuspunkte sind, dass Sie als Anwendungsentwickler einen externen Endpunkt bereitstellen müssen, der die Lightox-Inhalte lädt und die zusätzlichen Fernanfragen werden eine Verzögerung zwischen dem Öffnen der Lightbox und der Anzeige des Inhalts verursachen.
  2. Der Lightbox-Inhalt wird statisch durch die Inhaltsparameter bereitgestellt. Da der Inhalt sofort verfügbar ist, gibt es keine Verzögerung zwischen dem Öffnen der Lightbox und der Anzeige der Inhalte. Der Minuspunkt ist, das standardmäßig keine Skripte zugelassen sind, die innerhalb der iframe ausgeführt werden, dadurch beschränken Sie sich selbst auf überwiegend statische Inhalte.
  3. Die letzte Methode ist eine Erweiterung der zweiten, aber in diesem Fall wird auch die Ausführung von Skripten zugelassen. Leider ist diese Methode aus Sicherheitsgründen momentan nicht mit dem Internet Explorer kompatibel.

Die folgenden Optionen “buttonPositioning”, “buttons”, “context”, “height”, “title” und “width” werden unterstützt, ungeachtet auf welche Weise der Inhalt geladen wird. Die Optionen “position” und “appData” sind ausschließlich für die ersten Mechanismen des Ladens von Inhalten, und die Optionen “content”, “css” und “includeSpeakapCSS” werden von den anderen beiden Mechanismen genutzt. Die Optionen “js” und “hasScripts” dienen ausschließlich für den dritten Mechanismus.

Es ist möglich Optionen für beide, den ersten und den dritten Mechanismus, in einem einzelnen Aufruf von openLightbox() bereitzustellen. In diesem Fall wird der dritte Mechanismus genutzt, wenn der Browser des Nutzers ihn unterstützt, und der erste Mechanismus dient als Ausweichmöglichkeit.

Option Beschreibung
appData Anwendungsdaten, die mit dem signed request gesendet werden sollen, wenn der Lightbox-Inhalt von einer manifest position geladen wird.
buttonPositioning Zeichenfolge “top” oder “bottom”, abhängig davon, ob die vorhandenen Schaltflächen in der Kopf- oder Fußzeile angezeigt werden sollen.

Standard ist “top”.

buttons Reihe von Schaltflächenobjekten für die Schaltflächen, die unter der Lightbox angezeigt werden.

Jedes Schaltflächenobjekt kann die folgenden Eigenschaften besitzen:

enabled – Boolescher Wert, ob die Schaltfläche aktiviert ist. Standard ist richtig.

label – Zeichenbezeichnung der Schaltfläche.

positioning – Zeichenfolge “left” oder “right”, abhängig davon, auf welcher Seite die Schaltfläche angezeigt werden soll. Standard ist “right”.

primary – Boolescher Wert, ob die Schaltfläche die Hauptschaltfläche ist. Die Hauptschaltfläche wird in der Call-to-Action-Farbe (typischerweise grün) gestaltet und wird ausgewählt. wenn der Nutzer Ctrl+Enter drückt.

type – Art der Zeichenfolge der Schaltfläche, die zur Identifizierung der Schaltfläche genutzt wird.

Es werden zwei Arten unterstützt:

close” – Schließt die Lightbox nach dem Klicken.

resolve” – Löst die Lightbox nach dem Klicken auf.

content HTML Inhalt, der im Körper des iframe angezeigt wird. Falls diese Option vorgesehen wird, wird der zweite oder dritte Mechanismus zum Laden von Inhalt genutzt, abhängig vom Wert der hasScripts-Option.
context Zusammenhang, in dem die vereinbarten Rückrufe ausgeführt werden.
css Reihe der URLs zu CSS Ressourcen, die vom iframe umfasst werden sollen.
hasScripts Falls die Inhaltoption vorausgesetzt wird, muss diese Option auf richtig gesetzt werden, um das Ausführen der Skripte in der Lightbox zu aktivieren. Sie stillschweigend auf richtig gesetzt, falls JavaScript URLs festgelegt werden, muss aber explizit auf richtig gesetzt werden, falls Sie beispielsweise Ereignisbearbeiter in Ihrem HTML Inhalt festlegen. Wichtige Warnung: Wenn die Eigenschaft richtig gesetzt ist (ob stillschweigend oder explizit), wird die Lightbox im Internet Explorer nicht funktionieren, es sei denn Sie bieten eine position als Ausweichmöglichkeit an.
height Lightboxhöhe in Pixeln. Die minimal zulässige Höhe ist 100 Pixel und die maximal zulässige Höhe ist 540 Pixel.
includeSpeakapCSS Boolesche Variablen, beide von Speakaps “base.css” und “branding.css”, sollten enthalten sein. Standard ist richtig.
js Reihe von URLs zu JavaScript Ressourcen, die vom iframe geladen werden sollte. Beachten Sie, dass Sie Ihre eigene Referenz in diese speakap.js-Datei einbringen müssen, falls Sie diese API vom iframe aus nutzen möchten.
position Position des manifest der Anwendung, um im iframe geladen zu werden. Falls diese Option vorausgesetzt wird, wird der erste Mechanismus zum Laden des Inhalts genutzt. Der Name der Position sollte zum Zweck der Validierung mit “-lightbox” enden.
title Titel der Lightbox.
width Lightboxbreite in Pixeln. Die minimal zulässige Breite beträgt 100 Pixel und die maximal zulässige Breite beträgt 740 Pixel.

Diese Methode sendet eine jQuery als verzögerte Vereinbarung zurück, die erledigt wird wenn die Lightbox aufgelöst wird oder fehlschlägt, wenn die Lightbox auf andere Weise geschlossen wird.

Wenn die Lightbox aufgelöst wird, empfängt der vereinbarte Rückruf einen Datenparameter. Wenn Sie die zweite Methode zum Laden von Inhalten genutzt haben, ist dieser Datenparameter automatisch so bestückt, dass er Schlüssel-Wert-Paare für alle Eingabeelemente innerhalb der Lightbox enthält, wobei der Schlüssel der Name des Eingabeelementes ist und der Wert der eingegebene Wert ist. Falls Sie die erste oder dritte Methode zum Laden von Inhalten genutzt haben, sollte dieser Datenparameter mit den Skripten vom Empfang des “resolveLightbox”-Ereignisses bestückt sein.

Alle URLs für CSS und JavaScript Ressourcen müssen endgültige URLs sein.

Im iframe ist diese speakap.js-Datei verfügbar, wenn Sie es mit den JavaScript Ressourcen eingearbeitet haben, und gibt Ihnen Zugriff auf das globale Speakap-Objekt aus dem igframe (beinhaltet Ereignisbearbeiter, die in der Lightbox festgelegt definiert sind). Insbesondere können die folgenden Methoden aus einem Lightbox-Kontext genutzt werden:

getLoggedInUser()

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

openUrl(url)

Öffnet eine URL in einem neuen Fenster oder Tab. Nachfolgende Aufrufe dieser Methode werden die Methode im gleichen Fenster oder Tab öffnen.

Aufgrund der Sandbox-Einschränkungen sind Anwendungen nicht dazu berechtigt. Links zu öffnen. Diese Methode ermöglicht das Öffnen von Links dann nur in einem neuen Fenster.

Argument Beschreibung
url Die zu öffnende URL. Muss eine endgültige URL sein.

replyToEvent(event, data)

Sendet eine Antwort an ein vom Speakap-Hostprogramm generiertes Ereignis.

Argument Beschreibung
event Ereignis, auf das reagiert werden soll.
data Daten, die zurück an das Hostprogramm gesendet werden.

selectMembers(options)

Öffnet eine Lightbox zur Auswahl von Netzwerkmitgliedern.

Option Beschreibung
context Zusammenhang, in welchem die vereinbarten Rückrufe ausgeführt werden sollen.
description Beschreibungstext, um den Nutzer darüber zu informieren, was zu tun ist.
excludedMemberIds Reihe von EIDs von Mitgliedern, welche nicht ausgewählt werden kann.
Standardmäßig können nur die eingeloggten Nutzer nicht ausgewählt werden.
selectedMemberIds Optionale Reihe vorbestimmter Mitglieder EIDs.
selectMultiple Boolesche Bestimmung, ob diverse Mitglieder ausgewählt werden können. (Standard: Richtig).
submitButtonLabel Label der Auswahlschaltfläche.
title Lightboxtitel.

Diese Methode senden eine jQuery als verzögerte Vereinbarung zurück, die erledigt wird wenn ein oder mehrere Mitglieder ausgewählt wurden oder fehlschlägt, wenn die Aktion abgebrochen wird.

Wenn ein oder mehrere Mitglieder ausgewählt wurden, empfängt der vereinbarte Rückruf ein Datenparameter, das eine einzelne Eigenschaft beinhaltet, abhängig vom Wert der selectMultiple-Option:

Property Beschreibung
memberId EID der ausgewählten Mitglieder.
memberIds Reihe von EIDs der ausgewählten Mitglieder.

Beachte: In manchen Situationen, in denen Sie die selectedMemberIds-Option nutzen, kann es zu einer leichten Verzögerung zwischen dem Abrufen der Methode und dem Moment, wenn die Lightbox geöffnet wird, kommen, daher wird empfohlen, einen Indikator für den Ladevorgang anzuzeigen, wenn Sie diese Option nutzen wollen.

selectRole(options)

Öffnet eine Lightbox zur Auswahl einer Netzwerkrolle.

Option Beschreibung
context Zusammenhang, in dem vereinbarte Rückrufe ausgeführt werden sollen.
description Beschreibungstext, der den Nutzer darüber informiert, was zu tun ist.

Diese Methode sendet eine jQuery verzögerte Vereinbarung zurück, die erledigt wird, wenn eine Rolle ausgewählt wurde oder fehlschlägt, wenn die Aktion abgebrochen wird.

Wenn eine Rolle ausgewählt wurde, empfängt der vereinbarte Rückruf ein Datenparameter mit zwei enthaltenen Eigenschaften:

Property Beschreibung
key Schlüssel der ausgewählten Rolle. Das kann eine EID einer benutzerdefinierten Rolle oder die Kennung einer Zeichenfolge einer vordefinierten Rolle sein.
name Name der Rolle. Dies ist der Name der Rolle, der durch den Administrator vergeben wurde, oder der ermittelte Name einer vordefinierten Rolle. Da der Name ortsabhängig ist, ist er nur als Information für den Nutzer vorgesehen und sollte nicht für andere Zwecke gespeichert werden.

setButtonEnabled(type, enabled)

Schaltet den Aktivierungsstatus einer der Lightbox-Schaltflächen um.

Argument Beschreibung
type Art der Schaltfläche zum Aktivieren oder Deaktivieren.
enabled Richtig, wenn die Schaltfläche aktiviert werden soll, falsch, wenn sie deaktiviert werden soll.

Diese Methode ist nur aus dem Inhalt eines Lightbox-iframe verfügbar.

showError(message)

Zeigt dem Nutzer eine Fehlermeldung.

Argument Beschreibung
message Bestimmte Meldung, die dem Nutzer gezeigt wird.

showNotice(message)

Zeigt dem Nutzer einen Hinweis oder Bestätigungsmeldung.

Argument Beschreibung
message Bestimmte Meldung, die dem Nutzer gezeigt wird.