Skip to main content
Skip table of contents

Send Review Emails Yourself

By default, client Review Solicitation Emails (RSE) are sent to shoppers by Emplifi. If you want to retain control of the timing, recipient list, and triggering of the RSE while still having shopper reviews submitted via the Emplifi widgets after click-through, you can do so by constructing the links in your email according to the instructions outlined in this document.

A typical Review Solicitation Email contains information about what products the customer bought, and links for each of those products on the calls-to-action to submit their reviews.

For such a link to properly work with Emplifi, you must include certain details in URL query string parameters. At Emplifi, we sometimes call this a "magic link" because it contains all of the necessary information to display the Review Submission Form when clicked.

URL base path

https://www.turnto.com/trackin/review

Adding locales

To specify a locale other than the default locale, append the locale to the URL base path.

Example:

https://www.turnto.com/trackin/review/en_AU

If the data in your Catalog Feed does not contain data for this locale in the item's LOCALEDATA or regional_data field, we will use the default locale.

Parameters

  • siteKey - The site key that is located in your site’s configuration on www.turnto.com.

  • emailType - review

  • turntoCampaign - Campaign identifier; a string on a customer's system that is used to identify/differentiate campaigns. This parameter allows clients to track engagement in their campaigns.

  • turntoIncentiveType - Type of incentive (Sweepstakes or Sample)

  • turntoSku -The SKU of the product that is to be reviewed. Note that an email can have multiple products for review in it, but each link can only refer to one product.

  • turntoOrdJWT - The details of the order encoded as a JSON Web Token (JWT). Emplifi needs the order to properly attribute reviews to owners, among other things. See the turntoOrdJWT parameter section to learn more.

  • turntoReviewStartAction - One of either the string rateIt or the string shareAPhoto. If this parameter is not present, the user is sent to the "Review Flow" (same as rateIt). See Two possible workflows to learn more.

  • turntoStarSelected - A number from 0-5 representing which star (from 1 to 5) the user clicked on, or 0 if they clicked on the text-based "Start by rating it" link rather than one of the stars. If this parameter is not present, it will be as though 0 is passed, which means no star will be pre-selected when the user lands on the page.

See an example of a full URL.

Two possible workflows

The Review Solicitation Email can contain links to direct a user to one of two possible workflows for contributing rating and review content.

  • Review Flow - emphasizes collecting rating and overall impression data first, with the subsequent opportunity to add visual content.

  • Visual Content Flow - emphasizes collecting photos or videos first, with the subsequent opportunity to add rating and review information.

Links containing turntoReviewStartAction=rateIt or missing the turntoReviewStartAction parameter bring users to the "Review Flow". Links containing turntoReviewStartAction=shareAPhoto bring users to the "Visual Content Flow".

The turntoOrdJWT parameter

The turntoOrdJWT parameter contains order data encoded as a JSON Web Token (JWT). JWT is a compact, URL-safe way of securely transferring information between two parties as a JSON object. Emplifi uses the signature of the JWT to verify the contents of the turntoOrdJWT parameter. An order is rejected if the token is invalid or the signature cannot be verified.

These are the steps involved in creating a signed JWT with order data to be passed as the value of the turntoOrdJWT parameter.

1. Create the JWS Header

The JWS Header is a JSON object with parameters describing how the JWT payload is digitally signed or MACed. The alg parameter is required. Emplifi expects the JWT to be signed with the HMAC SHA-256 algorithm. The following shows the JWS Header:

CODE 
{
 "alg": "HS256",
}

This JSON is base64url encoded to form the first part of the JWT.

2. Create the JWS Payload

The JWS Payload is a JSON object that has the order details. This is an example:

CODE 
{
   "orderId": "99977",
   "deliveryDate": "2019-05-20",
   "orderDate": "2019-05-15",
   "postalCode": "10667",
   "incentiveType": "SAMPLE",
   "user":          {
       "firstName": "Andy",
       "lastName": "Adamson",
       "nickName": null,
       "emailAddress": "andrew@sample.com"
   },
   "items":     [
   {
      "lineItemId": "1",
      "title": "Adeline Slim Wallet",
      "url": "https://www.yoursite.com/U00467.html",
      "sku": "U00467"
   }
   ]
}

This JSON is base64url encoded to form the second part of the JWT.

The required fields are: orderId, orderDate, deliveryDate, firstName, lastName, emailAddress, title, url, sku

The customer's preferred locale is optional. The locale must contain both the language and country code. Example for Canadian French: fr_CA.

The incentiveType field should only be included for incentive programs, such as when a free product sample has been provided in order to obtain a review.

3. Compute the JWS Signature

The JWS Signature is constructed using the encoded header, encoded payload, and a secret key. Use your site’s authKey as the secret key. The signature is computed in the following way:

CODE 
HMACSHA256(
   BASE64URL(header) + "." +
   BASE64URL(payload),
   authKey)

The output of the computed signature is base64url encoded to form the third part of the JWT.

4. Create the JWT token

Finally, the JWT token is constructed using the encoded header, encoded payload, and encoded signature as follows:

CODE 
BASE64URL(header) + "." +
 BASE64URL(payload) + "." +
 BASE64URL(signature)

Below is a JWT that has the previous header and payload encoded, and is signed with authKey "NnbTyYRfma8TFeGAc9etgUJAvizzauth". Line feeds have been added for readability.

CODE 
eyJhbGciOiJIUzI1NiJ9.
eyJpbmNlbnRpdmVUeXBlIjoiU0FNUExFIiwicG9zdGFsQ29kZSI6IjEwNjY3IiwiaXRlbXMiOlt7
ImxpbmVJdGVtSWQiOiIxIiwidGl0bGUiOiJBZGVsaW5lIFNsaW0gV2FsbGV0IiwidXJsIjoiaHR0
cDpcL1wvd3d3LnlvdXJzaXRlLmNvbVwvVTAwNDY3Lmh0bWwiLCJza3UiOiJVMDA0NjcifV0sIm9y
ZGVyRGF0ZSI6IjIwMTUtMDUtMTUiLCJkZWxpdmVyeURhdGUiOiIyMDE1LTA1LTIwIiwiaWF0Ijox
NTE2ODA5MzA4LCJ1c2VyIjp7ImZpcnN0TmFtZSI6IkFuZHkiLCJsYXN0TmFtZSI6IkFkYW1zb24i
LCJuaWNrTmFtZSI6bnVsbCwiZW1haWxBZGRyZXNzIjoiYW5kcmV3QHNhbXBsZS5jb20ifSwib3Jk
ZXJJZCI6Ijk5OTc3In0.
PBG3PIJ5h8PauRyXP2rFhHGrSkjxAqNnIPDMIlrPpW4

This JWT would be passed to Emplifi in the turntoOrdJWT parameter. The signature of the JWT is used by Emplifi to verify the order data has not been tampered with.

Creating a signed JSON Web Token

Below is an example implementation in PHP that creates a signed JSON Web Token using the Spomkey-Labs/Jose PHP library.

CODE 
use Jose\Factory\JWSFactory;
use Jose\Object\JWK;

// define an HMAC key with your site’s authKey
$jwk = new JWK([
  'k' => authKey,
]);

// define the order payload
$claims = [
   'orderId'        => '99977',
   'deliveryDate'   => '2019-05-20',
   'orderDate'      => '2019-05-15',
   'postalCode'     => '10667',
   'locale'         => 'en_US',
   'incentiveType'  => 'SAMPLE',
   'user'           => [
       'firstName'     => 'Andy',
       'lastName'      => 'Adamson',
       'nickName'      => null,
       'emailAddress'  => 'andrew@sample.com',
   ],
   'items': [
       [
           'lineItemId'  => '1',
           'title'  => 'Adeline Slim Wallet',
           'url'  => 'https://www.yoursite.com/U00467.html',
           'sku'  => 'U00467',
       ]
   ]
]

// generate the signed JWT token
$turntoOrdJWT = JWSFactory::createJWSToCompactJSON(
   $claims,           // The payload or claims to sign
   $jwk,              // The key used to sign

  [               // Protected headers. Must contain at least algorithm
       'alg' => 'HS256',
   ]
);

Below is a similar example in Java using the Nimbus-JOSE JWT library.

CODE 
import com.nimbusds.jose.*;
import com.nimbusds.jose.crypto.*;
Import com.nimbusds.jwt.*;

// define the header. Must contain at least algorithm
JWSHeader header = new JWSHeader(JWSAlgorithm.HS256);

// define the order payload
JWTClaimsSet.Builder claims = new JWTClaimsSet.Builder();
claims.claim("orderId", "99977");
claims.claim("deliveryDate", "2019-05-20");
claims.claim("orderDate", "2019-05-15");
claims.claim("postalCode", "10667");
claims.claim("locale", "en_US");
claims.claim("incentiveType", "SAMPLE");
// etc…

// create HMAC signer with site authKey as secret
JWSSigner signer = new MACSigner(authKey.getBytes());

// generate the signed JWT token
SignedJWT jws = new SignedJWT(header, claims.build());
jws.sign(signer);

// serialize to compact form
String turntoOrdJWT = jws.serialize();

Verifying generated JWT tokens

You can use the debugger at JWT.IO to verify tokens generated manually or using a library. This is a good way to test whether Emplifi can verify the JWT tokens you generate.

Review Solicitation Email URL example

Sticking with the above order, this is the URL for a link in the review solicitation email sent to inviting him to review the Adeline Slim Wallet:

https://www.turnto.com/trackin/review?siteKey=YOURSITEKEY&emailType=review&turntoSku=U00467&turntoOrdJWT=eyJhbGciOiJIUzI1NiJ9.eyJpbmNlbnRpdmVUeXBlIjoiU0FNUExFIiwicG9zdGFsQ29kZSI6IjEwNjY3IiwiaXRlbXMiOlt7ImxpbmVJdGVtSWQiOiIxIiwidGl0bGUiOiJBZGVsaW5lIFNsaW0gV2FsbGV0IiwidXJsIjoiaHR0cDpcL1wvd3d3LnlvdXJzaXRlLmNvbVwvVTAwNDY3Lmh0bWwiLCJza3UiOiJVMDA0NjcifV0sIm9yZGVyRGF0ZSI6IjIwMTUtMDUtMTUiLCJkZWxpdmVyeURhdGUiOiIyMDE1LTA1LTIwIiwiaWF0IjoxNTE2ODA5MzA4LCJ1c2VyIjp7ImZpcnN0TmFtZSI6IkFuZHkiLCJsYXN0TmFtZSI6IkFkYW1zb24iLCJuaWNrTmFtZSI6bnVsbCwiZW1haWxBZGRyZXNzIjoiYW5kcmV3QHNhbXBsZS5jb20ifSwib3JkZXJJZCI6Ijk5OTc3In0.PBG3PIJ5h8PauRyXP2rFhHGrSkjxAqNnIPDMIlrPpW4

If there are multiple items to review in a single email, the URLs on each of those items would differ only in the turntoSku parameter. The entire order will be encoded in each link as the value of the turntoOrdJWT parameter.

Configuration for site groups

If your site is part of a site group, you must pass the site key in the items array because products in the order can come from multiple stores (Emplifi sites).

Here is an example of how the payload of the turntoOrdJWT parameter should look in such a case:

CODE 
{
   "orderId": "99977",
   "deliveryDate": "2019-05-20",
   "orderDate": "2019-05-15",
   "postalCode": "10667",
   "locale": "en_US",
   "user":          {
       "firstName": "Andy",
       "lastName": "Adamson",
       "nickName": null,
       "emailAddress": "andrew@sample.com"
   },
   "items":     [
   {
      "lineItemId": "1",
      "title": "Adeline Slim Wallet",
      "url": "https://www.yoursite.com/U00467.html",
      "sku": "U00467",
      "siteKey": "aaa-aaa",
   }
   ]
}

Additional External Resources

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close