An instance of this class will define metadata and data storage provider for gathering telemetry analytics of a Shiny dashboard.
The `name` and `version` parameters will describe the dashboard name and version to track using analytics, allowing to store the analytics data from multiple dashboards in the same data storage provider. As well as discriminate different versions of the dashboard.
The default data storage provider uses a local SQLite database, but this can be customizable when instantiating the class, by using another one of the supported providers (see [DataStorage]).
Active bindings
data_storageinstance of a class that inherits from [DataStorage]. See the documentation on that class for more information.
app_namestring with name of dashboard
Methods
Method new()
Constructor that initializes Telemetry instance with parameters.
Usage
Telemetry$new(
app_name = "(dashboard)",
data_storage = DataStorageSQLite$new(db_path = file.path("telemetry.sqlite"))
)Arguments
app_name(optional) string that identifies the name of the dashboard. By default it will store data with `(dashboard)`.
data_storage(optional) DataStorage instance where telemetry data is being stored. It can take any of data storage providers by this package, By default it will store in a SQLite local database in the current working directory with filename `telemetry.sqlite`
version(optional) string that identifies the version of the dashboard. By default it will use `v0.0.0`.
Method start_session()
Setup basic telemetry
Usage
Telemetry$start_session(
track_inputs = TRUE,
track_values = FALSE,
login = TRUE,
logout = TRUE,
browser_version = TRUE,
navigation_input_id = NULL,
session = shiny::getDefaultReactiveDomain(),
username = NULL
)Arguments
track_inputsflag that indicates if the basic telemetry should track the inputs that change value. `TRUE` by default
track_valuesflag that indicates if the basic telemetry should track the values of the inputs that are changing. `FALSE` by default. This parameter is ignored if `track_inputs` is `FALSE`
loginflag that indicates if the basic telemetry should track when a session starts. `TRUE` by default.
logoutflag that indicates if the basic telemetry should track when the session ends. `TRUE` by default.
browser_versionflag that indicates that the browser version should be tracked.`TRUE` by default.
navigation_input_idstring or vector of strings that represent input ids and which value should be tracked as navigation events. i.e. a change in the value represent a navigation to a page or tab. By default, no navigation is tracked.
sessionShinySession object or NULL to identify the current Shiny session.
usernameCharacter with username. If set, it will overwrite username from session object.
Method log_navigation()
Log an input change as a navigation event
Usage
Telemetry$log_navigation(input_id, session = shiny::getDefaultReactiveDomain())Method log_navigation_manual()
Log a navigation event manually by indicating the id (as input id)
Usage
Telemetry$log_navigation_manual(
navigation_id,
value,
session = shiny::getDefaultReactiveDomain()
)Method log_login()
Log when session starts
Usage
Telemetry$log_login(
username = NULL,
session = shiny::getDefaultReactiveDomain()
)Method log_logout()
Log when session ends
Usage
Telemetry$log_logout(
username = NULL,
session = shiny::getDefaultReactiveDomain()
)Method log_click()
Log an action click
Usage
Telemetry$log_click(id, session = shiny::getDefaultReactiveDomain())Method log_browser_version()
Log the browser version
Usage
Telemetry$log_browser_version(session = shiny::getDefaultReactiveDomain())Method log_button()
Track a button and track changes to this input (without storing the values)
Usage
Telemetry$log_button(
input_id,
track_value = FALSE,
session = shiny::getDefaultReactiveDomain()
)Arguments
input_idstring that identifies the button in the Shiny application so that the function can track and log changes to it.
track_valueflag that indicates if the basic telemetry should track the value of the input that are changing. `FALSE` by default.
sessionShinySession object or NULL to identify the current Shiny session.
Method log_all_inputs()
A short description...
Usage
Telemetry$log_all_inputs(
track_values = FALSE,
excluded_inputs = c("browser_version"),
session = shiny::getDefaultReactiveDomain()
)Arguments
track_valuesflag that indicates if the basic telemetry should track the values of the inputs that are changing. `FALSE` by default. This parameter is ignored if `track_inputs` is `FALSE`.
excluded_inputsvector of input_ids that should not be tracked. By default it doesn't track browser version, which is added by this package.
sessionShinySession object or NULL to identify the current Shiny session.
Method log_input()
A short description...
Usage
Telemetry$log_input(
input_id,
track_value = FALSE,
matching_values = NULL,
input_type = "text",
session = shiny::getDefaultReactiveDomain()
)Arguments
input_idstring that identifies the generic input in the Shiny application so that the function can track and log changes to it.
track_valueflag that indicates if the basic telemetry should track the value of the input that are changing. `FALSE` by default.
matching_valuesAn object specified possible values to register.
input_type'text' to registered bare input value, 'json' to parse value from JSON format.
sessionShinySession object or NULL to identify the current Shiny session.
Method log_input_manual()
Log a manual input value.
This can be called in telemetry and is also used as a layer between log_input family of functions and actual log event. It creates the correct payload to log the event internally.
Usage
Telemetry$log_input_manual(
input_id,
value = NULL,
session = shiny::getDefaultReactiveDomain()
)Method log_custom_event()
Log a manual event
Usage
Telemetry$log_custom_event(
event_type,
details = NULL,
session = shiny::getDefaultReactiveDomain()
)Examples
log_file_path <- tempfile(fileext = ".txt")
telemetry <- Telemetry$new(
data_storage = DataStorageLogFile$new(log_file_path = log_file_path)
)
#
# Create dummy session (only for example purposes)
session <- shiny::MockShinySession$new()
class(session) <- c(class(session), "ShinySession")
telemetry$start_session(session = session)
#> Warning: session$request doesn't currently simulate a realistic request on MockShinySession
#> Warning: session$request doesn't currently simulate a realistic request on MockShinySession
#> Warning: session$request doesn't currently simulate a realistic request on MockShinySession
#> NULL
telemetry$log_click("a_button", session = session)
telemetry$log_custom_event("a_button", list(value = 2023), session = session)
telemetry$log_custom_event("a_button", list(custom_field = 23), session = session)
# Manual call loging with custom username
telemetry$log_login("ben", session = session)
telemetry$data_storage$read_event_data("2020-01-01", "2025-01-01")
#> # A tibble: 5 × 9
#> app_name type session username id value custom_field time
#> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <dttm>
#> 1 (dashboar… login 46cac8… anon_us… NA NA NA 2024-07-25 12:18:11
#> 2 (dashboar… click 46cac8… NA a_bu… NA NA 2024-07-25 12:18:11
#> 3 (dashboar… a_bu… 46cac8… NA NA 2023 NA 2024-07-25 12:18:11
#> 4 (dashboar… a_bu… 46cac8… NA NA NA 23 2024-07-25 12:18:11
#> 5 (dashboar… login 46cac8… ben NA NA NA 2024-07-25 12:18:11
#> # ℹ 1 more variable: date <date>
file.remove(log_file_path)
#> [1] TRUE
#
# Using SQLite
db_path <- tempfile(fileext = ".sqlite")
telemetry <- Telemetry$new(
data_storage = DataStorageSQLite$new(db_path = db_path)
)
telemetry$log_custom_event("a_button", list(value = 2023), session = session)
telemetry$log_custom_event("a_button", list(custom_field = 23), session = session)
telemetry$data_storage$read_event_data("2020-01-01", "2025-01-01")
#> # A tibble: 2 × 9
#> time app_name session type value custom_field date id
#> <dttm> <chr> <chr> <chr> <chr> <chr> <date> <chr>
#> 1 2024-07-25 12:18:11 (dashbo… 46cac8… a_bu… 2023 NA 2024-07-25 NA
#> 2 2024-07-25 12:18:11 (dashbo… 46cac8… a_bu… NA 23 2024-07-25 NA
#> # ℹ 1 more variable: username <chr>
file.remove(db_path)
#> [1] TRUE