Skip to content

Add analytics section to frontend documentation #9421

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aduth merged 2 commits into from
Oct 20, 2023
Merged

Add analytics section to frontend documentation #9421

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5c95b36
Add analytics section to frontend documentation
aduth Oct 19, 2023
dfc2ae1
link to correct javascript package
aduth Oct 19, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 0 additions & 6 deletions app/javascript/packages/analytics/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,6 @@

Utilities and custom elements for logging events and errors in the application.

By default, events logged from the frontend will have their names prefixed with "Frontend:". This
behavior occurs in [`FrontendLogController`][frontend_log_controller.rb]. You can avoid the prefix
by assigning an event mapping method in the controller's `EVENT_MAP` constant.

[frontend_log_controller.rb]: https://github.com/18F/identity-idp/blob/main/app/controllers/frontend_log_controller.rb

## Usage

### Programmatic Event Tracking
Expand Down
27 changes: 27 additions & 0 deletions docs/frontend.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,33 @@ to deduplicate resolved package versions within the Yarn lockfile.

See [`@18f/identity-i18n` package documentation](../app/javascript/packages/i18n/README.md).

### Analytics

See [`@18f/identity-analytics` package documentation][analytics_package] for code examples detailing
how to track an event in JavaScript.

Any event logged from the frontend must be added to the `EVENT_MAP` allowlist in [`FrontendLogController`][frontend_log_controller.rb].
This mapping associates the event name logged from the frontend with the corresponding method from
[AnalyticsEvents][analytics_events.rb] to be called. All properties will be passed automatically to
the event from the frontend as long as they are defined in the method argument signature.

There may be some situations where you need to append a value known by the server to an event logged
in the frontend, such as an A/B test bucket descriptor. In these scenarios, you have a few options:

1. Add the value to the page markup, such as through an [HTML `data-` attribute][data_attributes],
and reference that attribute in JavaScript.
2. Define the mapped value in `EVENT_MAP` to a service class, such as how [frontend error logging][frontend_error_logging]
is implemented.
3. Implement a mixin to intercept and override the default behavior of an analytics event, such as
how [`Idv::AnalyticsEventEnhancer`][analytics_events_enhancer.rb] is implemented.

[analytics_package]: ../app/javascript/packages/analytics/README.md
[frontend_log_controller.rb]: https://github.com/18F/identity-idp/blob/main/app/controllers/frontend_log_controller.rb
[analytics_events.rb]: https://github.com/18F/identity-idp/blob/main/app/services/analytics_events.rb
[data_attributes]: https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes
[frontend_error_logging]: https://github.com/18F/identity-idp/blob/9c17164c0b8d9b4aefad74dde1a521c111b53aac/app/controllers/frontend_log_controller.rb#L14
[analytics_events_enhancer.rb]: https://github.com/18F/identity-idp/blob/main/app/services/idv/analytics_events_enhancer.rb

## Components

### Design System
Expand Down