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. 
@@ -175,6 +116,6 @@ devtools::check() # Ctrl-Shft-E
 shinytest2::test_app("tests/test_dashboard") # important as not currently ran in CI checks, need to move this over
 
 # For code styling
-styler::style_pkg() # currently has a known error on cookies.R
+styler::style_pkg() 
 lintr::lint_package()
 ```

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,116 @@
+---
+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 = "#>"
+)
+```
+
+Cookies are chunks of data that are stored by browsers to help websites store 
+user preferences and other information. Most of our DfE data dashboards 
+generally store two cookies, one to allow Google Analytics to differentiate 
+between unique users and returning users and the second to store a user's 
+preference on whether they allow the use of the Google Analytics (or any 
+additional custom) cookies.
+
+Assuming a dashboard is set up with at least the Google Analytics cookie, then 
+gaining user consent is a mandatory requirement.
+
+> 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 Government Digital Service (GDS) compliant 
+banner, a cookie information panel and the underlying code required 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 (note that 
+this will lead to your analytics underestimating your user base to some degree).
+
+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 in your dashboard project / repo:
+
+```{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 Explore Education Statistics Plaforms team):
+
+```{r eval=FALSE}
+google_analytics_key <- "ABCDE12345"
+```
+
+You will then need to add the necessary code to your **ui.R** file to a) run the 
+javascript (`dfe_cookie_script`), b) create the consent banner 
+(`cookie_banner_ui`), editing the dashboard name to match your own and c) add a cookies information panel 
+(`cookies_panel_ui`):
+
+
+```{r eval=FALSE}
+ui <- function(input, output, session) {
+  shiny::fluidPage(
+    shinyjs::useShinyjs(),
+    dfeshiny::dfe_cookie_script(),
+    dfeshiny::cookie_banner_ui(
+      "cookie-banner",
+      "Your dashboard name"
+    ),
+    shiny::navlistPanel(
+      "",
+      id = "navlistPanel",
+      widths = c(2, 8),
+      well = FALSE,
+      dfeshiny::cookies_panel_ui(
+        id = "cookie-panel",
+        google_analytics_key = google_analytics_key
+      )
+    )
+  )
+}
+```
+
+You should then add the `cookie_banner_server` and `cookies_panel_server` 
+functions to your **server.R** script:
+
+```{r eval=FALSE}
+output$cookie_status <- dfeshiny::cookie_banner_server(
+  "cookie-banner",
+  input_cookies = shiny::reactive(input$cookies),
+  parent_session = session,
+  google_analytics_key = google_analytics_key,
+  cookie_link_panel = "cookies_panel_ui"
+)
+
+dfeshiny::cookies_panel_server(
+  id = "cookie-panel",
+  input_cookies = shiny::reactive(input$cookies),
+  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, 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.