@amedia/user 0.13.38 → 0.13.39

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +252 -24
  2. package/package.json +6 -6
package/README.md CHANGED
@@ -1,11 +1,24 @@
1
- # amedia-user-js
1
+ # @amedia/user
2
2
 
3
- Its goal is to simplify the complexity of logging in and
4
- getting access to user related data.
3
+ The goal of this module is to simplify the usage of aID data and services in Amedia frontend code. The module is
4
+ designed to be used several places on a webpage independently, and the module will ensure that requests from
5
+ different parts of the webpage are handled in an efficient manner.
6
+
7
+ An important requirement for this module is Eik. When used in production, this module should always be loaded from
8
+ an alias in Eik. This is to ensure that all components on a page that uses this module will use same version. The
9
+ normal way to load the module from Eik is through import maps.
5
10
 
6
11
  # Usage
7
- Add this project to yours either via npm (@amedia/user) or eik (https://assets.acdn.no/pkg/user/v0)
8
12
 
13
+ ## Importing the module
14
+
15
+ Add this module to your project by running `npm install -d @amedia/user`. This will allow local development through
16
+ bundling. Once you are ready for production, set up import maps from Eik and point `@amedia/user` to
17
+ `https://assets.acdn.no/pkg/@amedia/user/v0/user.js`.
18
+
19
+ See Ego, Bacchus or Saturn for examples on how to use this module through Eik.
20
+
21
+ Once the module is installed, it can be imported in your source code using a standard import like this:
9
22
 
10
23
  ```ts
11
24
  import {
@@ -14,10 +27,91 @@ import {
14
27
  goToLoginPage,
15
28
  logout,
16
29
  ...etc,
17
- } from 'depends on npm or eik (see above)';
30
+ } from '@amedia/user';
18
31
  ```
19
32
 
20
- ## Subscribing to updates
33
+ When your source code is bundled together for production, it's important that the bundler (rollup, webpack etc.) will
34
+ use an import map to replace this import with `import {} from https://assets.acdn.no/pkg/@amedia/user/v0/user.js` instead
35
+ of bundling a hard coded version of the module in your bundled assets. If this happens, the page will end up with
36
+ different versions of this module, which in time will cause incompatibilities and extra code to download.
37
+
38
+ You can read more about Eik on [Slite](https://amedia.slite.com/app/channels/hOlqx3Miez/notes/iexhL4MZn3).
39
+
40
+ ## Getting user data
41
+
42
+ The most common use case for aID on newspapers is to get some kind of data about a user, this could be the user's name,
43
+ some stored preference, access or data that has been derived about the user.
44
+
45
+ To get user data you first need to create a `UserDataRequest`, then you specify what data you need and once that is
46
+ done, you decide if you want to wait until all data is available, or you want to get partial updates.
47
+
48
+ This module tries to simplify the model representing various data about the user. We have introduced (and re used) some
49
+ concepts that are listed here.
50
+
51
+ ### Data model
52
+ #### Attributes
53
+
54
+ Attributes are data directly related to the user, with the exception of access. Supported attributes are:
55
+
56
+ - uuid (string): The user's unique ID
57
+ - name (string): User's full name
58
+ - trackingKey (string): Unique ID of user that can be used for tracking (pseudonym)
59
+ - access (list of strings): User's access on current site (list of access features)
60
+ - extraData (dynamic object): Data that has been modelled about the user (gender, ad segments etc. from Nebula)
61
+ - privacyPreferences (privacy preferences object): Privacy preferences set on Min aID.
62
+
63
+ Attributes are requested by calling `.withAttributes()` on a `UserDataRequest` with a list of the attributes you need.
64
+
65
+ In the response, `attributes` is an object where each requested attribute is an attribute. So you can get the name by
66
+ accessing `attributes.name` for example.
67
+
68
+ Privacy preferences contains the following boolean attributes:
69
+
70
+ - allowResearchUsage
71
+ - connectWithSurveys
72
+ - personalizedAds
73
+ - personalizedContent
74
+
75
+ NOTE: Fetching each attribute has a cost, so keep the list to a minimum. Don't request attributes you don't really need.
76
+
77
+ #### Storage
78
+
79
+ Storage are namespaces stored in Europa. A namespace is a named set of key value pairs stored for a specific user.
80
+ An example could be favourite_teams, which could contain team_id as key and timestamp it was stored as favourite as value.
81
+
82
+ Storage is requested by calling `.withStorage()` on a `UserDataRequest` with a list of namespaces you need.
83
+
84
+ In the response, `storage` is an object with each namespace as an attribute which leads to an object with attributes
85
+ for each key in the namespace. So you can access `storage.favourite_teams.myteamid` and get the value stored for
86
+ `teamid` in the `favourite_teams` namespace. This value will be whatever was saved there.
87
+
88
+ #### State
89
+
90
+ State is meant to describe the current context the user is in right now. It's not directly requested, but will always
91
+ be a part of the response.
92
+
93
+ Current attributes in `state`:
94
+ - isLoggedIn (boolean): Is the user currently logged in? If not, most attributes will be undefined
95
+ - emergencyMode (list of strings): Current state of emergency mode in production environment (paywall, aid etc.)
96
+
97
+ ### Executing the request
98
+
99
+ Once you have created a request and specified the data you need, the final step is to decide how you want to get
100
+ the data once it's available. You can either choose to subscribe to updates or wait until everything is ready and get
101
+ everything in one package.
102
+
103
+ The response to the request will be an object with attributes for state, attributes and storage. In the
104
+ examples below these are unpacked for easier access.
105
+
106
+ #### Subscribing to updates
107
+
108
+ The most flexible way to get userdata is by subscribing to updates. This is done by calling `.subscribe()` on the
109
+ `UserDataRequest` with a callback function that can handle the updates once they arrive. This is especially useful
110
+ when the time it can take to get the data can vary. Getting the user's name is very fast, so you can display the
111
+ user's name before you have received storage for example.
112
+
113
+ Full usage example:
114
+
21
115
  ```ts
22
116
  import { UserDataRequest } from '...';
23
117
 
@@ -25,18 +119,24 @@ new UserDataRequest()
25
119
  .withAttributes(['name', 'email'])
26
120
  .withStorage(['my_namespace']) // You might know this as Europa
27
121
  .subscribe(({attributes, state, storage}) => {
28
- console.log({attributes, state, storage})
122
+ console.log(attributes, state, storage)
29
123
  });
30
124
  ```
31
- The callback you supplied to subscribe is called
32
- whenever where are any changes to the properties
125
+
126
+ The callback you supplied to subscribe is called whenever there are any changes to the properties
33
127
  you have requested, so be prepared to rerender.
34
128
 
35
- Also, your requested properties might not arrive
36
- all at once. This callback will be called whenever
129
+ Also, your requested properties might not arrive all at once. This callback will be called whenever
37
130
  we get data in from the various services.
38
131
 
39
- ## Fetching all the data once (no rerenders)
132
+ #### Fetching all the data once (no rerenders)
133
+
134
+ In many use cases it's more convenient to just wait until everything is ready so you don't have to handle
135
+ multiple callbacks. In these cases it's easier to call `.fetch()`. This method will return a `Promise` that
136
+ resolves the same object you would get in the `subscribe` callback.
137
+
138
+ Full usage example:
139
+
40
140
  ```ts
41
141
  import { UserDataRequest } from '...';
42
142
 
@@ -45,28 +145,86 @@ new UserDataRequest()
45
145
  .withStorage(['my_namespace']) // You might know this as Europa
46
146
  .fetch()
47
147
  .then(({attributes, state, storage}) => {
48
- console.log({attributes, state, storage})
148
+ console.log(attributes, state, storage)
49
149
  });
50
150
  ```
51
- Fetch will wait until it has all the data you requested before resolving.
52
- The exception is if the visitor isn't logged in atm.
53
151
 
54
- This is neat if you don't need to render fast as it reduces complexity in some situations.
152
+ Fetch will wait until it has all the data you requested before resolving, unless the user is not currently
153
+ logged in. Internally `.fetch()` will use `.subscribe()` and just wait until everything is ready before
154
+ resolving the returned prommise.
55
155
 
156
+ If you really need to render the user's name etc. as fast as possible, use `.subscribe()`, if not,
157
+ this is probably easier.
158
+
159
+ ##### Timeouts
160
+
161
+ Especially poor connections may result in almost eternal wait times - which is no good if your app is locked while
162
+ waiting on the data. Because of this we have introduced a timeout. A timeout will cause the fetch to reject with
163
+ FetchTimeoutError.
164
+
165
+ FetchTimeoutError will include any data we might have gotten before we timed out
56
166
 
57
- ## Updating storage
58
167
  ```ts
59
- import { updateStorage } from '...';
168
+ .catch((e) => {
169
+ if (e instanceof FetchTimeoutError) {
170
+ console.log(e.partialData);
171
+ // Maybe you're able to render your app in a reduced state (perhaps with some partialData) or decide not to render at all.
172
+ }
173
+ }
174
+ ```
60
175
 
61
- updateStorage({
62
- my_namespace: {
63
- my: 'data'
64
- }
65
- });
176
+ If you're running a background task and don't mind waiting longer than default (10 seconds), you may set a longer
177
+ timeout in fetch:
178
+
179
+ ```ts
180
+ .fetch({timeout: 60000 /* milliseconds */ })
66
181
  ```
67
- The subscribe above will notify you when data has changed.
68
182
 
69
183
  ## Unlocking the paywall
184
+
185
+ Amedia's publications use a Paywall that's based on a cookie called VSTOKEN that is read by Varnish and used by
186
+ the content system to decide if the content should be shown to the user or not. If not, the content will load what
187
+ we call an incentive, a dialogue above the content, that will allow the user to log in and buy subscriptions. The
188
+ incentive will use a `PaywallUnlockRequest` to see if it can somehow grant access to the user. In some cases it makes
189
+ sense to create a different user interface for a paywall. In these cases we recommend that you use this
190
+ `PaywallUnlockRequest` in order to get the same functionality.
191
+
192
+ More information about the paywall can be found here:
193
+ [How the Paywall works](https://amedia.slite.com/app/channels/hOlqx3Miez/notes/UFqOFRV3g1)
194
+
195
+ Information about the incentive can also be useful, since you probably need to replicate this functionality if you
196
+ create a new user interface:
197
+ [How the Incentive works](https://amedia.slite.com/app/channels/hOlqx3Miez/notes/SroHksU9u)
198
+
199
+ To unlock the paywall, you first need to create a new `PaywallUnlockRequest`. Once created, you can set some options by
200
+ calling methods on this request:
201
+
202
+ - `reloadOnAccess()`: If the paywall unlocker finds sufficient access for the user it will reload the current page
203
+ - `redirectOnAccess(requestedUrl: string)`: If the paywall unlocker finds sufficient access for the user, it will send the user
204
+ to `requestedUrl`. (Provides more flexibility than `reloadOnAccess()`)
205
+ - `withAccessFeatures(accessFeatures: string[])`: Specify what access features will give access to the current content.
206
+ The default is [`newspaper`].
207
+
208
+ More details about the access model can be found here:
209
+ [Access model](https://amedia.slite.com/app/channels/hOlqx3Miez/notes/nhG2Ok39BN)
210
+
211
+ Once your options have been set up, you can call `tryUnlock()`. This is when all the magic happens. The unlocker will
212
+ try to auto login the user on the current domain, check access, activate subscriptions in the subscription system,
213
+ check for stuff like IP based access etc. When this is done, it will resolve the `Promise` that was returned by
214
+ `tryUnlock()`.
215
+
216
+ The resolution to the promise contains an object with attributes you can use to get details about why the user did
217
+ not get access (or if he had access if you don't opt for reload or redirect). The object contains the following:
218
+
219
+ - isLoggedIn: True if the user is logged in, false otherwise. Useful if you want to show a login button, which makes
220
+ no sense for logged in users.
221
+ - hasAccess: True if the user has access. Always false if you called `reloadOnAccess()` or `redirectOnAccess()`.
222
+ - accessFeatures: List of access features the user has access to. Empty list if user is logged out or has no access.
223
+ This list is useful if you want to upgrade from 'newspaper' to 'plussalt' for instance. You might want to give
224
+ a different user experience to users with some access than users with no access.
225
+
226
+ Full usage example:
227
+
70
228
  ```ts
71
229
  import { PaywallUnlockRequest } from '...';
72
230
 
@@ -101,9 +259,79 @@ new PaywallUnlockRequest()
101
259
  );
102
260
  });
103
261
  ```
262
+
104
263
  Note that this *might result in redirects/reloads* if the user is not already logged in.
105
264
  In that case you will end up here again if logging in did not result in access.
106
265
 
266
+ ## Actions
267
+
268
+ The following methods are actions that the user needs to be able to perform in an environment using logged in users.
269
+
270
+ ### `goToLoginPage(requestedUrl: string)`
271
+
272
+ This action will send the user to the aID login page. It will take care of building the correct URL, including
273
+ your current publication domain, so the login page is skinned correctly.
274
+
275
+ You may include a requestedUrl if you need to control where the user should end up after logging in. The default
276
+ is to send the user back to the current URL where this action was called.
277
+
278
+ ### `logout()`
279
+
280
+ This action will log the user out of aID. The logout is global, meaning it will log the session out of all
281
+ publications and aid.no.
282
+
283
+ ## Updating storage
284
+
285
+ If you need to store preferences, favourite teams etc for the user, you can choose between two methods. One will
286
+ update only the attributes of a namespace that you specify, the other will update everything. The main difference is
287
+ that if you opt for updating everything, attributes that are present on the backend, but not in the update, will be
288
+ deleted.
289
+
290
+ ### Update changed values (PATCH)
291
+
292
+ The safest way to update a value is to use `updateStorage()`. This will send a `PATCH` to Europa to only update
293
+ the specified attributes of a namespace, and keep the rest as it is. This reduces concurrency issues where someone could
294
+ have updated a different attribute after you read the namespace.
295
+
296
+ Example of use:
297
+
298
+ ```ts
299
+ import { updateStorage } from '...';
300
+
301
+ updateStorage({
302
+ my_namespace: {
303
+ my: 'data'
304
+ }
305
+ });
306
+ ```
307
+
308
+ In the example, only `my` in `my_namespace` would be updated to `data`. If the namespace also contained
309
+ `{ your: 'loss' }`, this would be kept untouched, so the resulting namespace would now contain
310
+ `{ my: 'data', your: 'loss' }`.
311
+
312
+ ### Update the entire namespace (PUT)
313
+
314
+ If you're not afraid of concurrency issues, or you need to make sure that old attributes are removed, you should
315
+ use `saveStorage()`. This works in the same way as `updateStorage()`, but it will send a `PUT` to Europa, which will
316
+ then make sure that attributes that are stored in the namespaces in the request, but are not a part of the request,
317
+ will be removed.
318
+
319
+ Example of use:
320
+
321
+ ```ts
322
+ import { updateStorage } from '...';
323
+
324
+ saveStorage({
325
+ my_namespace: {
326
+ my: 'data'
327
+ }
328
+ });
329
+ ```
330
+
331
+ In the example, `my` in `my_namespace` would be updated to `data`. If the namespace also contained
332
+ `{ your: 'loss' }`, this would removed, so the resulting namespace would now contain
333
+ `{ my: 'data' }`.
334
+
107
335
  ## Performance
108
336
  This app aims to be able to deliver a lot of data fast.
109
337
  Still, we might need to call several services in order
package/package.json CHANGED
@@ -1,22 +1,22 @@
1
1
  {
2
2
  "name": "@amedia/user",
3
- "version": "0.13.38",
3
+ "version": "0.13.39",
4
4
  "description": "Client lib for working with aID user and associated data",
5
5
  "repository": "https://github.com/amedia/amedia-user-js",
6
6
  "author": "Amedia Utvikling (ID og data)",
7
7
  "type": "module",
8
- "main": "dist/index.cjs",
9
- "module": "dist/index.js",
8
+ "main": "dist/user.cjs",
9
+ "module": "dist/user.js",
10
10
  "exports": {
11
11
  ".": {
12
- "require": "./dist/index.cjs",
13
- "import": "./dist/index.js"
12
+ "require": "./dist/user.cjs",
13
+ "import": "./dist/user.js"
14
14
  }
15
15
  },
16
16
  "files": [
17
17
  "dist/*"
18
18
  ],
19
- "typings": "dist/index.d.ts",
19
+ "typings": "dist/user.d.ts",
20
20
  "scripts": {
21
21
  "test": "jest --coverage",
22
22
  "lint": "eslint ./src --ext .ts",