Finish updating documentation + add vignette

DESCRIPTION

@@ -18,4 +18,8 @@ Imports:
     googlesheets4,
     lubridate,
     pkgload,
-    rstudioapi
+    rstudioapi,
+    shiny,
+    usethis
+Suggests:
+    knitr

NAMESPACE

@@ -2,5 +2,5 @@
 
 export(add_credentials)
 export(set_credentials)
-export(set_user_tracking)
 export(setup_sheet)
+export(use_logging)

R/usertracking.R

@@ -114,8 +114,8 @@ check_cols <- function(columns) {
 #' Add a new sheet for tracking to the Google sheets
 #'
 #' @param sheet_name Name for the sheet. Default is to use current package name.
-#' @param columns Either NULL or vector of column names. Names must be known. Known
-#'  columns are id, username, login, logout and duration
+#' @param columns Which columns to log, from id, username, login, logout and
+#'  duration. By default login, logout and duration will be logged.
 #' @param creds File used to store credentials. Defaults to `.google-sheets-credentials`.
 #'
 #' @return Nothing, used for side-effects only
@@ -127,7 +127,7 @@ check_cols <- function(columns) {
 #' setup_sheet("A new Shiny app", c("login", "logout", "duration"))
 #' }
 setup_sheet <- function(sheet_name = pkgload::pkg_name(),
-                        columns = NULL,
+                        columns = c("login", "logout", "duration"),
                         creds = ".google-sheets-credentials") {
   columns <- check_cols(columns)
 
@@ -154,10 +154,9 @@ setup_sheet <- function(sheet_name = pkgload::pkg_name(),
 #' Log session ID, username (only for Private apps), session start, end and
 #' duration to a Google sheet.
 #'
-#' @param session Shiny session object.
 #' @param sheet_name Name for the sheet. Default is to use current package name.
-#' @param columns Which columns to record, from id, username, login, logout and
-#'  duration. By default all will be recorded.
+#' @param columns Which columns to log, from id, username, login, logout and
+#'  duration. By default login, logout and duration will be logged.
 #' @param creds File used to store credentials. Defaults to `.google-sheets-credentials`.
 #'
 #' @return Nothing, used for side-effects only
@@ -178,12 +177,21 @@ setup_sheet <- function(sheet_name = pkgload::pkg_name(),
 #'
 #' shinyApp(ui, server)
 #' }
-set_user_tracking <- function(session,
-                              sheet_name = pkgload::pkg_name(),
-                              columns = NULL,
-                              creds = ".google-sheets-credentials") {
+use_logging <- function(sheet_name = pkgload::pkg_name(),
+                         columns = c("login", "logout", "duration"),
+                         creds = ".google-sheets-credentials") {
   columns <- check_cols(columns)
 
+  stopifnot(
+    "set_user_tracking can run only in a Shiny app" = shiny::isRunning(),
+    "set_user_tracking requires a Shiny session object to run" = exists(
+      "session",
+      parent.frame()
+    )
+  )
+
+  session <- get("session", parent.frame())
+
   set_credentials(creds)
 
   googlesheets4::gs4_auth(

README.md

@@ -9,15 +9,14 @@
 
 ## Installation
 
-You can install `shinyusertracking` from [GitHub](https://github.com/) with:
+To install this package from GitHub, use the below code. Note that you must explicitly ask for vignettes to be built when installing from GitHub.
 
-``` r
-# install.packages("devtools")
-devtools::install_github("nhsbsa-data-analytics/shinyusertracking")
-```
+`remotes::install_github("nhsbsa-data-analytics/shinyusertracking", build_vignettes = TRUE)`
 
 ## Usage
 
+Fields available for logging are:
+
 Column|Description
 :---:|:---: 
 id|The Shiny session ID
@@ -26,39 +25,24 @@ login|Timestamp of session start
 logout|Timestamp of session end
 duration|Duration of session in `hh:mm:ss` format
 
-1. Create a new Google sheet, with column headers corresponding to the columns you will be recording (they can be named differently to the columns given if you want).
-2. Copy the contents of the file `.google-sheets-credentials.example` in this repo to a file named `.google-sheets-credentials` in the root directory of your app.
-3. IMPORTANT: You must tell git to ignore this! `usethis::use_git_ignore(".google-sheets-credentials")`.
-4. IMPORTANT: While you are at it, also `usethis::use_git_ignore(".secret/")`. This is the directory in which the Google authorisation secret will be stored.
-5. Replace the example for `GOOGLE_SHEET_ID` with the ID of the Google sheet. You can find this in the URL. For example, if the URL is `https://docs.google.com/spreadsheets/d/1vwrKiwX4T_-A2IldWnjcd1PHlCDsGAq9U-yTtQ6tgzk/edit?gid=0#gid=0`, the ID is `1vwrKiwX4T_-A2IldWnjcd1PHlCDsGAq9U-yTtQ6tgzk`.
-6. Replace the example for `GOOGLE_SHEET_USER` with the Google account username. See the page _Coding and Dashboards/ R code/Shiny app visit tracking_ in the DALL Wiki for details of a Data Science team Google account to use.
-7. Add the code at the top of your `server` function.
-8. The first time it is run, you will be asked to authenticate the Google account access. Once this is done, an authorisation token will be stored in the `.secrets` directory. This can be reused when adding visit tracking for another app. So alternatively, you could copy an existing `.secret` directory, with the token inside, and paste into the root directory of your app. Note that you will not be able to confirm the access on AVDs, as the Google pages to do so are not whitelisted. See the page _Coding and Dashboards/ R code/Shiny app visit tracking_ in the DALL Wiki for details of where to find an existing token.
-8. Ensure you bundle both the `.google-sheets-credentials` file and the `.secret` directory when your app is deployed.
+By default, `login`, `logout` and `duration` will be logged. Although `sessionid` and `username` are also available, these have potential to be treated as PII, so please ensure you meet any legal obligations if logging these.
 
-Note that 'visits' when running it locally in development will also track. So you might want to introduce some configuration to only run in production. Alternatively, try to remember to delete any entries logged during development from the Google sheet.
+For instructions on using check out the vignette by running `vignette("adding-logging-to-a-shiny-app", "shinyusertracking")`.
+
+Note that 'visits' when running it locally in development will also be logged. So you might want to introduce some configuration to only run in production. Alternatively, try to remember to delete any entries logged during development from the Google sheet.
 
 ## Example
 
+Once the necessary credentials are in place, and a Google sheet is ready to be logged to, just place the a call to `use_logging()` at the top of your server function.
+
 ``` r
 library(shiny)
 
 ui <- fluidPage()
 
 server <- function(input, output, session) {
-  shinyusertracking::set_user_tracking(
-    session
-  )
+  shinyusertracking::use_logging()
 }
 
 shinyApp(ui, server)
 ```
-
-Optionally, you can choose to log specific columns only.
-
-``` r
-shinyusertracking::set_user_tracking(
-  columns = c("login", "logout", "duration"),
-  session
-)   
-```

vignettes/adding-tracking-to-a-shiny-app.Rmd → vignettes/adding-logging-to-a-shiny-app.Rmd

@@ -1,8 +1,8 @@
 ---
-title: "Adding tracking to a shiny app"
+title: "Adding logging to a shiny app"
 output: rmarkdown::html_vignette
 vignette: >
-  %\VignetteIndexEntry{Adding tracking to a shiny app}
+  %\VignetteIndexEntry{Adding logging to a shiny app}
   %\VignetteEngine{knitr::rmarkdown}
   %\VignetteEncoding{UTF-8}
 ---
@@ -18,11 +18,17 @@ knitr::opts_chunk$set(
 
 ### ID of Google sheet to use
 
-To keep all tracking sheets together, it is advised to create an initial Google sheet and then add new sheets as you add tracking to apps. You will need the ID of the initial sheet. This can be found from the URL.
+To keep all logging sheets together, it is advised to create an initial Google sheet and then add new sheets as you add logging to apps. You will need the ID of the initial sheet. This can be found from the URL.
 
 #### Example
 
-A sheet with URL `https://docs.google.com/spreadsheets/d/1PZJ_xCbZPSlMzfmjtrM0ePB6115Qqp5fYmLxTNTa5ms/edit?gid=0#gid=0` has ID `1PZJ_xCbZPSlMzfmjtrM0ePB6115Qqp5fYmLxTNTa5ms`
+A sheet with URL 
+
+```
+https://docs.google.com/spreadsheets/d/1PZJ_xCbZPSlMzfmjtrM0ePB6115Qqp5fYmLxTNTa5ms/edit?gid=0#gid=0
+```
+
+has ID `1PZJ_xCbZPSlMzfmjtrM0ePB6115Qqp5fYmLxTNTa5ms`
 
 ### Google account username
 
@@ -36,33 +42,27 @@ These pop-ups will allow the credentials to be cached in your OS secrets store s
 
 The file in which credentials are saved will be added to the `.gitignore` file automatically.
 
-## Set up tracking sheet
+## Set up logging sheet
 
-Once the credentials are added you can add a new sheet to track the app. To do this, again ensuring you are in the root directory of the R project containing the app, run `setup_sheet()`. This will append a new sheet to the sheet with ID provided earlier. It is recommended to track only the `login`, `logout` and `duration`. Although `sessionid` and `username` are also available, these have potential to be treated as PII.
-
-``` r
-setup_sheet(columns = c("login", "logout", "duration"))
-```
+Once the credentials are added you can add a new sheet for the app. To do this, again ensuring you are in the root directory of the R project containing the app, run `setup_sheet()`. This will append a new sheet to the sheet with ID provided earlier. By default, `login`, `logout` and `duration` will be logged. Although `sessionid` and `username` are also available, these have potential to be treated as PII.
 
 Before the sheet can be added, authorisation must take place. You have two options.
 
 Option 1. Place an existing authorisation file in a folder `.secret`, within the root folder of the project.
+
 Option 2. Let a browser window open, and confirm authorisation. This will save an authorisation file in `.secret`.
 
 The `.secret` folder, whether pasted in or created anew, will be added to the `.gitignore` file automatically.
 
 ## Add code to server function
 
-Add the tracking code to the shiny server function. This should be placed at the top, before any other code.
+Add the logging code to the shiny server function. This should be placed at the top, before any other code.
 
 ``` r
 server <- function(input, output, session) {
-  shinyusertracking::set_user_tracking(
-    session,
-    columns = c("login", "logout", "duration")
-  )
+  shinyusertracking::use_logging()
 
-  ... # Existing code below!
+  ... # Existing code below
   ...
   ...
 }