Erstellen einer Bolt-App

Lernziele 

Nachdem Sie diese Lektion abgeschlossen haben, sind Sie in der Lage, die folgenden Aufgaben auszuführen:

• Ermöglichen, dass Ihre Bolt-App auf Slack zugreift
• Erläutern von Listener-Funktionen
• Hinzufügen von Ereignis-Listenern zu Ihrer App
• Hinzufügen von Interaktivität zu Ihrer App

Neuzusammenführen der App-Vorlage von Bolt for JavaScript in Glitch

Da die App konfiguriert und installiert ist, können wir nun eine neue Bolt-App mit den Anmeldedaten Ihrer App einrichten.

Um die Entwicklung zu erleichtern, verwenden wir in diesem Modul Glitch, ein Tool, das das Erstellen und Hosten von Apps vereinfacht. Ein kostenloser Glitch-Account ist prima für die Entwicklungsarbeit, doch wenn Ihre App inaktiv ist, läuft Ihr Server nicht weiter. Sie müssen Glitch also beim Entwickeln und Testen Ihrer App in Ihrem Browser geöffnet lassen.

Wenn Ihre App bereit für den Einsatz in der Produktion ist, sollten Sie sie dann entweder anderswo hosten oder ein Upgrade Ihres Glitch-Accounts durchführen. Eine vollständige Liste empfohlener Hosting-Anbieter finden Sie auf der API-Website.

Wenn Sie Ihre App lieber lokal ausführen möchten, können Sie ein Tool wie ngrok verwenden. Ein Beispiel für die Verwendung von ngrok finden Sie in der Dokumentation im Handbuch mit ersten Schritten.

1. Öffnen Sie Ihre Glitch-Umgebung.
2. Klicken Sie auf diesen Link, um das Bolt-Startprojekt neu zusammenzuführen (oder zu duplizieren).
3. Nach der Neuzusammenführung wird das Projekt in Ihrer Projektliste aufgeführt. In unserem Beispiel heißt das Projekt "actually-triangular-pigeon".
4. Klicken Sie auf Ihr Projekt, um es zu laden.
5. Klicken Sie dann auf app.js.

In der Datei app.js sehen Sie, dass das Paket @slack/bolt importiert und instanziiert wird. Darunter wird der App-Server eingerichtet und ausgeführt, sodass er eingehende Ereignisse von Slack empfangen kann.

Später fügen wir hier noch mehr hinzu. Zuerst fügen Sie die Anmeldedaten aus Ihrer Slack-App-Konfiguration hinzu. Denken Sie daran, Glitch während dieses Prozesses geöffnet zu lassen. 

Kehren Sie zu Ihrer App-Seite auf der "Slack API"-Website zurück.

Hinzufügen von App-Anmeldeinformationen

Rufen Sie Ihren geheimen Unterzeichnungsschlüssel und Ihr OAuth-Zugriffs-Token für Bot-Benutzer ab. 

1. Wechseln Sie zu Ihrer Slack App-Konfigurationsseite auf der ""Slack API"-Website.
2. Klicken Sie in der Randleiste auf Basic Information (Grundlegende Informationen).
3. Blättern Sie nach unten zum Abschnitt "Anmeldeinformationen für App".
4. Kopieren Sie Ihren geheimen Unterzeichnungsschlüssel und speichern Sie ihn für den nächsten Schritt in Ihrem Texteditor.
5. Klicken Sie in der Randleiste auf OAuth & Permissions (OAuth & Berechtigungen).
6. Klicken Sie auf Copy (Kopieren), um Ihr OAuth-Zugriffs-Token für Bot-Benutzer zu kopieren und für den nächsten Schritt zu speichern.

Wenn Sie Geheimnis und Token gespeichert haben, wechseln Sie wieder zu Glitch.

1. Navigieren Sie in Ihrem Glitch-Projekt zur .env-Datei in der linken Randleiste.
2. Fügen Sie Ihr OAuth-Zugriffs-Token für Bot-Benutzer in das Feld "Variable Value (Variablenwert)" direkt neben SLACK_BOT_TOKEN (1) ein.
3. Fügen Sie Ihren geheimem Unterzeichnungsschlüssel in das Feld "Variable Value (Variablenwert)" direkt neben SLACK_SIGNING_SECRET (2) ein. Die App verwendet den geheimen Unterzeichnungsschlüssel, um zu prüfen, ob die eingehenden Anfragen von Slack stammen. Bolt führt die Verifikation automatisch durch, wenn der geheime Unterzeichnungsschlüssel in den App-Konstruktor übergeben wird.

Wenn Sie unten im Glitch-Dateinavigator auf Logs klicken, sollten Sie die Nachricht sehen, dass Ihre Bolt-App ausgeführt wird!

Kennenlernen von Listener-Funktionen

Slack-Apps empfangen und beantworten in der Regel eine bis viele Anfragen von Slack. Für jede Art von eingehender Anfrage von Slack gibt es eine zugehörige Listener-Funktion, die die Anfrage handelt und beantwortet. 

Dies ist eine Teilmenge der Listener-Funktionen, an die Bolt-Apps Anfragen übergeben können.

Die vollständige Liste finden Sie in der Bolt-Referenzdokumentation. Jetzt gehen wir daran, Ihre App entsprechend zu konfigurieren, damit sie auf Ereignisse, Interaktionen und Interaktivitäten überwacht und antwortet! 

Abonnieren von Ereignissen

Um auf Ereignisse der Ereignis-API zu überwachen, muss Ihre App Ereignis-Abos aktivieren.

1. Wechseln Sie nun zu Ihrer Slack-App-Seite auf der Website "Slack API", falls Sie sich nicht bereits dort befinden.
2. Klicken Sie in der Randleiste auf Ereignis-Abos.
3. "Ereignis-Abos" sollte automatisch aktiviert werden. Sie können die Funktion aber bei Bedarf auch einschalten.
4. Es wird ein Eingabefeld für einen Anfrage-URL angezeigt. An den Anfrage-URL werden HTTP-Anfragen für Ereignisse gesendet, die Ihre App abonniert hat. Wenn Sie Ihre App aus der Vorlage erstellen, lautet Ihr Anfrage-URL momentan https://project-name.glitch.me/slack/events.
5. Geben Sie statt project-name den Namen Ihres eigenen Glitch-Projekts ein.
   1. Klicken Sie erst auf Settings (Einstellungen) und dann auf Go to project page (Zur Projektseite wechseln). Der URL hinter "Live site" enthält Ihren Projektnamen. Dazu zählt alles, was nach https:// und vor .glitch.me steht.
6. Wechseln Sie zurück zur Seite "Ereignis-Abos" der Slack API-Website und geben Sie den Anfrage-URL ein. Dieser sollte so aussehen: https://actually-triangular-pigeon.glitch.me/slack/events
   Bolt for JavaScript überwacht standardmäßig auf alle über /slack/events eingehenden Anfragen, weshalb dies am Ende des Anfrage-URL angehängt wird.
7. Klicken Sie zum Speichern Ihrer Arbeit auf Save Changes (Änderungen speichern).
8. Klicken Sie anschließend auf Subscribe to bot events (Bot-Ereignisse abonnieren), um den Abschnitt zu öffnen. Hier wird message.channels unter "Ereignis-Name" angezeigt. Dieses Ereignis überwacht auf alle in offenen Channels gepostete Nachrichten, in denen sich Ihre App befindet. Nachdem der Anfrage-URL jetzt aktiviert ist, sollte Ihre App beginnen, diese Ereignisse zu empfangen.

Hinzufügen eines Ereignis-Listeners

Ereignis-Abos verwenden den Listener event(), für den Sie in der Bolt-Dokumentation Beispiele finden. Wir verwenden hier vorerst den Listener message(), um auf Nachrichten zu überwachen und zu antworten.

1. Wechseln Sie zu Ihrem Glitch-Projekt.
2. Fügen Sie in Ihre Datei app.js den folgenden Code unter // Space for your code ein:

app.message('hello', async ({ message, say }) => {
    await say(`Hey there <@${message.user}>`);
});

Glitch speichert Ihre Arbeit automatisch.

Hinter den Kulissen ist die Verwendung des Listeners message() dasselbe wie app.event(“message”, fn), mit Ausnahme des zusätzlichen Parameters say(), der an die Listener-Funktion übergeben wird. Der Parameter say() gibt den Antwort-URL des Ereignisses an, der im Gegensatz zum Aufruf von chat.postMessage() keine zusätzlichen Umfänge benötigt, um auf Ereignisse vom Typ message zu antworten.

Solange Glitch in einem separaten Browserfenster ausgeführt wird, sollte Ihre App automatisch neu gestartet werden. Sie können innerhalb des Channels, zu dem Ihre App hinzugefügt wurde, jetzt die Nachricht "hello" senden. Die App sollte antworten.

Dieses einfache Beispiel gibt Ihnen einen Ausgangspunkt, an dem Sie mit der Anpassung Ihrer App für Ihren Anwendungsfall ansetzen können. Probieren wir nun einen etwas interaktiveren Austausch, indem wir nicht nur einfachen Text senden, sondern ein Button-Element.

Einrichten von Interaktivität

Damit Sie Funktionen wie Schaltflächen, ausgewählte Menüs, Datumsauswahlen, modale Dialogfenster und Tastaturkürzel verwenden können, müssen Sie Interaktivität aktivieren. Ähnlich wie bei Ereignis-Abos müssen Sie einen Anfrage-URL angeben, damit Slack die Aktionsanfrage senden kann (wie etwa ein Benutzer hat auf Ihre Schaltfläche geklickt).

1. Wechseln Sie zu Ihrer Slack App-Konfigurationsseite und klicken Sie in der Randleiste auf Interactivity & Shortcuts (Interaktivität & Tastaturkürzel).
2. Stellen Sie den Schalter für Interaktivität auf On (Ein). Wie Sie sehen, gibt es ein weiteres Feld "Anfrage-URL".
3. Standardmäßig wird Bolt so konfiguriert, dass es für interaktive Komponenten denselben Endpunkt wie für Ereignisse verwendet. Geben Sie hier also denselben Anfrage-URL wie oben ein.
4. Nun klicken Sie in der rechten unteren Ecke der Seite auf Save Changes (Änderungen speichern), und das war's auch schon! Ihre App ist jetzt für die Verarbeitung von Interaktivität eingerichtet.

Hinzufügen eines action-Listeners zur Beantwortung einer Nachricht

Zum Überwachen auf Interaktivität dient der Listener action(). Bevor Sie den Listener action() einrichten, ändern Sie den Listener message() so ab, dass er ein Button-Element sendet.

1. Wechseln Sie zu Ihrem Glitch-Projekt.
2. Erstellen Sie in der Datei app.js den vorherigen Codeauszug, um einen neuen Abschnitt einzufügen.

// Message listener function called for messages containing "hello"
app.message('hello', async ({ message, say }) => {
    await say({
        "blocks": [
            {
                "type": "section",
                "text": {
                    "type": "mrkdwn",
                    "text": `👋 Hey there <@${message.user}>`
                },
                "accessory": {
                    "type": "button",
                    "text": {
                        "type": "plain_text",
                        "text": "Click Me",
                        "emoji": true
                    },
                    "action_id": "click_me_button"
                }
            }
        ]
    });
});

Der Wert von say() ist jetzt ein Objekt, das ein Array von Blöcken enthält. Blöcke sind Komponenten einer Slack-Nachricht und können Text, Bilder oder Datumsauswahlen enthalten. In diesem Fall handelt es sich um einen Block vom Typ "section" mit einem "accessory"-Objekt vom Typ "button".

Zum Entwerfen von Nachrichten und anderen Block-Kit-Oberflächen können Sie das Tool Block-Kit-Builder verwenden. Block-Kit-Builder bietet eine Reihe integrierter Vorlagen für gängige Anwendungsfälle und eine praktische grafische Drag & Drop-Benutzeroberfläche mit der entsprechenden JSON-Payload auf der rechten Seite.

Da Block-Kit Benachrichtigungen standardmäßig nicht mit Daten füllen oder suchen kann, sollte das Feld text verwendet werden, um Ihre Nachrichten besser zugänglich zu machen. Weitere Informationen über das Feld "text" finden Sie auf der Referenzseite chat.postMessage.

Im "accessory"-Objekt vom Typ "button" befindet sich eine action_id. Diese fungiert als eindeutiger Bezeichner, den Sie an Ihre Listener-Funktion übergeben können, damit diese nur auf interaktive Ereignisse überwacht, die zu diesem Blockelement gehören.

Starten Sie Ihre App neu und senden Sie dann eine weitere Nachricht mit dem Inhalt "hello", auf die Ihre App mit einer Nachricht antworten wird, die das Button-Element, also eine Schaltfläche, enthält. Wenn Sie auf die Schaltfläche klicken, geschieht allerdings (noch!) nichts.

Hinzufügen eines action-Listeners zur Beantwortung einer Schaltflächeninteraktion

Wir fügen nun einen action()-Listener hinzu, um mit einer Nachverfolgungsnachricht darauf zu reagieren, dass auf die Schaltfläche geklickt wurde.

1. Wechseln Sie wieder zu Ihrem Glitch-Projekt.
2. Fügen Sie den folgenden action-Listener zu app.js hinzu.

// Action listener function called when an interactive component with action_id of “click_me_button” is triggered
app.action('click_me_button', async ({ ack, body, client, say }) => {
    // Acknowledge action request before anything else
    await ack();
    let channelID = body.channel.id
    let userID = body.user.id
    // Respond to action with an ephemeral message
    await client.chat.postEphemeral({
    channel: channelID,
    user: userID,
    text: `<@${userID}> clicked the button! 🎉 `
  });
});

Beachten Sie, dass ack() innerhalb der Listener-Funktion aufgerufen wird. Mit ack() wird bestätigt, dass Ihre App das Ereignis von Slack empfangen hat. Nach dem Neustart Ihrer App können Sie erneut auf die Schaltfläche klicken, und Ihre App wird mit der neuen Nachricht antworten.

Wenn Sie Schwierigkeiten mit der Ausführung der App haben, sehen Sie sich den fertigen Code in der Datei actions.js im Ordner "examples" Ihres Projekts an. 

Was kommt als Nächstes?

Sie haben jetzt Ihre erste Bolt for JavaScript-App erstellt, die Bolt-Kernkonzepte nutzt, um auf verschiedene, von Slack eingehende Ereignisse zu überwachen und zu antworten! 

Mit diesen Grundlagen können Sie sich jetzt weitere Bolt- und Plattformfunktionen ansehen. Sie könnten beispielsweise folgende Pfade einschlagen:

• Durchgehen des Ordners "examples" in Ihrem Glitch-Projekt. Es gibt ein paar Dateien mit unterschiedlichen Codebeispielen, die Sie kopieren und in Ihr Projekt einfügen können.
• Lesen der Dokumentation zu Bolt for JavaScript, um mehr über anspruchsvollere Funktionen zu erfahren und sich Codeauszüge anzusehen, die die Möglichkeiten veranschaulichen
• Ausbauen des Designs Ihrer App mit dem Block-Kit-Builder

Erkunden Sie weitere Oberflächen, auf die Ihre App Zugriff hat, wie etwa die Registerkarte "Home" sowie modale Popup-Fenster.