-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
94 lines (65 loc) · 4.26 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
<!-- badges: start -->
[](https://github.com/ppssphysics/QualtricsInR/actions)
<!-- badges: end -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%")
library(QualtricsInR)
set_qualtrics_opts(Sys.getenv("QUALTRICSINR_TEST_TOKEN"))
```
You can find the official documentation [here](https://qualtrics.psaouter.com/).
# QualtricsInR
The **QualtricsInR** package provides a general R wrapper for the Qualtrics [API v3 references](https://api.qualtrics.com/reference). The package is built accross the main API calls
to manipulate survey objects and responses, as well as general survey and account admnistration functions.
The package was created in order to address the needs of large scale survey projects where the management and handling of multiple surveys can benefit from automation through the API.
- [Installation](#installation)
- [Authenticatication](#authentication)
- [Development Pipeline](#dev-pipeline)
There are other important R packages available to automate different aspects of survey manipulation in Qualtrics. The [qualtRics](https://github.com/ropensci/qualtRics) R package implements
the retrieval of survey data using the Qualtrics API and is currently the only package on CRAN that offers such functionality.
Other related packages are available through Github. [Jason Bryer's](https://github.com/jbryer/qualtrics) R package to work with the previous version of the Qualtrics API.
[QualtricsTools](https://github.com/emmamorgan-tufts/QualtricsTools/) creates automatic reports in shiny and [qsurvey](https://github.com/jamesdunham/qsurvey), by James Dunham,
focuses on testing and review of surveys before fielding, as well as the analysis of responses afterward.
## Getting Started
You can install QualtricsInR from github using the devtools package.
``` r
devtools::install_github('ppssphysics/QualtricsInR')
```
The package is made available on GitHub in order to collect feedback from the community before we consider a submission to CRAN.
### Authentication
We provide two authentication methods to set-up your Qualtrics credentials:
1. Using a plain Token
2. Using the OAuth 2.0
Both are valid methods. All information on how to retrieve identification parameters and
generete tokens from your Qualtrics account can be found [here](https://api.qualtrics.com/v3/docs/api-general-instructions).
### Setting a plain text API Token
For convenience, we recommend you define your API token and Qualtrics Data Center ID (optional) in your .Renviron with the names `QUALTRICSINR_TOKEN` and `QUALTRICSINR_DATA_CENTER` respectively.
Upon loading the QualtricsInR package, your credentials will be automatically set as internal _encrypted_ parameters.
You can always custom set your credentials by calling the `set_qualtrics_opts()` function:
```r
# set auth options assuming definition in .Renviron
set_qualtrics_opts()
# set auth options by hand
set_qualtrics_opts("9ssssss83jsl83282032932sds2", "mydatacenter")
```
If you use this method, you will have set your credentials for every new session.
### Setting-up an OAuth Client Manager
To generate an OAuth application, follow the steps below in your Qualtrics account:
1. Go to Account Settings
2. Create an OAuth application
3. Use the client id, client secret, and data center id in `qualtrics_auth`, as below.
```r
qualtrics_auth(id = "xXxxX0X0x", secret = "xXxxX0X0x", data_center = "my.center")
```
This will authenticate you, returning a bearer token valid for one hour, saving the _encrypted_ credentials in a `.qualtrics-oauth` file, which will be automatically
loaded in all subsequent sessions and automatically refreshed if need be. You should therefore only find the need to run `qualtrics_auth` once.
## Development pipeline
There are close to 200 different API calls provides by Qualtrics. Depending on interest, demand, and help from the community, efforts will be dedicated to the testing and implementation of missing references. Most of the XM
Directory related calls are not implemented due to not having access to this feature in our own account.