Kommentare

Plan Feature

Diese Funktion ist nur in den Plänen Growth und Scale verfügbar.

Mit Kommentaren können Ihre Benutzer Feedback hinterlassen und Diskussionen direkt an E-Mail-Vorlagen im Editor führen. Kommentare sind threadbasiert, können an bestimmte Blöcke verankert werden und unterstützen das Auflösen/Wiederöffnen für Review-Workflows.

Funktionsweise

1. Ihr Token-Endpunkt gibt die Identität des aktuellen Benutzers und eine kryptografische Signatur zurück (siehe Einrichtung)
2. Das SDK zeigt eine Kommentare-Schaltfläche in der Editor-Toolbar
3. Benutzer können Kommentare erstellen, auf bestehende Threads antworten und Konversationen auflösen
4. Das SDK ruft den onComment-Callback auf (falls konfiguriert), wenn eine Kommentaraktion stattfindet

Die Benutzeridentität wird mit HMAC-SHA256 verifiziert, sodass sie auf der Client-Seite nicht gefälscht werden kann. Jeder Benutzer kann nur seine eigenen Kommentare bearbeiten und löschen.

Einrichtung

1. Signaturschlüssel abrufen

Den Signaturschlüssel finden Sie in Ihren Projekteinstellungen im Templatical-Dashboard. Dieser Schlüssel wird zum Signieren der Benutzeridentitätsdaten verwendet. Speichern Sie ihn sicher auf Ihrem Backend zusammen mit Ihrer Client ID und Ihrem Client Secret.

2. Token-Endpunkt aktualisieren

Ihr Token-Endpunkt gibt bereits eine Token-Antwort zurück (siehe Authentifizierung). Um Kommentare zu aktivieren, fügen Sie der Antwort ein user-Objekt hinzu:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": 1709251200,
  "project_id": "proj_abc123",
  "tenant": "acme-corp",
  "user": {
    "id": "user_123",
    "name": "Jane Smith",
    "signature": "a1b2c3d4..."
  }
}

Feld	Typ	Beschreibung
user.id	string	Eine eindeutige Kennung für den Benutzer in Ihrem System
user.name	string	Der Anzeigename des Benutzers (wird bei Kommentaren angezeigt)
user.signature	string	HMAC-SHA256-Signatur der Benutzer-ID

Wenn das user-Objekt fehlt, wird die Kommentare-Schaltfläche in der Toolbar nicht angezeigt.

Signatur berechnen

Der Signaturalgorithmus ist:

1. Die id-Zeichenkette des Benutzers (z. B. "user_123") mit Ihrem Signaturschlüssel per HMAC-SHA256 signieren

Backend-Beispiele

import crypto from 'crypto';

app.post('/api/token', async (req, res) => {
  // 1. Token von Templatical abrufen
  const response = await fetch('https://templatical.com/api/v1/auth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      client_id: process.env.TEMPLATICAL_CLIENT_ID,
      client_secret: process.env.TEMPLATICAL_CLIENT_SECRET,
      tenant: req.user.organizationId,
    }),
  });

  const tokenData = await response.json();

  // 2. Benutzersignatur berechnen
  const signature = crypto
    .createHmac('sha256', process.env.TEMPLATICAL_SIGNING_KEY)
    .update(String(req.user.id))
    .digest('hex');

  // 3. Token + Benutzerkonfiguration zurückgeben
  res.json({
    ...tokenData,
    user: {
      id: req.user.id,
      name: req.user.name,
      signature,
    },
  });
});

Important

Der für die Signatur verwendete id-Wert muss mit dem in der Antwort zurückgegebenen user.id-Wert übereinstimmen. Stellen Sie sicher, dass Sie an beiden Stellen die gleiche Zeichenkette verwenden.

Funktionen

Threadbasierte Kommentare

Kommentare unterstützen Threading — Benutzer können auf jeden Hauptkommentar antworten, um einen Konversationsthread zu erstellen. Antworten werden inline unter ihrem übergeordneten Kommentar angezeigt.

Block-Verankerung

Kommentare können an bestimmte Vorlagenblöcke verankert werden. Wenn ein Kommentar mit einem Block verknüpft ist, erscheint ein Kommentar-Indikator-Badge auf diesem Block im Editor. Ein Klick auf das Badge öffnet die Kommentar-Seitenleiste, gefiltert nach den Kommentaren dieses Blocks.

Kommentare auflösen

Jeder Benutzer kann einen Kommentar-Thread auflösen oder wiederöffnen. Aufgelöste Kommentare sind visuell unterscheidbar und können herausgefiltert werden, was es einfach macht nachzuverfolgen, welches Feedback bearbeitet wurde.

Berechtigungen

Benutzer können nur ihre eigenen Kommentare bearbeiten und löschen. Die Eigentümerschaft wird serverseitig überprüft, indem die signierte Benutzeridentität mit dem Autor des Kommentars abgeglichen wird. Jeder Benutzer kann jeden Kommentar auflösen oder wiederöffnen.

Kommentare deaktivieren

Auch wenn Ihr Plan Kommentare unterstützt und Ihr Token-Endpunkt eine Benutzeridentität zurückgibt, können Sie Kommentare bei Bedarf deaktivieren, indem Sie commenting: false in der SDK-Konfiguration setzen:

const editor = await init({
  container: '#email-editor',
  auth: { url: 'https://your-app.com/api/token' },
  commenting: false,
});

Wenn commenting auf false gesetzt ist, wird die Kommentare-Schaltfläche unabhängig von Plan- oder Benutzerkonfiguration nicht in der Toolbar angezeigt. Das Weglassen der Option oder das Setzen auf true (Standard) ermöglicht Kommentare basierend auf Planverfügbarkeit und Benutzeridentität.

onComment

Wird aufgerufen, wenn eine Kommentaraktion stattfindet. Verwenden Sie diesen Callback, um Kommentaraktivitäten mit Ihren eigenen Systemen zu synchronisieren — z. B. um Benachrichtigungen zu senden oder Aktivitäten zu protokollieren.

const editor = await init({
  container: '#email-editor',
  auth: { url: 'https://your-app.com/api/token' },
  onComment: (event) => {
    console.log(event.type, event.comment);

    // Beispiel: Ihr Backend über neue Kommentare benachrichtigen
    if (event.type === 'created') {
      fetch('/api/comment-notifications', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          templateId: event.comment.template_id,
          authorName: event.comment.author_name,
          body: event.comment.body,
        }),
      });
    }
  },
});

Das event-Objekt enthält:

Feld	Typ	Beschreibung
type	string	Einer von: created, updated, deleted, resolved, unresolved
comment	Comment	Das Kommentar-Objekt (siehe Kommentar-Objekt)

Kommentar-Objekt

Feld	Typ	Beschreibung
id	string	Eindeutige Kommentar-Kennung (UUID)
template_id	string	Die Vorlage, zu der dieser Kommentar gehört
block_id	string | null	Der Block, an dem dieser Kommentar verankert ist (null für allgemeine Kommentare)
parent_id	string | null	ID des übergeordneten Kommentars (null für Hauptkommentare)
body	string	Der Kommentartext (maximal 2000 Zeichen)
author_identifier	string	Die Benutzer-ID des Autors
author_name	string	Der Anzeigename des Autors
resolved_at	string | null	ISO-Zeitstempel, wann der Kommentar aufgelöst wurde
resolved_by_identifier	string | null	Benutzer-ID desjenigen, der den Kommentar aufgelöst hat
resolved_by_name	string | null	Anzeigename desjenigen, der den Kommentar aufgelöst hat
created_at	string	ISO-Zeitstempel, wann der Kommentar erstellt wurde
updated_at	string	ISO-Zeitstempel, wann der Kommentar zuletzt aktualisiert wurde
replies	Comment[]	Array von Antwort-Kommentaren (nur bei Hauptkommentaren)