This feature is part of the Private add-on module.

Get the module

Send invitations with Business Generated Links (for developers)

This feature is part of the Private add-on module.

Get the module

This guide is for developers who want to create Business Generated Links. Here you can learn how to generate encrypted links using your chosen programming language.

Note: Trustpilot has created resources about Authenticated Encryption on Github to help you get started. Read about them here.

Guide for all programming languages

Business Generated Links use Authenticated Encryption with Associated Data (AEAD) and an approach called Encrypt then MAC (EtM). Trustpilot uses one key to encrypt the payload (encryptkey) and another key for the MAC part (authkey) to ensure data integrity.

From your Trustpilot Business account, navigate to Get Reviews > Invite Customers > Business Generated Links to find the two keys.

Create Business Generated Links

  1. The keys copied from your Trustpilot Business account are displayed in a base64-encoded format. So, the first thing your application needs to do is a base64-decode of the keys.
  2. Create the JSON formatted payload object and insert the customer information. Note that the following fields are required: email, name, and ref (reference number). Here’s an example:
{
  "email":"xyz@domain.com",
  "name":"John Smith",
  "ref":"1234",
  "skus":["sku1","sku2","sku3"],
  "tags":["tag1","tag2","tag3"]
}
Note: Tags must not contain any spaces.
  1. Ensure the payload cannot be read by third-parties by encrypting the payload. Encrypt with AES-CBC using a key size of 256 bits, a block size of 128 bits, and PKCS7 padding mode
    • Generate an Initialization Vector (IV) according to the block size ( 128 bits)
    • Encrypt the JSON with the encryptkey and IV
    • Create a signature of the ciphertext.
    • For this, we use HMAC-SHA256 and the authkey. Compute the HMAC by hashing the IV followed by the ciphertext. Here's an example: HMAC = HMAC-SHA256( IV + ciphertext )
  1. Now base64-encode the IV + ciphertext + HMAC. Like this: base64_payload = base64( IV + ciphertext + HMAC )
  2. Finally, because base64 includes the slash (/) and plus (+) characters, it is necessary to URL-encode the payload above before adding it to the final link.
  3. The final link should look like this:
  payload = urlencode( base64_payload )
  https://www.trustpilot.com/evaluate-bgl/?p=
  1. Replace the domain with your domain name and the payload with the payload you generated in step 5.

The following flowchart shows the necessary steps involved in correctly formatting, encrypting, and preparing the payload data prior to distribution:

Image_1.png

How to verify a Business Generated Link

There are two ways to verify that a Business Generated Link has been created correctly:

Test your link in a browser

Paste your link into a browser and search. Then create a test review. Select a star rating, add a title, and a review text. If the Post your review now button is active, your encryption process succeeded. If you are asked to log in using Facebook, Google, or Email, then your encryption process failed. Please don’t post your test review. Here's an example:

Image_2.png

Test your link with our command line interface (CLI)

You can install our command line interface (CLI) on your development computer. If you can decrypt your payload with the CLI, then you have encrypted your payload correctly.

Encode Business Generated Links for product reviews

To collect product reviews with Business Generated Links, add product SKUs to your payload. Here’s an example of a payload that includes product SKUs. It’s a simple JSON array:

{
  "email":"xyz@domain.com",
  "name":"John Smith",
  "ref":"1234",
  "skus":["sku1","sku2","sku3"]
}