Surveys - Generating personalized links

Client hotel can send the link to the survey themselves.

The link has the following format:

https://survey.reviewpro.com/feedback/mail?<query-params>

Request Type: GET

Instead of survey.reviewpro.com client can use any host name, as long as all the request to that host name are forwarded to survey.reviewpro.com.

Parameters

Encryption of the link 

For security or privacy reasons you can decide to encrypt the link, to hide the parameters passed on in the URL. ReviewPro supports the secure Rijndael 256-encryption. To be able to encrypt links in a proper way for ReviewPro to be able to ‘read’ them you need the following:

• Encryption key of 20 characters: this will be provided by ReviewPro, for this you can contact reviewpro.integrations@shijigroup.com.
• Encryption secret of 24 characters: this will be provided by ReviewPro, for this you can contact reviewpro.integrations@shijigroup.com.
• The base url: https://survey.reviewpro.com/feedback/mail
• For the encryption, please use an IV of NULLs, a padding of 32 and CBC and make sure to urlencode plus base64encode the result of the encryption before adding it to the full link.

You would encrypt all parameters with guest-data that would typically go into a survey-link:

“?email=john.doe@example.com&checkin=2022-09-20&checkout=2022-09-25&firstName=John&language=en&lastName=Doe&pmsId=1234&room=123&roomType=suite&surveyId=2265e0a6bc5 d5639ea646fe0&view=desktop”

A typical encrypted link would look like: https://survey.reviewpro.com/feedback/mail?encryption=Rijndael&apiKey=<encryption-key>&key=<encrypted guest data>

IMPORTANT NOTE RELATED TO SALESFORCE: For the creation of encrypted links to be sent from within Salesforce (MarketingCloud) there is currently no encryption method available due to limitations of the encryption module of Salesforce/MarketingCloud. A workaround has to be used, creating the links outside SF/MC and store them with the reservation-data to be used within invitation emails as a dynamic insert.

Signature generation for non-encrypted links 

sig is a HMAC using a secret key and SHA256 message digest algorithm. It takes as an input all query parameters concatenated in the alphabetical order by key (where UPPERCASE goes before lowercase): apiKey, checkin, checkout, email, firstName, lastName, pmsId, surveyId, etc. The secret key can be obtained from your Mashery account settings. Please note that although the parameters will need to be URLENCODE in the final URL, they are not URLENCODE to calculate the sig.

Example

Assuming that the url has parameters:

• apiKey = "23675469989xxhy0"
• checkin = "2014-01-01"
• checkout = "2014-01-02"
• email = "aaa@bbb.com"
• firstName = "John"
• lastName = "Doe"
• LoyaltyNumber = "23445"
• pmsId = "53770"
• surveyId = "UtjT-oSiRJoMGL-k"

The concatenated string (all the parameters in alphabetical order, where UPPERCASE goes before lowercase, the parameters overall and nps are never included in this string) to encode is:

2344523675469989xxhy02014-01-012014-01-02aaa@bbb.comJohnDoe53770UtjT-oSiRJoMGL-k

If you example shared key is "ABC", the sig will be:

fa5bd997dfadd787b6bc673233cbbc1ef6a4cb121332821b047ec36e90f1c639

You can test HMAC + HA256 generation via online tools like http://www.freeformatter.com/hmac-generator.html.

The final URL with sig appended will read:

https://survey.reviewpro.com/feedback/mail?apiKey=23675469989xxhy0&checkin=2014-01-01&checkout=2014-01-02&email=aaa@bbb.com&firstName=John&lastName=Doe&pmsId=53770&surveyId=UtjT-oSiRJoMGL-k&LoyaltyNumber=23445&sig=fa5bd997dfadd787b6bc673233cbbc1ef6a4cb121332821b047ec36e90f1c639

Including NPS or Overall in invitation emails 

ReviewPro supports having either an NPS or Overall question directly in the invitation email to increase the response ratio. The chosen score from the email wll be prefilled in the survey when opening the survey in the webbrowser. The score of NPS or Overall are specific parameters which should be passed in the links in the invitation mail.

We have two types of urls, encrypted and not encrypted :  

• Encrypted  

In this case the "nps" or "overall" must be explicitly in the url as in https://survey.reviewpro.com/feedback/mail?encryption=Rijndael&apiKey=<apiKey>&key=<key>&nps=2  

Example: https://survey.reviewpro.com/feedback/mail?encryption=Rijndael&apiKey=fa06db18a46c4aadab94&key=HyH7UCgA7LVHXJcCaDDIzRoLIj%2fJph8cXHdqwt0hsmcRp4ApjLqY1Pyr0JgkWWJPGugIzmUOme0hWqiBBUAkkc4j3DY%2fBDV%2fdRB3LwQRzeiq%2bqVPYPMJIBtg%2b4dm4yw0i5dTofjqBV7Y6MlfTL5zS2sJSggDl5BvbCYa1KduJRJ%2fTR6K5InM6d1Q2O8%2fEn8wfzC8Ips8cGXFDGiAsVCkoRC5yhfaDqOhk5WL8xO6ckzvPofeLFCOhcrWZpcgZC%2f7CQeDRa6%2bl%2bVk0DO%2bJv2W8haEgtTi7PTJp7Frfnr6Wg9DLgIAZUv7XQ5TsL0Fou434uXQDzWIw%2bydTvs1%2bB1n5NHhYKoswEqcFSx%2bo9rgFQyFbjkQ0ir7RoZCkw5zpRsFMWapI06CLhY%3d&nps=2

• Not Encrypted  

In this case the "nps" or "overall" must be explicitly in the url, but the signature ("sig" param) must be generated WITHOUT this new param as in https://survey.reviewpro.com/feedback/mail?apiKey=<apiKey>&<...params>&nps=2&sig=<sig>  

Example: https://survey.reviewpro.com/feedback/mail?apiKey=gprfv4c4w2tks8j87kp346xhzj5s6cwyksswma43&checkin=2017-12-17&checkout=2017-12-18&email=dummy@wynnpalace.com&firstName=Dummy&language=ja&lastName=Dummy&pmsId=WPM&surveyId=5a1f6ec7117072d6cf023031&confirmationId=2222&country=JP&view=desktop&sig=137d6f37ef77ea9da21823b04c0c2fc7735c1af56f66b0a07f13656ddadd3106

The following Python script can be used to calculate sig. It accepts two parameters: api shared secret and the survey url without the sig parameter, and outputs sig to the console.

import hmac
import hashlib
from urlparse import urlparse, parse_qs
import sys

o = urlparse(sys.argv[2])
params = parse_qs(o.query)

s = ''.join(''.join(sorted(v)) for _, v in sorted(params.items()))

sig = hmac.new(sys.argv[1], msg=s, digestmod=hashlib.sha256).hexdigest()

print sig

Another example of sig generation in Java

String key = "whatever"
TreeMap<String, String> sortedParams = new TreeMap<>();
sortedParams.put("surveyId", "45fa3453g");

StringBuilder sb = new StringBuilder();
for (Map.Entry<String, String> param : sortedParams.entrySet()) {    
	sb.append(param.getValue());
}

 String algorithm = "HmacSHA256";
Charset charset = Charset.forName("UTF-8");
Mac hmac = Mac.getInstance(algorithm);
SecretKey secretKey = new SecretKeySpec(key.getBytes(charset), algorithm);
hmac.init(secretKey);
 
byte[] b = sb.toString().getBytes(charset);
String sig = Hex.encodeHexString(hmac.doFinal(b));

Testing

Parameters can be tested using the following url: 

https://survey.reviewpro.com/feedback/mail/testParams?<query-params>

Request Type: GET

It takes the same query parameters as the survey url.