Hello! How can we help?

Browse the Trustpilot Support Center to find info on Google Seller Ratings, Rich Snippets, TrustBoxes, Product reviews, plus how-to guides for editing your reviews and account settings

​Business Generated Links (for developers)

Here's a general guide on how to generate encrypted links using the programming language of your choice. Before you start developing your own program, please note that Trustpilot has developed some resources that can help you get started with Business Generated Links. You can read more about both resources in the Authenticated Encryption on GitHub section at the end of this document.

General 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. These two keys can be obtained from your Trustpilot Business portal under the 'Business Generated Links' tab. If you don't see the tab, it is because you have to upgrade your account.

Here’s a step-by-step guide of how to create Business Generated Links:

  1. The keys copied from the Trustpilot Business portal 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 customer information. Please note: the following fields are required: email, name, and ref (reference number). Example:

{

"email":"xyz@domain.com",

"name":"John Doe",

"ref":"1234",

"skus":["sku1","sku2","sku3"],

"tags":["tag1","tag2","tag3"]

}

To receive multiple reviews from the same customer, make sure to include a reference number every time you send them a Business Generated Link.

  1. Ensure the payload cannot be read by third-party interests, 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

HMAC = HMAC-SHA256( IV + ciphertext )

  1. Now base64-encode the IV + ciphertext + HMAC:

base64_payload = base64( IV + ciphertext + HMAC )

  1. 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. The final link should look like this:

payload = urlencode( base64_payload )

https://www.trustpilot.com/evaluate-bgl/<domain>?p=<payload>

Replace the <domain> with your domain name and <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:

How to verify that a Business Generated Link works

There are two ways of verifying that a Business Generated Link has been created correctly:

1. Test your link in a browser

  • Paste your link into a browser and navigate to www.trustpilot.com.
  • Select a star rating, add a title, and a review text.
  • Now you can verify that your link works. If the name of the reviewer is displayed on the page then your encryption process is correct. If you are asked to log in using Facebook, Google, or Email, then your encryption process is incorrect.
  • Please don’t post your test review.

2. 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.

Collecting product reviews with Business Generated Links

Collecting product reviews with Business Generated Links is easy. First add the relevant product SKUs to the payload and then upload your product catalog to Trustpilot.

1. Add product SKUs to your payload

Below is an example of a payload that includes product SKUs. It’s a simple JSON array.

{

"email":"xyz@domain.com",

"name":"John Doe",

"ref":"1234",

"skus":["sku1","sku2","sku3"]

}

2. Upload your product catalog to Trustpilot

To upload your product catalog to Trustpilot, provide your Customer Success Manager with a tab-separated file of all product details. The file should include the following column names (all lowercase):

  • sku (required)
  • title
  • link
  • image_link
  • gtin
  • mpn
  • brand
  • price

You can learn more about the format of this file here.

Once your product catalog is uploaded, our system is able to match a given product SKU with relevant product details, such as the URL of the product page on your site, the URL of the product image on your site, as well as the name of the product. Product details are then used to optimize your customer’s user experience. For example, when your customer is presented with the form where they will write the review, the form will include the name and an image of the product. Trustpilot also feeds product reviews to Google where they are used, e.g. in product listing ads.

“Authenticated Encryption” on GitHub

Here are some resources to help you get started with Business Generated Links:

1. Open source library for .NET

If your development language of choice is C-Sharp .NET, then you are in luck. We have generated a programming library that combines the .NET built-in AES and HMAC algorithms to provide an easy-to-use interface for doing authenticated encryption. Our library is based on this Gist by James Tuley: https://gist.github.com/jbtule/4336842, but modified slightly to only support the key based versions. Also, it does not use the GCM version, so there are no external dependencies. Please visit our GitHub repository and download the library here: https://github.com/trustpilot/nuget-authenticated-encryption

2. Open source command line client for Windows, Linux & Mac (beta)

We have also developed a lightweight command line client (program) your company can use to encrypt the data payload to be included in the link. This option was developed to accommodate companies with limited programming resources. You can learn more and download this client here: https://github.com/trustpilot/authenticated-encryption-cli

3. Open source sample for the Python programming language

If your development language is Python, then simply download our Python implementation here: https://github.com/trustpilot/python-authenticated-encryption

4. Open source example for PHP

If your development language is PHP, then download our PHP implementation here: https://github.com/trustpilot/php-authenticated-encryption

5. Open source example for Java

If your development language is Java, then download our Java implementation here: https://github.com/NordeaOSS/authenticated-encryption

Comments

0 comments

Please sign in to leave a comment.