diff --git a/README.md b/README.md index fac3eec..b2bc83d 100644 --- a/README.md +++ b/README.md @@ -37,13 +37,17 @@ The tool is available as a Docker image as well. Please refer to [Docker Hub pag ## Usage +**ℹ️ Be aware that, by default, the data will be always anonymised. Even if the client sends user data, the server will not save any PII (personal +identifiable information).This includes user ids, names and e-mails. If your application grants permission to gather certain personal data, +run the application with --non-anonymised-mode.** + ### Server Use one of the distributions above to fetch a binary. Before running, bear in mind the following configurations: ``` --public-url value Public URL where the service is exposed. The service might be running on :3000, but the public access can be proxied through 80 (default: "http://localhost:3000") [$PUBLIC_URL] - --anonymise If enabled, it erases any personal information from requests (default: true) [$ANONYMISE] + --non-anonymised-mode If set, it will allow user details to be recorded (default: false) [$NON_ANONYMISED_MODE] --address value Service address -- change to 127.0.0.1 if developing on Mac (avoids network warnings) (default: "0.0.0.0") [$ADDRESS] --port value Service port (default: "3000") [$PORT] --allowed-origins value CORS allowed origins (default: "*") [$ALLOWED_ORIGINS] @@ -54,7 +58,7 @@ Use one of the distributions above to fetch a binary. Before running, bear in mi ### Client -To use this, add the following snippet to your app (at the end of ``) and then head to http://localhost:3000 to see recorded sessions +Add the following snippet to your app (at the end of ``) and then head to `http://localhost:3000` to see recorded sessions ```js @@ -80,9 +84,10 @@ To use this, add the following snippet to your app (at the end of ``) and - `go run ./cmd/jornada` - By default, it will be served on `http://localhost:3000` -### Architecture +### Architecture & Documentation -Refer to [`ARCHITECTURE.md`](./ARCHITECTURE.md) for more informations about the service implementation. +- Refer to [`docs/js_client.md`](./docs/js_client.md) for more informations about the JS client. +- Refer to [`docs/architecture.md`](./docs/architecture.md) for more informations about the service implementation. ## To-do diff --git a/ARCHITECTURE.md b/docs/architecture.md similarity index 93% rename from ARCHITECTURE.md rename to docs/architecture.md index 1465e73..40f853c 100644 --- a/ARCHITECTURE.md +++ b/docs/architecture.md @@ -9,11 +9,11 @@ The following happens once the recorder is instantiated: - Call `POST /api/v1/sessions` to create a session (receives `session id`) - Call `POST /api/v1/sessions` for sub-sequent sessions updates, but attaching the `session id` on the body -- Every 5 seconds, dump recorded events to the service through `POST /api/v1/sessions/{id}/events` +- Every T seconds, dump recorded events to the service through `POST /api/v1/sessions/{id}/events` [![](https://mermaid.ink/img/eyJjb2RlIjoic2VxdWVuY2VEaWFncmFtXG4gICAgYXBwLT4-YXBpOiBjcmVhdGUgc2Vzc2lvblxuICAgIGFwaS0tPj5hcHA6IG9rIHcvIHNlc3Npb25faWRcblxuICAgIGxvb3BcbiAgICAgICAgYXBwLT4-YXBpOiBzZW5kcyBldmVudHNcbiAgICAgICAgYXBwLT4-YXBpOiBzZW5kcyBzZXNzaW9uIHVwZGF0ZXNcbiAgICBlbmRcbiIsIm1lcm1haWQiOnsidGhlbWUiOiJuZXV0cmFsIn0sInVwZGF0ZUVkaXRvciI6ZmFsc2V9)](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoic2VxdWVuY2VEaWFncmFtXG4gICAgYXBwLT4-YXBpOiBjcmVhdGUgc2Vzc2lvblxuICAgIGFwaS0tPj5hcHA6IG9rIHcvIHNlc3Npb25faWRcblxuICAgIGxvb3BcbiAgICAgICAgYXBwLT4-YXBpOiBzZW5kcyBldmVudHNcbiAgICAgICAgYXBwLT4-YXBpOiBzZW5kcyBzZXNzaW9uIHVwZGF0ZXNcbiAgICBlbmRcbiIsIm1lcm1haWQiOnsidGhlbWUiOiJuZXV0cmFsIn0sInVwZGF0ZUVkaXRvciI6ZmFsc2V9) -The available JS API can be seen in [./internal/http/view/view.go](here). In the future, this will be extracted as a npm package. +The available JS API can be seen in [./internal/server/view/view.go](here). In the future, this will be extracted as a npm package. ## Storage diff --git a/docs/js_client.md b/docs/js_client.md new file mode 100644 index 0000000..b66d01b --- /dev/null +++ b/docs/js_client.md @@ -0,0 +1,34 @@ +# JS Client APIs + +Once imported, the recorder will be available at `window.recorder`. + +## Methods + +### `window.recorder.setUser` + +- Input: `(user: { id: string, name: string: email: string })` +- Output: window.recorder + +Sets user information. If server is running on anonymised mode, this data will not be recorded + +### `window.recorder.setMeta` + +- Input: `(meta: { [key: string]: string })` +- Output: window.recorder + +Sets session meta data. Useful to identify the session somehow. + +### `window.recorder.setClientId` + +- Input: `(clientId: string)` +- Output: window.recorder + +Sets which clientId (example: site1 and site2). Can be used in the future as a filter in the explorer. + +### `window.recorder.sync` + +Forces the recorder to send data to the server + +### `window.recorder.close` + +Kills the recorder session