So versenden Sie Einladungen mit Business Generated Links (für Entwickler)

Diese Anleitung richtet sich an Entwickler, die Business Generated Links erstellen möchten. Hier erfahren Sie, wie Sie mit Ihrer bevorzugten Programmiersprache verschlüsselte Links generieren.

WICHTIG

Die Einladungsmethode Business Generated Links steht nur neuen Trustpilot-Unternehmenskunden in bestimmten Branchen zur Verfügung.

Bitte beachten: Um Ihnen den Einstieg in Business Generated Links zu erleichtern, hat Trustpilot auf Github verschiedene Tools zur Authenticated Encryption erstellt. Weitere Informationen dazu finden Sie in diesem Artikel.

Anleitung für alle Programmiersprachen

Business Generated Links nutzen für die Verschlüsselung AEAD (Authenticated Encryption with Associated Data) und den EtM-Ansatz (Encrypt then MAC). Um die Datenintegrität sicherzustellen, verwendet Trustpilot einen Code zur Verschlüsselung der Payload-Daten (encryptkey) und einen anderen Code für das MAC-Element (authkey).

Sie finden die beiden Codes in Ihrem Trustpilot-Business-Account: Gehen Sie zum Bereich Bewertungen erhalten, weiter zu Kunden einladen und dort zu Business Generated Links.

So erstellen Sie Business Generated Links

  1. Die Verschlüsselungscodes, die Sie von Ihrem Trustpilot-Business-Account kopieren, werden in einem mit Base64 kodierten Format angezeigt. Ihre Anwendung muss also zunächst eine Base64-Dekodierung dieser Codes durchführen.
  2. Erstellen Sie das Payload-Objekt im JSON-Format und setzen Sie die Kundeninformationen ein. Dabei sind die Felder email, name und ref (=Referenznummer) unbedingt erforderlich. Hier sehen Sie ein Beispiel:
{
  "email":"mustermann@beispiel.de",
  "name":"Max Mustermann",
  "ref":"1234",
  "skus":["sku1","sku2","sku3"],
  "tags":["tag1","tag2","tag3"]
}
Bitte beachten: Tags dürfen keine Leerzeichen enthalten.
  1. Stellen Sie sicher, dass die Payload-Daten nicht von Dritten gelesen werden können, indem Sie diese Payload-Daten verschlüsseln. Führen Sie die Verschlüsselung mit AES-CBC mit einer Schlüssellänge von 256 Bit, einer Blockgröße von 128 Bit und dem PKCS7-Paddingmodus durch.
  • Generieren Sie einen Initialisierungsvektor (IV) mit der entsprechenden Blockgröße (128 Bit).
  • Verschlüsseln Sie das JSON-Objekt mit dem Verschlüsselungs-Code (encryptkey) und dem IV.
  • Erstellen Sie eine Signatur des Ciphertexts.
  • Hierfür verwenden wir HMAC-SHA256 und den Authentifizierungs-Code (authkey). Berechnen Sie den HMAC durch Hashing des IV gefolgt vom Ciphertext. Zum Beispiel: HMAC = HMAC-SHA256( IV + Ciphertext )
  1. Kodieren Sie nun den IV, den Ciphertext und den HMAC mit Base64. Also so: base64_payload = base64( IV + Ciphertext + HMAC )
  2. Da Base64 Schrägstriche (/) und Pluszeichen (+) enthält, müssen Sie zum Schluss die obigen Payload-Daten URL-kodieren, bevor Sie sie dem endgültigen Link hinzufügen.
  3. Der endgültige Link sollte so aussehen:
  payload = urlencode( base64_payload )
  https://www.trustpilot.com/evaluate-bgl/<domain>?p=<payload>
  1. Ersetzen Sie <domain> durch Ihre Webadresse und <payload> durch die Payload-Daten, die Sie in Schritt 5 generiert haben.

Das folgende Flussdiagramm zeigt die Schritte, die für die korrekte Formatierung, Verschlüsselung und Aufbereitung der Payload-Daten vor dem Versand erforderlich sind:

Image_1.png

So können Sie einen Business Generated Link überprüfen

Es gibt zwei Möglichkeiten, um zu überprüfen, ob ein Business Generated Link korrekt erstellt wurde:

Testen Sie Ihren Link in einem Browser

Fügen Sie Ihren Link in einen Browser ein und öffnen Sie ihn. Erstellen Sie dann eine Testbewertung. Wählen Sie eine Anzahl von Sternen, schreiben Sie einen Titel und einen Bewertungstext. Wenn der Button Bewertung jetzt veröffentlichen aktiv ist, war Ihre Verschlüsselung erfolgreich. Wenn Sie aufgefordert werden, sich mit Facebook, Google oder Ihrer E-Mail-Adresse einzuloggen, ist Ihre Verschlüsselung fehlgeschlagen. Veröffentlichen Sie Ihre Testbewertung nicht. Hier sehen Sie ein Beispiel:

Image_2.png

Testen Sie Ihren Link mit unserer Befehlszeilen-Schnittstelle (CLI)

Sie können unsere Befehlszeilen-Schnittstelle (CLI) auf Ihrem Entwicklungsrechner installieren. Wenn Sie Ihre Payload-Daten mit der Befehlszeilen-Schnittstelle entschlüsseln können, haben Sie Ihre Payload-Daten korrekt verschlüsselt.

So verschlüsseln Sie Business Generated Links für Produktbewertungen

Fügen Sie Produkt-SKUs zu Ihren Payload-Daten hinzu, um mit Business Generated Links Produktbewertungen zu sammeln. Hier sehen Sie ein Beispiel für Payload-Daten, das Produkt-SKUs enthält. Es handelt sich um ein einfaches JSON-Array:

{
  "email":"mustermann@beispiel.de",
  "name":"Max Mustermann",
  "ref":"1234",
  "skus":["sku1","sku2","sku3"]
}

So können Sie einen Business Generated Link für ein bestimmtes Land lokalisieren

Um den Link zu lokalisieren, entfernen Sie „www“ und ersetzen es durch den jeweiligen Ländercode, z. B.:

https://de.trustpilot.com/evaluate-bgl/?p= https://fr.trustpilot.com/evaluate-bgl/?p=

So verwenden Sie Business Generated Links für Einladungen zu Standortbewertungen

Wenn Sie Business Generated Links verwenden möchten, um Einladungen zu Standortbewertungen zu versenden, müssen Sie beim Einfügen der Kundeninformationen in das Payload-Objekt ebenfalls das Standort-Feld hinzufügen. Verwenden Sie dafür die Standort-ID, die Sie dem jeweiligen Standort zugewiesen haben.

Hier sehen Sie ein Beispiel:

{
  "email":"mustermann@beispiel.de",
  "name":"Max Mustermann",
  "ref":"1234",
  "locationId": "id1",
  "skus":["sku1","sku2","sku3"],
  "tags":["tag1","tag2","tag3"]
}

Bitte beachten: Bei der Standort-ID muss die Groß- und Kleinschreibung eingehalten werden.