🕸️Web-Komponente

Die Integration Ihres Bots in Ihre Website verbessert das Nutzerengagement und bietet direkte Unterstützung auf Ihrer Plattform. Dieser Prozess ist unkompliziert und beinhaltet das Einbetten eines kleinen Code-Snippets.

Web-Komponenten Parameter

Vor der Integration der Web-Komponente müssen Sie folgende Parameter verstehen:

ClientId, OrgId und SecretKey: Diese erhalten Sie vom Blockbrain-Team.

UserUid: Dieser eindeutige String repräsentiert jeden Benutzer und kann dynamisch im HTML gesetzt werden. Es kann sich um einen beliebigen Identifikator handeln, wie E-Mail, Benutzername, Telefonnummer oder Benutzer-ID.

Hinweis: Dieses Feld ist optional. Wenn es leer gelassen wird, speichert das System keinen Benutzerverlauf. Jeder Besuch wird als neue Sitzung behandelt, ohne gespeicherte Daten aus früheren Besuchen.

WebComponent uID: Die WebComponent UID ist eine eindeutige Kennung, die individuell im Admin-Dashboard Ihrer Instanz eingestellt werden kann.

Web-Komponente erstellen

Folgen Sie diesen einfachen Schritten zur Erstellung einer Web-Komponente in Blockbrain:

1. Zugriff auf die Blockbrain-Plattform

   • Öffnen Sie Ihren Webbrowser und gehen Sie zu Ihrer Blockbrain-Tenant-Domain (z.B. run.theblockbrain.ai).

2. Mit Admin-Anmeldedaten einloggen

   • Geben Sie Ihren Admin-Benutzernamen und Passwort ein, um auf die Plattform zuzugreifen.

3. Zum Admin-Tab navigieren

   • Klicken Sie auf die Admin-Schaltfläche in der oberen Navigationsleiste.

   • 

4. Den WebComponent-Bereich öffnen

   • Suchen und klicken Sie in der linken Seitenleiste auf WebComponent.

   • 

5. Eine neue WebComponent-Bot-Zuordnung erstellen

   • Klicken Sie auf die Schaltfläche "Neue Bot-Zuordnung erstellen" oben rechts.

   • 

6. Erforderliche Informationen eingeben

   • Im Modal "Neue WebComponent-Bot-Zuordnung erstellen", das erscheint:

     • Wählen Sie einen Bot aus der Bot-Name-Dropdown-Liste.

     • Geben Sie die WebComponent UID ein.

     • 

7. Zuordnung speichern

   • Klicken Sie auf die Schaltfläche "Speichern", um die WebComponent-ID-Erstellung abzuschließen.

Integration der Web-Komponente

Die Komponente kann überall integriert werden, wo HTML-Tags unterstützt werden. Zusätzlich bieten wir ein SharePoint Web Part-Paket an, das eine nahtlose Integration innerhalb des Microsoft-Ökosystems ermöglicht, einschließlich SharePoint und Teams.

Die vom Blockbrain-Team erhaltenen Parameter (ClientID, OrgID & SecretKey) und Ihre WebComponents UID sind alle Parameter, die für den HTML-Tag erforderlich sind:

<blockbrain-main  
clientId="clientId"  
secretKey="secretKey"  
orgId="orgId"  
uid="uid"  
userUid="userUid">  
</blockbrain-main>  

Guideline für Web-Komponente OAuth-Integration

Diese Anleitung bietet Anweisungen zur Integration der Web-Komponente im privaten Modus (mit OAuth-Authentifizierung) und im öffentlichen Modus (ohne Authentifizierung). Wählen Sie den passenden Modus basierend auf Ihren Anforderungen.

Hinzufügen des erforderlichen Scripts

Um die Chat-Element-Komponente in Ihre Website einzubinden, folgen Sie diesen Schritten:

1. Teilen Sie uns den Ursprung (Origin) der Seite mit, in die Sie integrieren möchten

2. Fügen Sie den folgenden Script-Tag in Ihre HTML-Datei ein:

<script   
  type="module"  
  src="https://assets.theblockbrain.io/scripts/blocky-chat/blocky-chat.bundle.js"  
  async>  
</script>  

1. Fügen Sie den <blockbrain-main>-Tag dort ein, wo Sie die Chat-Komponente platzieren möchten:

<blockbrain-main
    clientId="clientId"
    secretKey="secretKey"
    orgId="orgId"
    uid="uid"
    userUid="userUid">  
</blockbrain-main>  

1. Ersetzen Sie clientId und secretKey durch Ihre tatsächliche Client-ID und Ihren geheimen Schlüssel, die uid durch die Kontonummer / Maschinen-UID und userUid durch eine eindeutige Benutzer-ID, falls Sie eine haben, die Sie senden können - andernfalls entfernen Sie sie einfach.

Public vs. Private Modus

• Privater Modus: Erfordert Benutzerauthentifizierung. Benutzer müssen über ein Blockbrain-Konto verfügen, um auf die Webkomponente zuzugreifen, und alle Daten werden basierend auf ihrem Konto gespeichert.

• Öffentlicher Modus: Keine Authentifizierung erforderlich. Jeder kann die Komponente nutzen, und Benutzer werden durch das Feld userId unterschieden. Dieser Modus erfordert die Angabe einer clientId und eines secret.

Private Mode Integration (Authentifizierte Nutzung)

Für eine sichere und authentifizierte Nutzung konfigurieren Sie die Webkomponente im privaten Modus mit dem issuer-Attribut.

Erforderliche Attribute:

issuer	URL Ihrer Blockbrain-Domain (Knowledge Bots Frontend)	Von der Client-Seite bereitgestellt	Erforderlich
uid	Eindeutiger Identifikator für die Bot-Instanz oder Anwendung	Vom Kunden zugewiesen	Erforderlich
userUid	Eindeutiger Identifikator für den Benutzer	Von der Client-Seite bereitgestellt	Optional
orgId	Für Ihre Instanz bereitgestellte Organisations-ID	Von Blockbrain bereitgestellt	Erforderlich

Beispiel:

<blockbrain-main
    orgId="ihre-org-id"
    issuer="https://ihre-blockbrain-domain.com"
    uid="ihre-uid"
    userUid="optionale-benutzer-id">
</blockbrain-main>

Public Mode Integration (Nicht-authentifizierte Nutzung)

Für Szenarien, in denen keine Authentifizierung erforderlich ist, konfigurieren Sie die Webkomponente im öffentlichen Modus mit dem clientSecret-Attribut.

Erforderliche Attribute:

orgId	Für Ihre Instanz bereitgestellte Organisations-ID	Von Blockbrain bereitgestellt	Erforderlich
clientSecret	Ein Client-Geheimnis zur Aktivierung des öffentlichen Modus	Von Blockbrain bereitgestellt	Erforderlich
uid	Eindeutiger Identifikator für die Bot-Instanz oder Anwendung	Vom Kunden zugewiesen	Erforderlich
userUid	Eindeutiger Identifikator für den Benutzer	Vom Kunden zugewiesen	Optional

Beispiel:

<blockbrain-main
    orgId="ihre-org-id"
    clientSecret="ihr-client-geheimnis"
    uid="ihre-uid"
    userUid="optionale-benutzer-id">
</blockbrain-main>

Hinweise

• Privater Modus: Empfohlen für Umgebungen, die Benutzerauthentifizierung erfordern. Stellen Sie sicher, dass der issuer korrekt konfiguriert ist.

• Öffentlicher Modus: Nur in Szenarien verwenden, in denen keine Authentifizierung erforderlich ist oder Zugriffskontrollen keine Rolle spielen.

• Sicherheit: Vermeiden Sie es, sensible Daten im Frontend offenzulegen. Verwenden Sie den öffentlichen Modus mit Vorsicht.

Damit ist die Einrichtung für Ihren gewählten Integrationsmodus abgeschlossen.

Anpassung

Erweitern Sie das <blockbrain-main>-Tag und passen Sie es durch verschiedene Attribute an Ihre Bedürfnisse an:

<blockbrain-main 
    clientId="your-clientId"
    secretKey="your-secretKey"
    orgId="your-orgId"
    issuer="my-issuer-url"
    layout="minimal"
    iconUrl="https://example.com/default-icon.png"
    iconSize="50px"
    messages='{
        "notCreated": {
            "iconSize": "100px",
            "title": "Bot-Einrichtung abgeschlossen",
            "description": "Die Bot-Einrichtung ist abgeschlossen. Sie werden zu Ihrem Bot weitergeleitet..."
        },
        "completed": {
            "iconSize": "106px",
            "title": "Benutzerdefinierter Abschlusstitel",
            "description": "Benutzerdefinierte Abschlussbeschreibung."
        },
        "requested": {
            "iconSize": "56px",
            "title": "Benutzerdefinierter Anfragetitel",
            "description": "Benutzerdefinierte Anfragebeschreibung."
        },
        "needAttention": {
            "title": "Benutzerdefinierte Aufmerksamkeit erforderlich",
            "description": "Benutzerdefinierte Beschreibung für erforderliche Aufmerksamkeit."
        },
        "rejected": {
            "title": "Benutzerdefinierter Ablehnungstitel",
            "description": "Benutzerdefinierte Ablehnungsbeschreibung."
        },
        "loading": {
            "iconUrl": "https://cdn-1.webcatalog.io/catalog/blockbrain/blockbrain-icon-filled-256.webp?v=1714777605928",
            "iconSize": "106px",
            "title": "Benutzerdefinierter Ladetitel",
            "description": "Benutzerdefinierte Ladebeschreibung."
        },
        "error": {
            "title": "Benutzerdefinierter Fehlertitel",
            "description": "Benutzerdefinierte Fehlerbeschreibung."
        },
        "missingParams": {
            "title": "Konfigurationsfehler",
            "description": "Es sieht so aus, als würde etwas in Ihrer Konfiguration fehlen. Bitte überprüfen Sie Ihre Konfiguration und versuchen Sie es erneut."
        }
    }'>
</blockbrain-main>

Beschreibungen der Attribute

• iconUrl (optional)

  • Beschreibung: URL zu einem Standard-Icon-Bild, das für alle Nachrichten verwendet wird, wenn keine spezifische iconUrl für die Nachricht angegeben ist.

  • Anpassung: Verwenden Sie die iconUrl-Eigenschaft innerhalb einer spezifischen Statusnachricht, um diesen Standard zu überschreiben.

  • Icon ausblenden: Um das Icon für eine Nachricht auszublenden, setzen Sie deren iconUrl auf einen leeren String ("").

  • Beispiel: "[https://example.com/default-icon.png](https://example.com/default-icon.png)"

• iconSize (optional)

  • Beschreibung: Legt die Größe des Standard-Icons fest.

  • Anpassung: Sie können die Größe für eine bestimmte Statusnachricht überschreiben, indem Sie deren iconSize angeben.

  • Werte: Akzeptiert jede gültige CSS-Größe (z.B. 50px, 4rem, 100%).

• messages (optional)

  • Beschreibung: Ein JSON-String, der es ermöglicht, die Titel und Beschreibungen für verschiedene Status anzupassen.

  • Struktur: Das messages-Attribut ist ein JSON-String, der es ermöglicht, das Erscheinungsbild jedes Status anzupassen. Jeder Status hat die folgenden anpassbaren Eigenschaften:

    • iconUrl (optional): URL zu einem Icon speziell für diesen Status. Verwenden Sie einen leeren String ("") zum Ausblenden.

    • iconSize (optional): Überschreibt die Standard-iconSize für diesen Status.

    • title (optional): Überschriftentext für den Status. Verwenden Sie einen leeren String ("") zum Ausblenden.

    • description (optional): Text, der unter dem Titel angezeigt wird. Verwenden Sie einen leeren String ("") zum Ausblenden.

  • Status:

    • notCreated: Wird angezeigt, wenn kein Bot für die angegebene botUid gefunden wird. Der Benutzer muss möglicherweise den Bot anfordern.

    • completed: Wird angezeigt, wenn die Bot-Einrichtung abgeschlossen ist, mit optionalem Weiterleitungshinweis.

    • requested: Die Bot-Anfrage wurde übermittelt, und der Bot wird in wenigen Sekunden bereit sein. Der Benutzer muss möglicherweise die Seite aktualisieren, um den Bot anzuzeigen.

    • needAttention: Erfordert Admin- oder Benutzeraktion, um mit der Bot-Einrichtung fortzufahren.

    • rejected: Wird angezeigt, wenn die Bot-Anfrage abgelehnt wurde.

    • loading: Wird während der Initialisierung oder anderen Ladevorgängen angezeigt.

    • error: Zeigt einen Fehler während des Bot-Einrichtungsprozesses an.

    • login: Wird auf der Anmeldeseite angezeigt.

Web Part: Bereitstellung & Konfiguration

Verwenden Sie dieses Handbuch, um Ihr Blockbrain Chat SPFx Web Part in SharePoint Online bereitzustellen, zu konfigurieren und Fehler zu beheben.

1. Bereitstellen des Pakets in SharePoint

1. Zugriff auf den App-Katalog

2. Navigieren Sie zu Ihrer SharePoint Online App Catalog Website. Normalerweise lautet die URL etwa so:

https://<your-tenant>.sharepoint.com/sites/apps

1. Das Paket hochladen

   1. Gehen Sie zu Apps für SharePoint (in der linken Navigation).

   2. Klicken Sie auf Hochladen und wählen Sie die .sppkg-Datei aus dem Ordner sharepoint/solution Ihres Projekts.

   3. Wenn Sie dazu aufgefordert werden, aktivieren Sie Diese Lösung für alle Standorte in der Organisation verfügbar machen, falls Sie möchten, dass sie global verfügbar ist.

      
   4. Klicken sie auf Deploy.

      
2. Bereitstellung prüfen

   • Wenn Sie Diese Lösung für alle Standorte verfügbar machen ausgewählt haben, sollte das Webpart automatisch auf allen Websitesammlungen verfügbar sein.

   • Andernfalls müssen Sie möglicherweise die App explizit zu der Website hinzufügen, auf der Sie sie verwenden möchten.

2. Das Webpart einer SharePoint-Seite hinzufügen

• Navigieren Sie zu Ihrer SharePoint-Seite

  • Gehen Sie zu der Seite, der Sie den Chatbot hinzufügen möchten.

• Bearbeiten Sie die Seite

  • Klicken Sie auf das Zahnrad-Symbol und wählen Sie Seite bearbeiten oder Bearbeiten.

• Fügen Sie das Webpart hinzu

  • Klicken Sie auf das + Symbol, um ein neues Webpart hinzuzufügen.

  • Suchen Sie nach BlockbrainChat (oder dem Namen, den Sie während der Einrichtung angegeben haben).

  • Fügen Sie es der Seite hinzu.

3. Webpart-Konfiguration

Das neue Webpart hat drei primäre Konfigurationsabschnitte in seiner Eigenschaftenleiste: Authentifizierung, Inhalt und Erscheinungsbild.

1. Öffnen Sie die Webpart-Eigenschaftenleiste

   • Während sich die Seite im Bearbeiten-Modus befindet, wählen Sie das Blockbrain Chat-Webpart aus.

   • Klicken Sie auf das Stift-Symbol, um die Eigenschaftenleiste des Webparts zu öffnen.

2. Authentifizierung

   • Anmeldemodus (loginMode)

     • Private Anmeldung: Verwendet eine Aussteller-URL (Auth-Endpunkt).

     • Öffentliche Anmeldung: Verwendet clientId und secretKey für die öffentliche Authentifizierung.

   • Aussteller (nur bei privater Anmeldung) (issuer)

     • Geben Sie die Aussteller-Endpunkt-URL an, wenn Sie loginMode auf "private" gesetzt haben.

   • Client-ID / Geheimer Schlüssel (nur bei öffentlicher Anmeldung) (clientId, secretKey)

     • Geben Sie die OAuth2-Anmeldeinformationen zur Authentifizierung bei Blockbrain an, wenn Sie loginMode auf "public" gesetzt haben.

3. Inhalt

   • Eindeutige Bot-Kennung (uid)

     • Geben Sie die Bot-UID ein, wenn Sie einen bestimmten Bot angeben möchten.

     • Dies kann auch durch URL-Parameter überschrieben werden (z.B. ?uid=ihre-bot-id).

4. Erscheinungsbild

   • Breite & Höhe (width, height)

     • Akzeptiert jeden gültigen CSS-Größenwert: z.B. 100%, 600px, 50vh, usw.

     • Verwenden Sie % oder Viewport-Einheiten für responsives Design oder px für eine feste Größe.

   • Symbol-URL (iconUrl)

     • Geben Sie eine direkte URL zum Symbol an, das im Chat angezeigt werden soll.

   • Symbolgröße (iconSize)

     • Legen Sie die Größe des Symbols fest (z.B. 50px, 96px).

   • Benutzerdefinierte Nachrichten-JSON (messages)

     • Ermöglicht das Überschreiben oder Anpassen von Systemnachrichten. Muss gültiges JSON sein.

   • Hintergrundfarbe (backgroundColor)

     • Wählen Sie eine Farbe aus dem Farbwähler oder geben Sie einen Hex-Code ein (z.B. #FFFFFF).

5. Webpart-Titel

   • Standardmäßig zeigt das Webpart einen Titelbereich an. Sie können ihn direkt auf der Seite bearbeiten:

     1. Klicken Sie auf den Webpart-Titeltext.

     2. Geben Sie Ihren benutzerdefinierten Titel ein (z.B. "Kundensupport-Chat").

     3. Drücken Sie Enter oder klicken Sie außerhalb, um zu speichern.

6. Speichern und Veröffentlichen

   • Nachdem Sie die Eigenschaften konfiguriert haben, klicken Sie auf Anwenden (falls erforderlich) und dann auf Veröffentlichen der Seite.

4. Zusätzliche Konfigurationsoptionen

1. URL-Parameter

   • Sie können die Bot-UID überschreiben, indem Sie ?uid=IHRE_BOT_UID an die Seiten-URL anhängen.

   • Ebenso können Sie eine userUid mit ?userUid=EINIGER_WERT angeben, um den Benutzer anders zu verfolgen oder zu identifizieren.

2. Für detaillierte Prop-Dokumentation

   • Siehe die offizielle Blockbrain-Dokumentation für zusätzliche, aktuelle Eigenschaftsreferenzen und Verwendungsbeispiele.

5. Fehlerbehebung & häufige Probleme

1. Probleme beim Laden von Skripten

   • Korrekte externe Skript-URL: Stellen Sie sicher, dass Sie die blocky-chat.bundle.js URL nicht verändert haben.

   • Netzwerk- / Proxy-Beschränkungen: Wenn Ihr Unternehmensnetzwerk externe Skripte blockiert, stellen Sie sicher, dass https://assets.theblockbrain.io/ erlaubt ist.

2. Authentifizierungsfehler

   • Überprüfen Sie loginMode, issuer, clientId und secretKey in der Eigenschaftenleiste.

   • Bei privater Anmeldung stellen Sie sicher, dass der Aussteller-Endpunkt korrekt ist.

   • Bei öffentlicher Anmeldung stellen Sie sicher, dass sowohl Client-ID als auch geheimer Schlüssel gültig sind.

3. Bot nicht gefunden

   • Überprüfen Sie, ob die von Ihnen angegebene uid (entweder in der Webpart-Eigenschaft oder URL) eine gültige Bot-UID aus Ihrer Blockbrain-Umgebung ist.

4. Webpart erscheint nicht oder 'Nicht gefunden'

   • Stellen Sie sicher, dass Sie die .sppkg-Datei in den App-Katalog hochgeladen haben.

   • Aktivieren Sie Diese Lösung für alle Standorte verfügbar machen, wenn Sie möchten, dass es in Websitesammlungen erscheint.

   • Wenn nicht, fügen Sie die Lösung zu den Websiteinhalten Ihrer spezifischen Website hinzu.

5. Andere Benutzer können das Webpart nicht sehen

   • Bestätigen Sie, dass das Webpart (und das zugrunde liegende Skript) für alle beabsichtigten Benutzer freigegeben oder zugänglich ist.

   • Wenn das Skript extern gehostet wird, überprüfen Sie, ob die Skript-Domain nicht durch Tenant-Richtlinien eingeschränkt ist.