Link website widget answers to known visitors

On the Growth plan and up, the widget can tell SurveyRock who a signed-in visitor is, so their answer is linked to their contact. Workflows then have the respondent’s email ({{trigger.response.email}}), and HubSpot, Zendesk and Freshdesk steps find the person as they do for an email invitation.

So that nobody can claim to be someone else from a browser console, your server signs the identity with the Website’s identity secret. It’s shown once, when you add the Website; store it with your other server secrets. A Website without one has a Make a secret button.

On your page

SurveyRock('identify', {
  userId: 'u_123',
  email: 'ana@example.com',
  traits: { plan: 'pro' },
  signature: '…'   // made by your server, below
});

Either userId or email may be empty, but not both. traits are kept with the answer as embedded data (up to 50, each up to 500 characters; names of letters, digits and _). They aren’t signed: they describe the visitor, they don’t say who they are. To filter or crosstab answers by a trait such as plan, add an embedded data field to the survey with the trait’s name as its key (keys are lowercase, so name the trait in lowercase too). Traits can also decide who sees a widget: see Visitor details.

The signature

The signature is HMAC-SHA256, with the identity secret as the key, of v1: + userId + : + the email trimmed and lowercased, as lowercase hex.

Node:

const crypto = require('crypto');
const signature = crypto.createHmac('sha256', process.env.SURVEYROCK_IDENTITY_SECRET)
  .update(`v1:${userId}:${email.trim().toLowerCase()}`)
  .digest('hex');

PHP:

$signature = hash_hmac('sha256', 'v1:' . $userId . ':' . strtolower(trim($email)), getenv('SURVEYROCK_IDENTITY_SECRET'));

Python:

import hashlib, hmac, os
signature = hmac.new(os.environ["SURVEYROCK_IDENTITY_SECRET"].encode(),
                     f"v1:{user_id}:{email.strip().lower()}".encode(), hashlib.sha256).hexdigest()

Ruby:

require 'openssl'
signature = OpenSSL::HMAC.hexdigest('SHA256', ENV['SURVEYROCK_IDENTITY_SECRET'], "v1:#{user_id}:#{email.strip.downcase}")

What SurveyRock keeps

• Signed, with an email: the answer is linked to the contact with that email, made if needed (it counts towards your plan’s contacts). The user id and traits are kept with it.
• Signed, no email: the user id and traits.
• Not signed, or signed wrongly: the user id and traits, marked sr_identity = unverified. The email is not kept and no contact is linked.
• Contact limit reached, or the address is on your suppression list: the answer is kept and marked verified_unlinked; it isn’t linked.
• An anonymous survey: nothing about the visitor, whatever the page sends.

The identity goes from your page to the survey frame by a browser message. It never appears in a URL and is never stored in the visitor’s browser.

Change the secret

Make a new secret on the Website. The old one keeps working until you click Stop accepting the old secret, so your site keeps working while you deploy the new one.

New to the widget? Start with Add the website widget to your site.