docs: basic documentation

brunoluiz · Feb 17, 2021 · 3399d34 · 3399d34
1 parent d9efd87
commit 3399d34
Show file tree

Hide file tree

Showing 3 changed files with 45 additions and 6 deletions.
diff --git 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 `<body>`) and then head to http://localhost:3000 to see recorded sessions
+Add the following snippet to your app (at the end of `<body>`) and then head to `http://localhost:3000` to see recorded sessions
 
 ```js
 <script type="application/javascript" src="http://localhost:3000/record.js" ></script>
@@ -80,9 +84,10 @@ To use this, add the following snippet to your app (at the end of `<body>`) 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 → docs/architecture.md b/ARCHITECTURE.md → 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
@@ -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