Dynata API guide

Also covered on docs.gradientmetrics.com here

Step 0: Credentials

Make sure you have the following credentials specified in your .Renviron file

DYNATA_API_HOST = https://api.researchnow.com
DYNATA_CLIENT_ID = api
DYNATA_USERNAME = gradient_metrics_sample_api
DYNATA_API_PASSWORD = Dyn4tAf0reVA!![;]

QUALTRICS_APITOKEN = ADD_YOURS
QUALTRICS_USER_ID = ADD_YOURS
QUALTRICS_DATACENTERID = gradientmetrics.az1

Step 1: Load packages

Install and load g6tr.api. Make sure you update the path (e.g., 'packages/g6tr').

# you can install packages with
devtools::install('path_to/g6tr.api', quick = TRUE, upgrade = 'never')
library(g6tr.api)

Step 2: Set up project

Use g6tr_newsletter_setup to setup an R, AWS, and Qualtrics project

# example from October Newsletter
library(g6tr.api)
g6tr_newsletter_setup(survey_topic_title = 'October_Newsletter', 
                      branch = 'voice/newsletter/2020-10', 
                      qualtrics_redirects = 'production', 
                      qualtrics_name = 'October Newsletter')
# survey_topic_title  is used for directories names on AWS and in R

branch will create a new branch, so give the branch a meaningful name.
- remember to be on a master branch when running the code
When you run the function, you will automatically be moved to the new branch and a new vignette is created for you under 'g6tr/packages/g6tr.voice/newsletter'. It will take a moment to copy all packages into the new cache.
Upon completion, the working directory will be changed for you.

Step 3: Update survey

In most cases survey is already programmed before you setup Dynata project so just skip this section.

Update Qualtrics survey

Make sure you do the following:

Collaborate so that all team members have access to the Qualtrics survey
Program the Qualtrics survey

After you are done programming the survey

Set the desired number of responses in Quotas
- Go to Tools → Quotas
Start the survey
- Go to Distributions → Get a single reusable link

Step 4: Set up Dynata project

Set up Dynata project from R

Make sure you add your .Renviron file. Use file.create('.Renviron') followed by file.edit('.Renviron'), add your credentials and then use readRenviron('.Renviron') to read them.
You should have this new password DYNATA_API_PASSWORD = Dyn4tAf0reVA!![;]
Locate the R project folder you created - it should be located under 'g6tr/packages/g6tr.voice/vignettes'
Use dynata_newsletter_config to setup Dynata project specification JSON

dynata_newsletter_config(
  file = '2020-12-03_december_newsletter_dynata_specs.json',
  project_id = 'DecemberTrendlines01', # name used on Dynata side
  survey_url = 'https://gradientmetrics.az1.qualtrics.com/jfe/form/SURVEY_ID'
)
# survey_url should be the actual url to qualtrics survey that was created
# when running g6tr_newsletter_setup

# NOTE
# g6tr_newsletter_setup created a urls.yml file that contains below urls
# qualtrics_survey should be passed as 'survey_url' in dynata_newsletter_config
aws_bucket: s3://monorepo-data/newsletter/2020-09_October_Newsletter
qualtrics_project_id: SV_1ByJRddt9IFRQkB
qualtrics_project: https://gradientmetrics.az1.qualtrics.com/Q/EditSection/Blocks?ContextSurveyID=SV_1ByJRddt9IFRQkB
qualtrics_survey: https://gradientmetrics.az1.qualtrics.com/jfe/form/SV_1ByJRddt9IFRQkB

Update SURVEY_ID at the end of the survey url — to do so, you can simply copy & paste the single reusable link from Qualtrics next to survey_url = 'Qualtrics reusable link'
JSON file MANUAL ADDITIONS
- Make sure lengthOfInterview (LOI) and incidence rate are properly set (lines 18-20)
- Change notifications e-mail if you want to notify the whole team (line 5)
```
# e.g., from
"notificationEmails": ["marcin@gradientmetrics.com"],
# to
"notificationEmails": ["marcin@gradientmetrics.com", "team@gradientmetrics.com"],
```

Step 5: Create the project

Use dynata_project_create to launch the project

dynata_project_create(
  file = '2020-12-03_december_newsletter_dynata_specs.json', 
  auth = dynata_auth(TRUE)
)

And once the project is created, you can check the feasibility using dynata_project_feasibility

dynata_project_feasibility(
  project_id = 'DecemberTrendlines01', 
  auth = dynata_auth(TRUE)
)

Make sure you update the project_id to match whatever you entered earlier using dynata_newsletter_config

If it is not returning errors you can buy the project, but first check redirects!

Step 6: Test redirect URLs

Test the Dynata+Qualtrics integration with a customized URL. Use dynata_newsletter_url to test the redirects. The following snippet should produce a url that you can enter to test redirects

dynata_newsletter_url(
  project_id = 'DecemberTrendlines01', # dynata_project_id
  survey_url = 'https://gradientmetrics.az1.qualtrics.com/jfe/form/SURVEY_ID' # qualtrics_survey_url
)

Paste the url into your browser and run through the survey to ensure the redirects are working properly

If your test is successful, you should be able to see ‘Test Successful’ in the end screen
If not, this means something is wrong with your redirect URLs
- Then keep looking at the redirect setup for screen-outs, overquotas and regular completes in Survey Flow and Quotas
- They should follow this redirects scheme

Step 7: Buy Dynata project

dynata_project_buy(
  auth = dynata_auth(TRUE),
  project_id = 'extProjectId',
  file = 'specificatio.json'
)