Send Seller Rating Emails Yourself

A typical Seller Ratings solicitation email contains information about the customer's order and a call-to-action to rate their experience with the seller. If you want to control the timing and recipient list for seller rating requests, you can construct and embed call-to-action links in your own email. Recipients will receive your email, click-through to your landing page, and submit seller ratings via Emplifi widgets.

If you send your own seller rating request emails, be aware that Google prohibits the collection of incentivized seller ratings. If you have already offered incentives, please contact us so that we can remove those reviews from the Google seller ratings feed.

You need to encode the order data as a JSON Web Token (JWT) and include it in the link embedded in your email. This is like the option to Send Review Emails Yourself.

Your email should include a call-to-action that opens your landing page. For steps to set up the landing page, see Landing Page.

For the call-to-action link to 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 seller rating collection form when clicked.

URL base path

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

Parameters

siteKey - The site key that is located in your site’s configuration in Emplifi Ratings & Reviews.
turntoOrdJWT - The details of the order encoded as a JSON Web Token (JWT). Emplifi needs the order to properly attribute seller ratings to owners, among other things. See the turntoOrdJWT parameter section for more detail.
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.

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 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',
   '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("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.

Seller Rating Solicitation Email URL example

Sticking with the above order, this is the URL for a link in the seller rating solicitation email sent to Andy, our fictional shopper, inviting him to rate his experience with your company:

https://www.turnto.com/trackin/sellerrating?siteKey=YOURSITEKEY&turntoOrdJWT=eyJhbGciOiJIUzI1NiJ9.eyJpbmNlbnRpdmVUeXBlIjoiU0FNUExFIiwicG9zdGFsQ29kZSI6IjEwNjY3IiwiaXRlbXMiOlt7ImxpbmVJdGVtSWQiOiIxIiwidGl0bGUiOiJBZGVsaW5lIFNsaW0gV2FsbGV0IiwidXJsIjoiaHR0cDpcL1wvd3d3LnlvdXJzaXRlLmNvbVwvVTAwNDY3Lmh0bWwiLCJza3UiOiJVMDA0NjcifV0sIm9yZGVyRGF0ZSI6IjIwMTUtMDUtMTUiLCJkZWxpdmVyeURhdGUiOiIyMDE1LTA1LTIwIiwiaWF0IjoxNTE2ODA5MzA4LCJ1c2VyIjp7ImZpcnN0TmFtZSI6IkFuZHkiLCJsYXN0TmFtZSI6IkFkYW1zb24iLCJuaWNrTmFtZSI6bnVsbCwiZW1haWxBZGRyZXNzIjoiYW5kcmV3QHNhbXBsZS5jb20ifSwib3JkZXJJZCI6Ijk5OTc3In0.PBG3PIJ5h8PauRyXP2rFhHGrSkjxAqNnIPDMIlrPpW4

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",
   "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",
   }
   ]
}

URL base path

Parameters

The turntoOrdJWT parameter

1. Create the JWS Header

2. Create the JWS Payload

3. Compute the JWS Signature

4. Create the JWT token

Creating a signed JSON Web Token

Verifying generated JWT tokens

Seller Rating Solicitation Email URL example

Configuration for site groups

Additional External Resources

The `turntoOrdJWT` parameter