🕸️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.

Integration der Webkomponente

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.

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:

• orgId: Für Ihre Instanz bereitgestellte Organisations-ID.

• issuer: URL Ihrer Blockbrain-Domain.

• uid: Eindeutiger Identifikator für die Bot-Instanz oder Anwendung.

• userUid: Eindeutiger Identifikator für den Benutzer (optional).

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.

• clientSecret: Ein Client-Geheimnis zur Aktivierung des öffentlichen Modus.

• uid: Eindeutiger Identifikator für die Bot-Instanz oder Anwendung.

• userUid: Eindeutiger Identifikator für den Benutzer (optional).

Beispiel:

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

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

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.