Dynata Link Embedding with surveydown

A brief tutorial on how to embed Dynata links in your surveydown survey.

1 Motivation

When you have your survey link ready, you might want to cooperate with Dynata to recruit your survey. Dynata has 2 link checkpoints:

1. Validate the Starting Link
2. Redirect to the Ending Link

The Starting Link ensures that the respondent is legitimate, and the Ending Link redirects them to the correct ending pages that Dynata prepares based on your designed filtering mechanism.

The Starting Link is ALREADY there as provided by Dynata. You just need to capture the values and validate it. There is one unique Starting Link for each respondent.

The Ending Link, on the other hand, should be generated by you as a redirection link back to Dynata. Usually there should be 3 types of Ending Links: “Complete”, “Screenout”, and “Quotafull”. Each of them has a different rst value in the link. We’ll talk about them later.

This tutorial is based on my previous experience of cooperating with Dynata, in which case I used formr and defined the related values and mechanisms in the XML files and the survey runs. Our lab has now moved on with surveydown, which is granted with similar capabilities that handle the starting and completion links as required by Dynata.

2 Starting Link (Your Survey Link with Dynata IDs)

2.1 Basic Example

Say you have an original survey link, how about the Google official website: https://www.google.com. Say we have 3 IDs and let’s call them id_a=xxx, id_b=xxx, and id_c=xxx. Then let’s assign them as parameters in the URL, like this:

https://www.google.com/?id_a=xxx&id_b=xxx&id_c=xxx

Let’s break down the link:

• https://www.google.com
• /?
• id_a=xxx
• &
• id_b=xxx
• &
• id_c=xxx

Actually you can click on this link. You’ll see this exact link in your browser’s URL part, and it is no different from the original https://www.google.com link.

2.2 Dynata’s Case

Tip

Your Dynata specialist will assign you 2 values (Come back to this part after you’ve done reading the rest):

1. A _k value. It’s usually a 4-digit number. Save it.
2. A Secure Key, which is a long string of hex values (0-9 and a-f). This is used to generate the _s value with HMAC-SHA256 encryption. The Secure Key is ONLY used in the HMAC-SHA256 encryption and nowhere else.

The starting link of Dynata has the same structure. Dynata has these IDs:

• psid: Unique ID for each respondent (aka survey participant).
• _k: short for keyID, unique ID for each client (aka survey creator, in short, you).
• _s: short for Starting Signature, unique ID for each respondent, HMAC-SHA256 Encrypted. This is a bit complicated. I’ll explain it later.

Therefore, as you deploy your survey URLs, your psid and _s are all unique for each respondent, but _k stays the same.

Here is a pseudo-example of a Dynata starting link:

https://www.mysurvey.com/?psid=xxx&_k=xxx&_s=xxx

Let’s break down the link:

• https://www.mysurvey.com
• /?
• psid=xxx
• &
• _k=xxx
• &
• _s=xxx

2.3 Starting Signature (_s)

The _s value, aka the starting signature, is the most complicated part of the Dynata starting link, and I chose to explain it separately in this sub-section.

You need these recipes to generate the Starting Signature (_s):

1. The string AFTER the survey URL and BEFORE the &_s=xxx part, aka /?psid=xxx&_k=xxx.
2. Your Secret Key provided by Dynata, which is a long string of hex values (0-9 and a-f).
3. The HMAC-SHA256 encryption algorithm.

If you wanna test the HMAC-SHA256 encryption, you can use the HMAC-SHA256 Hash Generator.

With R, you can use the digest package to generate the _s value. Here is how:

# To generate the Starting Signature (_s)
library(digest)
signature_start_validate <- hmac(
    key       = secret_key, # Your Dynata Secure Key
    object    = text_start, # The /?psid=xxx&_k=xxx part
    algo      = "sha256",   # Don't change
    serialize = FALSE       # Don't change
    )

The reason why I call it signature_start_validate is because it’s a validation process. The starting signature _s is already generated by Dynata in the starting link. You need to capture that _s from the URL, save it as maybe signature_start, and validate with this signature_start_validate value, so that you need to check if signature_start == signature_start_validate.

Tip

To make your life easier, _s, signature_start, and signature_start_validate are all the same (if the validation is successful).

If they don’t match, this respondent should be filtered out. The whole purpose of the _s value is this: to ensure legitimate respondents who really click on the link provided by Dynata.

3 Ending Link (Redirected Link to Dynata)

Dynata has a URL structure for the ending link: https://dkr1.ssisurveys.com/projects/end?rst=1&psid=xxx&_k=xxx&_s=xxx.

Let’s break down the link:

• https://dkr1.ssisurveys.com/projects/end (This is the base URL for Dynata’s ending link. Don’t change this part.)
• ?rst=1 (This is the indicator of completion, in which 1 means complete, 2 means screenout, and 3 means quotafull.)
• &
• psid=xxx
• &
• _k=xxx
• &
• _s=xxx (This is the ending signature, which is also HMAC-SHA256 encrypted.)

3.1 Ending Signature (_s)

Important

Now the tricky part is _s, which still using the same ID name as the Starting Signature, but this time it’s called the Ending Signature. It is different from the Starting Signature, and it is also HMAC-SHA256 encrypted.

There are 3 types of ending scenarios: “Complete”, “Screenout”, and “Quotafull”, each of them has an _s value.

Therefore, there are actually 4 possible _s values: one Starting Signature and up to three Ending Signatures.

You need these recipes to generate the Ending Signatures (_s):

1. The scenario of “Complete”: /projects/end?rst=1&psid=xxx&_k=xxx.
2. The scenario of “Screenout”: /projects/end?rst=2&psid=xxx&_k=xxx.
3. The scenario of “Quotafull”: /projects/end?rst=3&psid=xxx&_k=xxx.
4. Again, your Secret Key provided by Dynata.
5. The HMAC-SHA256 encryption algorithm.

Again, if you wanna test the HMAC-SHA256 encryption, you can use the HMAC-SHA256 Hash Generator.

With R, you can use the digest package to generate the _s values. Here is how:

# To generate the Ending Signature (_s)
library(digest)
signature_end <- hmac(
    key       = secret_key, # Your Dynata Secure Key
    object    = text_end, # The /projects/end?rst=x&psid=xxx&_k=xxx part
    algo      = "sha256",   # Don't change
    serialize = FALSE       # Don't change
    )

4 What You Should Do

So in the end, what you should do? Here is a walk-through:

4.1 Starting Link Validation

Note

Again, the Starting Link is ALREADY there as provided by Dynata. You just need to capture the values and validate it.

1. Capture the psid, _k, and _s values from your Starting Link. They are the PSID, keyID, and Starting Signature, respectively.
2. If the psid is empty or there is no psid, filter out this respondent.
3. Create a text_start variable with the value of /?psid=xxx&_k=xxx, where xxx are the psid and _k values you just captured.
4. Create a secret_key variable with the value of your Dynata Secure Key.
5. Create a signature_start_validate variable with the HMAC-SHA256 encryption. You can just use the R scripts I provided in the Starting Signature section.
6. Valide if signature_start == signature_start_validate. If they match, you can proceed with the survey. If not, filter out this respondent.

4.2 Ending Link Redirection

Note

And again, the Ending Link, on the other hand, should be generated by you as a redirection link back to Dynata.

1. Reuse your previously captured psid and _k values.
2. Create a text_end_1 variable for “Complete” responses, with the value of /projects/end?rst=1&psid=xxx&_k=xxx, where xxx are the psid and _k values.
3. Create a text_end_2 variable for “Screenout” responses, with the value of /projects/end?rst=2&psid=xxx&_k=xxx.
4. Create a text_end_3 variable for “Quotafull” responses, with the value of /projects/end?rst=3&psid=xxx&_k=xxx.
5. Reuse your previously stored secret_key variable.
6. Create a signature_end_1 variable for the “Complete” ending signature (_s) with the HMAC-SHA256 encryption of text_end_1. You can just use the R scripts I provided in the Ending Signature section.
7. Create a signature_end_2 variable for the “Screenout” ending signature (_s) with the HMAC-SHA256 encryption of text_end_2.
8. Create a signature_end_3 variable for the “Quotafull” ending signature (_s) with the HMAC-SHA256 encryption of text_end_3.

Here are the R codes you can use (in {surveydown}, the sd_redirect() function is used to generate the redirection links):

4.3 Example R Codes

# Server setup
server <- function(input, output, session) {
  ### Start of Dynata setup ###

  # Save your secret key in the .env file
  secret_key <- Sys.getenv("SECRET_KEY")

  # Obtain parameters from the URL
  url_pars <- reactive({sd_get_url_pars()})
  psid <- reactive({url_pars()["psid"]})
  keyid <- reactive({url_pars()["_k"]})
  signature_start <- reactive({url_pars()["_s"]})

  # Starting Link Validation
  is_valid_start <- reactive({
    # Get the current URL path (everything after the domain)
    url_path <- session$clientData$url_pathname
    text_start <- paste0(url_path, "?psid=", psid(), "&_k=", keyid())
    signature_start_validate <- hmac(
      key = secret_key,
      object = text_start,
      algo = "sha256",
      serialize = FALSE
    )
    !is.na(psid()) &&
      psid() != "" &&
      (signature_start() == signature_start_validate)
  })

  # Create ending links
  ending_links <- reactive({
    # Ending texts for "Complete", "Screenout", and "Quotafull"
    text_end_1 <- paste0("/projects/end?rst=1&psid=", psid(), "&_k=", keyid())
    text_end_2 <- paste0("/projects/end?rst=2&psid=", psid(), "&_k=", keyid())
    text_end_3 <- paste0("/projects/end?rst=3&psid=", psid(), "&_k=", keyid())

    # Ending signatures (_s) for "Complete", "Screenout", and "Quotafull"
    signature_end_1 <- hmac(
      key = secret_key,
      object = text_end_1,
      algo = "sha256",
      serialize = FALSE
    )
    signature_end_2 <- hmac(
      key = secret_key,
      object = text_end_2,
      algo = "sha256",
      serialize = FALSE
    )
    signature_end_3 <- hmac(
      key = secret_key,
      object = text_end_3,
      algo = "sha256",
      serialize = FALSE
    )

    # Ending links of "Complete", "Screenout", and "Quotafull"
    list(
      complete = paste0(
        "https://dkr1.ssisurveys.com/projects/end?rst=1&psid=",
        psid(),
        "&_k=",
        keyid(),
        "&_s=",
        signature_end_1
      ),
      screenout = paste0(
        "https://dkr1.ssisurveys.com/projects/end?rst=2&psid=",
        psid(),
        "&_k=",
        keyid(),
        "&_s=",
        signature_end_2
      ),
      quotafull = paste0(
        "https://dkr1.ssisurveys.com/projects/end?rst=3&psid=",
        psid(),
        "&_k=",
        keyid(),
        "&_s=",
        signature_end_3
      )
    )
  })

  ## Redirect buttons
  sd_redirect(
    id = "redirect_complete",
    url = ending_links()$complete,
    button = TRUE,
    label = "Back to panel"
  )

  sd_redirect(
    id = "redirect_screenout",
    url = ending_links()$screenout,
    button = TRUE,
    label = "Back to panel"
  )

  sd_redirect(
    id = "redirect_quotafull",
    url = ending_links()$quotafull,
    button = TRUE,
    label = "Back to panel"
  )

  ### End of Dynata set up ###

  # Rest of the server logic...
}

5 Other Resources

5.1 A Working Template of External Redirect

Start with the Extrenal Redirect template. This is a working template without HMAC-SHA256 encryption. It has the basic components of a survey that redirects to an external link. You can modify it to fit your Dynata needs.

5.2 Dynata Official Documentation

Check out the full official guidance form Dynata here.