Cookie vignette

.gitignore

@@ -3,3 +3,4 @@
 .RData
 .Ruserdata
 docs
+inst/doc

DESCRIPTION

@@ -22,6 +22,8 @@ Imports:
     styler
 Suggests: 
     diffviewer,
+    knitr,
+    rmarkdown,
     shinytest2,
     testthat (>= 3.0.0)
 Config/testthat/edition: 3
@@ -30,3 +32,4 @@ Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.3.1
 URL: https://dfe-analytical-services.github.io/dfeshiny/
      https://www.github.com/dfe-analytical-services/dfeshiny/
+VignetteBuilder: knitr

README.md

@@ -24,65 +24,6 @@ If this works, then you will need to look for where that "GITHUB_PAT" variable i
 
 ## Using this package in a DfE data dashboard
 
-### Adding cookies to your dashboard
-
-dfeshiny provides the facility to add a gov.uk styled cookie banner to your 
-site, which is fully functional in terms of controlling the user permissions for
-tracking their use of the site via Google Analytics.
-
-Before adding the cookie consent banner, you will need to obtain a Google 
-Analytics key that's both unique to your app and stored within the DfE Google
-Analytics domain. You can request a key from the 
-[Statistics Development team](mailto:[email protected]). 
-This should then be added as a variable to your dashboard's 
-[global.R](https://github.com/dfe-analytical-services/dfeshiny/blob/cookie-module/tests/test_dashboard/global.R) 
-file (replacing `ABCDE12345` below with the key provided by the Statistics 
-Development team):
-
-```
-google_analytics_key <- 'ABCDE12345'
-```
-
-Next, you should copy the javascript file
-([cookie_consent.js](https://raw.githubusercontent.com/dfe-analytical-services/dfeshiny/cookie-module/js/cookie-consent.js)) 
-necessary for controlling the cookie storage in the user's browser to the `www/` 
-folder in your dashboards repository.
-
-Once you've made the above updates, add the following lines to your 
-[ui.R](https://github.com/dfe-analytical-services/dfeshiny/blob/cookie-module/tests/test_dashboard/ui.R) 
-script (updating "My DfE R Shiny data dashboard" with the name of your app):
-
-```
-dfe_cookie_script(),
-cookie_banner_ui("cookies", name = "My DfE R Shiny data dashboard"),
-```
-
-Putting these on the lines *just before* the `shinyGovstyle::header(...)` line 
-should work well.
-
-Then add the following code to your
-[server.R](https://github.com/dfe-analytical-services/dfeshiny/blob/cookie-module/tests/test_dashboard/server.R) 
-script somewhere *inside* the `server <- function(input, output, session) {...}` 
-function (you shouldn't need 
-to change anything in this one):
-
-```
-output$cookie_status <- dfeshiny::cookie_banner_server(
-  "cookies",
-  input_cookies = reactive(input$cookies),
-  input_clear = reactive(input$cookie_consent_clear),
-  parent_session = session,
-  google_analytics_key = google_analytics_key
-)
-```
-
-Finally, you should make sure you're using the `dfeshiny::support_panel()` 
-function within the `navListPanel(...)` in your 
-[ui.R](https://github.com/dfe-analytical-services/dfeshiny/blob/cookie-module/tests/test_dashboard/ui.R) 
-script as this will provide
-users with the necessary explanatory text on how we use cookies and the ability 
-to change their decision on whether or not to accept the use of cookies.
-
 ### Adding a custom disconect message to your dashboard
 
 dfeshiny provides a function to add a custom disconnect message to your dashboard - this will appear when a dashboard would otherwise 'grey-screen' and will include options to refresh the page, go to overflow sites or visit the publication directly on Explore education statistics. 

tests/test_dashboard/www/cookie-consent.js

@@ -4,7 +4,7 @@ function getCookies(){
 }
 
 Shiny.addCustomMessageHandler('cookie-set', function(msg){
-  Cookies.set(msg.name, msg.value);
+  Cookies.set(msg.name, msg.value, { expires: 365 });
   getCookies();
 })
 

vignettes/.gitignore

@@ -0,0 +1,2 @@
+*.html
+*.R

vignettes/implementing-cookies.Rmd

@@ -0,0 +1,89 @@
+---
+title: "Implementing cookie consent"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Implementing cookie consent}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+Cookie consent is a mandatory requirement for any dashboard when using cookies. 
+Typically, all DfE dashboards will be using cookies as part of tracking with
+Google Analytics and so will require cookie consent.
+
+> Note that to activate Google Analytics on your data dashboard, you will need 
+to contact the Statistics Development team at 
+[[email protected]](mailto:[email protected]) and request a Google Analytics key.
+
+dfeshiny provides a standard GDS compliant banner, plus the underlying code, to
+allow end users to give or withhold their consent for cookies to be used. If 
+they withhold their consent, then tracking with Google Analytics will be halted.
+
+Implementing cookie control on your dashboard is handled by several functions 
+in dfeshiny, with the process outlined below.
+
+The cookie control requires some underlying javascript to remove and create 
+cookies as well as switch Google Analytics on and off. This javascript needs 
+including in your dashboard's www/ folder, which can be achieved by running the 
+following command from the R console:
+
+```{r eval=FALSE}
+dfeshiny::init_cookies()
+```
+
+Before adding the cookie consent banner, we recommend adding your Google 
+Analytics key as a variable to your dashboard's [global.R](https://github.com/dfe-analytical-services/dfeshiny/blob/cookie-module/tests/test_dashboard/global.R) 
+file (replacing `ABCDE12345` below with the key provided by the Statistics 
+Development team):
+
+```
+google_analytics_key <- 'ABCDE12345'
+```
+
+You will then need to add the necessary code to your ui.R file to a) run the 
+javascript, b) create the consent banner and c) add a cookies information panel:
+
+
+```{r eval=FALSE}
+ui <- function(input, output, session) {
+  fluidPage(
+    shinyjs::useShinyjs(),
+    dfe_cookie_script(),
+    cookie_banner_ui("Your dashboard name"),
+    ...
+    cookies_panel()
+  )
+}
+```
+
+You should then add the `cookie_banner_server` function to your server.R script:
+
+```{r eval=FALSE}
+cookie_banner_server(
+   "cookies",
+   input_cookies = reactive(input$cookies),
+   input_clear = reactive(input$cookie_consent_clear),
+   parent_session = session,
+   google_analytics_key = google_analytics_key
+)
+```
+
+In the above you should keep all of the flags as they are shown. Note that this 
+assumes you have added `google_analytics_key` as a declared variable in your 
+global.R file. If you've not done this, you'll need to replace 
+`google_analytics_key = google_analytics_key` to 
+`google_analytics_key = "ABCDE12345"` (replacing "ABCDE12345" with your own 
+key).
+
+With the above included, when the user's preference will itself be stored in a
+cookie (`dfe_analytics`), which by default expires after 365 days. The user can
+then also find information about the cookies stored by your dashboard and change 
+their consent preference on a specific cookie consent panel on your dashboard 
+that's created by the `cookies_panel()` function.