@amedia/user 1.0.0 → 1.0.3
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.
- package/CHANGELOG.md +29 -0
- package/README.md +157 -184
- package/package.json +4 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,34 @@
|
|
|
1
1
|
# @amedia/user
|
|
2
2
|
|
|
3
|
+
## 1.0.1
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- [#1126](https://github.com/amedia/amedia-user-js/pull/1126) [`b280880`](https://github.com/amedia/amedia-user-js/commit/b2808802cee1cfb539932fe081a70c5f74ac8dbc) Thanks [@emilhauk](https://github.com/emilhauk)! - Update readme, plus some package cleanup
|
|
8
|
+
|
|
9
|
+
## 1.0.0
|
|
10
|
+
|
|
11
|
+
### Major Changes
|
|
12
|
+
|
|
13
|
+
- [`31fd231`](https://github.com/amedia/amedia-user-js/commit/31fd23139e7d412d686c4c1ce2e0f5cf77564d72) Thanks [@emilhauk](https://github.com/emilhauk)! - From now @amedia/user package will include the following:
|
|
14
|
+
- index.js that wrap the relevant version alias.
|
|
15
|
+
- index.d.ts all typings to assist during development.
|
|
16
|
+
- README.md
|
|
17
|
+
- CHANGELOG.md
|
|
18
|
+
|
|
19
|
+
By "proxying" the version alias, developers no longer need to set up import maps rewrites for @amedia/user anymore!
|
|
20
|
+
|
|
21
|
+
**Upgrading**
|
|
22
|
+
|
|
23
|
+
Remove @amedia/user from import maps in the app. If this package was the only one using import maps, you can get rid of some extra config.
|
|
24
|
+
|
|
25
|
+
If you have made some additional setup to support SSR, you may need to rework this a bit. Node.js is not able to execute @amedia/user. It will just fail due to imports. We are looking into improving this, but at least for now, you need to ensure you don't try to execute the code during SSR. All frontend frameworks that support SSR should have built-in facilities for this case.
|
|
26
|
+
|
|
27
|
+
**Breaking changes**
|
|
28
|
+
|
|
29
|
+
With v1, @amedia/user will lose its built-in mocks.
|
|
30
|
+
We have some plans for achieving something similar later on, but at least the current implementation will go away.
|
|
31
|
+
|
|
3
32
|
## 0.14.152
|
|
4
33
|
|
|
5
34
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -1,87 +1,70 @@
|
|
|
1
1
|
# @amedia/user
|
|
2
2
|
|
|
3
|
-
The goal of this module is to simplify the usage of aID data and services in Amedia frontend code. The module is
|
|
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 different
|
|
5
|
+
parts of the webpage are handled efficiently.
|
|
4
6
|
|
|
5
7
|
# TL;DR (details in the linked chapters)
|
|
6
8
|
|
|
7
9
|
- [UserDataRequest](#getting-user-data)<br/>
|
|
8
|
-
|
|
10
|
+
User data like name, access, KV-storage, etc. Call it as much as you like, but only ask for what you
|
|
11
|
+
actually need.
|
|
9
12
|
- [PaywallUnlockRequest](#unlocking-the-paywall)<br/>
|
|
10
|
-
When you need to actively verify login state and access. May perform redirects and expensive calls for subscription
|
|
13
|
+
When you need to actively verify login state and access. May perform redirects and expensive calls for subscription
|
|
14
|
+
activation, and thus limited in how much it accepts to be called.
|
|
11
15
|
- [SiteAccessRequest](#activating-subscriptions--finding-upgrade-path)<br/>
|
|
12
|
-
When you need to actively verify access. Specify which access feature(s) you need. May attempt subscription
|
|
16
|
+
When you need to actively verify access. Specify which access feature(s) you need. May attempt subscription
|
|
17
|
+
activation.
|
|
13
18
|
- [User actions](#actions)<br/>
|
|
14
19
|
Login, logout, that sort of thing.
|
|
15
20
|
|
|
16
21
|
# Usage
|
|
17
22
|
|
|
18
|
-
Please be advised that you are required to use ESM
|
|
23
|
+
Please be advised that you are required to use ESM to use this module.
|
|
19
24
|
|
|
20
25
|
## Importing the module
|
|
21
26
|
|
|
22
|
-
Add this module to your project by running `npm install -d @amedia/user`. This will allow for type-hinting
|
|
23
|
-
|
|
24
|
-
## Mocking
|
|
25
|
-
|
|
26
|
-
When working exclusively on a frontend app, it might be cumbersome to boot the entire aid rig locally for development. To make this easier, the npm package provides a mock for you to use.
|
|
27
|
-
|
|
28
|
-
**To enable mocked data** you just comment out the import map translation. This will cause your bundler to include the mocks.
|
|
29
|
-
|
|
30
|
-
Then mocked, you'll be logged in as a user with full access. Check the browser console for information about this persona, other personas available, and how to choose between them.
|
|
31
|
-
|
|
32
|
-
### Caveats of the mock
|
|
33
|
-
|
|
34
|
-
This is not intended to be a complete mock as it would've soon required us to reimplement most of aID in the mock :)
|
|
35
|
-
|
|
36
|
-
Supported actions:
|
|
37
|
-
|
|
38
|
-
- **UserDataRequest** will return data based on current persona
|
|
39
|
-
- **PaywallUnlockRequest** will only return state based on current persona (e.g. no reload/redirect)
|
|
40
|
-
|
|
41
|
-
Unsupported (will throw Error):
|
|
42
|
-
|
|
43
|
-
- goToLoginPage
|
|
44
|
-
- logout
|
|
45
|
-
- updateStorage
|
|
46
|
-
- saveStorage
|
|
27
|
+
Add this module to your project by running `npm install -d @amedia/user`. This will allow for type-hinting. @amedia/user
|
|
28
|
+
requires a browser to run. If your app performs server-side rendering, consult framework documentation on how to do this.
|
|
47
29
|
|
|
48
30
|
## Getting user data
|
|
49
31
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
To get user data you first need to create a `new UserDataRequest()` instance, then specify what data you need and lastly decide if you want to wait until all data is available, or you want to get partial updates.
|
|
32
|
+
To get user data, you first need to create a `new UserDataRequest()` instance, then specify what data you need and
|
|
33
|
+
lastly decide if you want to wait until all data is available, or you want to get partial updates.
|
|
53
34
|
|
|
54
35
|
### Data model
|
|
55
36
|
|
|
56
37
|
#### Attributes
|
|
57
38
|
|
|
58
|
-
|
|
39
|
+
| name | type | description |
|
|
40
|
+
| ------------------ | ------------- | ------------------------------------------------------- |
|
|
41
|
+
| uuid | string | The users unique ID. (NOT for tracking). |
|
|
42
|
+
| trackingKey | string | Unique ID of user that can be used for tracking. |
|
|
43
|
+
| sessionTrackingKey | string | Tracking key for the user session. |
|
|
44
|
+
| name | string | Users full name. |
|
|
45
|
+
| access | Array<string> | Users access on current site (list of access features). |
|
|
59
46
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
| uuid | string | The users unique ID. (NOT for tracking) |
|
|
63
|
-
| name | string | Users full name |
|
|
64
|
-
| trackingKey | string | Unique ID of user that can be used for tracking (pseudonym) This is also known as the legacy name user_key |
|
|
65
|
-
| access | Array<string> | Users access on current site (list of access features) |
|
|
66
|
-
| extraData | Record<string,unknown> | Data that has been modelled about the user (gender, ad segments etc. from Nebula) |
|
|
67
|
-
| privacyPreferences (deprecated) | [PrivacyPreferences](https://github.com/amedia/amedia-user-js/blob/master/src/types.ts#L16) | Privacy preferences set on Min aID. (Deprecated - CMP is now used) |
|
|
68
|
-
| sessionTrackingKey | string | Tracking key for the user session |
|
|
47
|
+
Attributes are requested by calling `.withAttributes(attributes: Array<string>)` on a `UserDataRequest` with a list of
|
|
48
|
+
the attributes you need.
|
|
69
49
|
|
|
70
|
-
|
|
50
|
+
In the response, `attributes` is an object where each requested attribute is an attribute. So you can get the name by
|
|
51
|
+
accessing `attributes.name` for example.
|
|
71
52
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
NOTE: Don't request attributes you don't intend to use. This previously had a latency-cost attached to it. This is no longer the case. However, it's best not to keep user data around where it's not needed.
|
|
75
|
-
|
|
76
|
-
NOTE2: ~If you need to know if the current user is an employee, you are encouraged to use data from `extraData` rather than `access` as `extraData` is quicker.~ This is not the case anymore. `access` is now quicker to use and more precise.
|
|
53
|
+
NOTE: Don't request attributes you don't intend to use. This previously had a latency-cost attached to it. This is no
|
|
54
|
+
longer the case. However, it's best not to keep user data around unnecessarily.
|
|
77
55
|
|
|
78
56
|
#### Storage
|
|
79
57
|
|
|
80
|
-
Storage contains namespaces stored in aID (Europa). A namespace is a named set of key value pairs stored for a
|
|
58
|
+
Storage contains namespaces stored in aID (Europa). A namespace is a named set of key value pairs stored for a user. An
|
|
59
|
+
example could be favourite_teams namespace, which could contain team_id as a key and timestamp it was stored as a value.
|
|
81
60
|
|
|
82
|
-
Storage is requested by calling `.withStorage(namespaces: Array<string>)` on a `UserDataRequest`. If a namespace does
|
|
61
|
+
Storage is requested by calling `.withStorage(namespaces: Array<string>)` on a `UserDataRequest`. If a namespace does
|
|
62
|
+
not exist, it will be "created" in that you'll get an empty object back. Saving data to it will perform the actual
|
|
63
|
+
creation.
|
|
83
64
|
|
|
84
|
-
In the response, `storage` is an object with each namespace as an attribute which leads to an object with attributes for
|
|
65
|
+
In the response, `storage` is an object with each namespace as an attribute which leads to an object with attributes for
|
|
66
|
+
each key in the namespace. So you can access `storage.favourite_teams.myteamid` and get the value stored for `teamid` in
|
|
67
|
+
the `favourite_teams` namespace. This value will be whatever was saved there, but always a string.
|
|
85
68
|
|
|
86
69
|
```ts
|
|
87
70
|
type Storage = { [namespace: string]: Record<string, string> };
|
|
@@ -91,9 +74,11 @@ type Storage = { [namespace: string]: Record<string, string> };
|
|
|
91
74
|
|
|
92
75
|
This works just as [regular storage](#storage), but the namespaces are scoped to oauth clients.
|
|
93
76
|
|
|
94
|
-
Client Storage is requested by calling `.withClientStorage(clientId: string, namespaces: Array<string>)` on a
|
|
77
|
+
Client Storage is requested by calling `.withClientStorage(clientId: string, namespaces: Array<string>)` on a
|
|
78
|
+
UserDataRequest.
|
|
95
79
|
|
|
96
|
-
In the response, `clientStorage[clientId]` is an object with each namespace as en attribute that works as described
|
|
80
|
+
In the response, `clientStorage[clientId]` is an object with each namespace as en attribute that works as described
|
|
81
|
+
above.
|
|
97
82
|
|
|
98
83
|
```ts
|
|
99
84
|
type ClientStorage = { [clientId: string]: Storage };
|
|
@@ -101,8 +86,8 @@ type ClientStorage = { [clientId: string]: Storage };
|
|
|
101
86
|
|
|
102
87
|
#### Writing to storage namespaces
|
|
103
88
|
|
|
104
|
-
A namespace is a proxied instance of `Namespace`.
|
|
105
|
-
|
|
89
|
+
A namespace is a proxied instance of `Namespace`. You access this as any old object, but it provides a save()-method for
|
|
90
|
+
when you wish to persist this namespace for later use.
|
|
106
91
|
|
|
107
92
|
```ts
|
|
108
93
|
import { UserDataRequest } from '@amedia/user';
|
|
@@ -117,11 +102,14 @@ delete storage.my_namespace.my_key;
|
|
|
117
102
|
storage.my_namespace.save();
|
|
118
103
|
```
|
|
119
104
|
|
|
120
|
-
In this example, `my_key` in `my_namespace` would be updated to `my data` (and then deleted). Other data would probably
|
|
105
|
+
In this example, `my_key` in `my_namespace` would be updated to `my data` (and then deleted). Other data would probably
|
|
106
|
+
be left "untouched." **Meaning**, if this namespace sees a lot of changes outside this instance, you may end up
|
|
107
|
+
overwriting other changes if you delay a lot between reading and writing!
|
|
121
108
|
|
|
122
109
|
#### State
|
|
123
110
|
|
|
124
|
-
State is
|
|
111
|
+
State is meant to describe the current context the user is in right now. It's not directly requested but will always be
|
|
112
|
+
a part of the response.
|
|
125
113
|
|
|
126
114
|
Current attributes in `state`:
|
|
127
115
|
|
|
@@ -130,9 +118,9 @@ Current attributes in `state`:
|
|
|
130
118
|
| isLoggedIn | boolean | Is the user currently logged in? If not, most attributes will be undefined |
|
|
131
119
|
| emergencyMode | Array<string> | Current state of emergency mode in production environment (paywall, aid etc.) |
|
|
132
120
|
|
|
133
|
-
#### Access not attached to a user
|
|
121
|
+
#### Access not directly attached to a user
|
|
134
122
|
|
|
135
|
-
A visitor may have access through their IP
|
|
123
|
+
A visitor may have access through their IP-address, or a specific token that we periodically enable for "avis i skolen".
|
|
136
124
|
|
|
137
125
|
Current elements in the array `nonUserAccess`:
|
|
138
126
|
|
|
@@ -143,13 +131,19 @@ Current elements in the array `nonUserAccess`:
|
|
|
143
131
|
|
|
144
132
|
### Executing the request
|
|
145
133
|
|
|
146
|
-
Once you have created a request and specified the data you need, the final step is to decide how you want to get the
|
|
134
|
+
Once you have created a request and specified the data you need, the final step is to decide how you want to get the
|
|
135
|
+
data once it's available. You can either choose to subscribe to data as they get loaded from the various backends or
|
|
136
|
+
wait until all fetching is done and get everything in one package.
|
|
147
137
|
|
|
148
|
-
The response to the request will be an object with attributes for state, attributes and storage. In the examples below
|
|
138
|
+
The response to the request will be an object with attributes for state, attributes and storage. In the examples below
|
|
139
|
+
these are unpacked for easier access.
|
|
149
140
|
|
|
150
141
|
#### Subscribing to updates
|
|
151
142
|
|
|
152
|
-
The most flexible way to get userdata is by subscribing to updates. This is done by calling `.subscribe()` on the
|
|
143
|
+
The most flexible way to get userdata is by subscribing to updates. This is done by calling `.subscribe()` on the
|
|
144
|
+
`UserDataRequest` with a callback function that can handle the updates once they arrive. This is especially useful when
|
|
145
|
+
the time it can take to get the data can vary. Getting the user's name is quick, so you can display the user's name
|
|
146
|
+
before you have received storage, for example.
|
|
153
147
|
|
|
154
148
|
Full usage example:
|
|
155
149
|
|
|
@@ -169,17 +163,21 @@ const unsubscribe = new UserDataRequest()
|
|
|
169
163
|
unsubscribe();
|
|
170
164
|
```
|
|
171
165
|
|
|
172
|
-
The callback you supplied to subscribe is called whenever there are any changes to the properties you have requested, so
|
|
166
|
+
The callback you supplied to subscribe is called whenever there are any changes to the properties you have requested, so
|
|
167
|
+
be prepared to re-render.
|
|
173
168
|
|
|
174
|
-
Also, your requested properties might not arrive all at once. This callback will be called whenever we get data in from
|
|
169
|
+
Also, your requested properties might not arrive all at once. This callback will be called whenever we get data in from
|
|
170
|
+
the various services.
|
|
175
171
|
|
|
176
172
|
You should check the state object for potential emergency modes and act accordingly.
|
|
177
173
|
|
|
178
|
-
Should you wish to end your subscription, just call the returned function from subscribe
|
|
174
|
+
Should you wish to end your subscription, just call the returned function from `subscribe`.
|
|
179
175
|
|
|
180
|
-
#### Fetching all the data once (no re-renders)
|
|
176
|
+
#### Fetching all the data at once (no re-renders)
|
|
181
177
|
|
|
182
|
-
In many use-cases, it's more convenient to just wait until everything is ready, so you don't have to handle multiple
|
|
178
|
+
In many use-cases, it's more convenient to just wait until everything is ready, so you don't have to handle multiple
|
|
179
|
+
callbacks. In these cases, it's easier to call `.fetch()`. This method will return a `Promise` that resolves the same
|
|
180
|
+
object you would get in the `subscribe` callback.
|
|
183
181
|
|
|
184
182
|
Full usage example:
|
|
185
183
|
|
|
@@ -198,13 +196,18 @@ new UserDataRequest()
|
|
|
198
196
|
});
|
|
199
197
|
```
|
|
200
198
|
|
|
201
|
-
Fetch will wait until it has all the data you requested before resolving, unless the user is not currently logged in.
|
|
199
|
+
Fetch will wait until it has all the data you requested before resolving, unless the user is not currently logged in.
|
|
200
|
+
Internally `.fetch()` will use `.subscribe()` and just wait until everything is ready before unsubscribing and then
|
|
201
|
+
resolving the returned promise.
|
|
202
202
|
|
|
203
|
-
If you really need to render the user's name or get their uuid etc. as fast as possible, use `.subscribe()`, if not,
|
|
203
|
+
If you really need to render the user's name or get their uuid etc. as fast as possible, use `.subscribe()`, if not,
|
|
204
|
+
this is probably easier.
|
|
204
205
|
|
|
205
206
|
##### Timeouts when using fetch
|
|
206
207
|
|
|
207
|
-
Especially poor connections may result in almost eternal wait times - which is no good if your app is locked while
|
|
208
|
+
Especially poor connections may result in almost eternal wait times - which is no good if your app is locked while
|
|
209
|
+
waiting on the data. Because of this we have introduced a timeout. A timeout will cause the fetch to reject with
|
|
210
|
+
FetchTimeoutError.
|
|
208
211
|
|
|
209
212
|
_FetchTimeoutError will include any data we might have gotten before we timed out_
|
|
210
213
|
|
|
@@ -222,7 +225,8 @@ new UserDataRequest()
|
|
|
222
225
|
});
|
|
223
226
|
```
|
|
224
227
|
|
|
225
|
-
If you're running a background task and don't mind waiting longer than default (10 seconds), you may set a longer
|
|
228
|
+
If you're running a background task and don't mind waiting longer than default (10 seconds), you may set a longer
|
|
229
|
+
timeout in fetch:
|
|
226
230
|
|
|
227
231
|
```ts
|
|
228
232
|
new UserDataRequest()
|
|
@@ -232,7 +236,8 @@ new UserDataRequest()
|
|
|
232
236
|
.fetch({ timeout: 60000 /* milliseconds */ });
|
|
233
237
|
```
|
|
234
238
|
|
|
235
|
-
This may also be lowered below the default, but network request do take some time, even on fast networks, so don't shoot
|
|
239
|
+
This may also be lowered below the default, but network request do take some time, even on fast networks, so don't shoot
|
|
240
|
+
your app in the foot by lowering it too much.
|
|
236
241
|
|
|
237
242
|
##### Emergency mode when using fetch
|
|
238
243
|
|
|
@@ -241,7 +246,7 @@ If you receive this error, there will be no user data available.
|
|
|
241
246
|
Your app should act accordingly, eg:
|
|
242
247
|
|
|
243
248
|
- Render non-personalized
|
|
244
|
-
- Show placeholder with an error message
|
|
249
|
+
- Show a placeholder with an error message
|
|
245
250
|
- Not rendering at all
|
|
246
251
|
|
|
247
252
|
```ts
|
|
@@ -254,7 +259,7 @@ new UserDataRequest()
|
|
|
254
259
|
if (e instanceof FetchTimeoutError) {
|
|
255
260
|
console.log(e.partialData);
|
|
256
261
|
// Maybe you're able to render your app in a reduced state (using partialData).
|
|
257
|
-
} else if (e
|
|
262
|
+
} else if (e instanceof EmergencyModeError) {
|
|
258
263
|
console.log(e.activeEmergencyModes);
|
|
259
264
|
// Maybe you're able to render your app in a non-personalized way?
|
|
260
265
|
}
|
|
@@ -269,19 +274,28 @@ Builds and return the aID login URL. See `goToLoginPage` for details
|
|
|
269
274
|
|
|
270
275
|
### `goToLoginPage({requestedUrl: string context: string}): void`
|
|
271
276
|
|
|
272
|
-
Send the user to the aID login page. It will take care of building the correct URL, including your current site domain,
|
|
277
|
+
Send the user to the aID login page. It will take care of building the correct URL, including your current site domain,
|
|
278
|
+
so the login page is skinned correctly. By default, the user will be sent back to the current url after login has been
|
|
279
|
+
completed. You may include a requestedUrl if you need to control where the user should end up.
|
|
273
280
|
|
|
274
|
-
**Note**: We also support sending a context string when requesting a login. Please include your app-name or more
|
|
281
|
+
**Note**: We also support sending a context string when requesting a login. Please include your app-name or more
|
|
282
|
+
recognizable string. If your app has multiple places for requesting login, it's nice to include that info as well.
|
|
283
|
+
Eg: `goToLoginPage({context: my-app_switch-user})`. The context will help us understand where logins originate from to
|
|
284
|
+
assist in debugging.
|
|
275
285
|
|
|
276
286
|
### `requestDataRefresh(): void`
|
|
277
287
|
|
|
278
|
-
If you need to ensure the latest data is available, you may request a data refresh. @amedia/user will look up all data
|
|
288
|
+
If you need to ensure the latest data is available, you may request a data refresh. @amedia/user will look up all data
|
|
289
|
+
it has in the cache and contact various endpoints to ensure they are up to date. If you're subscribing to updates, your
|
|
290
|
+
callback will be executed if anything changes.
|
|
279
291
|
|
|
280
292
|
**Note**: A data refresh will be automatically performed every time the page regains focus (eg. user switches tabs)
|
|
281
293
|
|
|
282
294
|
### `logout(): Promise<void>`
|
|
283
295
|
|
|
284
|
-
This action will log the user out of aID. The logout is global, meaning it will log the session out of all sites and
|
|
296
|
+
This action will log the user out of aID. The logout is global, meaning it will log the session out of all sites and
|
|
297
|
+
aid.no. After logout has completed the promise will resolve, giving your app the opportunity to reset state / reload the
|
|
298
|
+
page etc.
|
|
285
299
|
|
|
286
300
|
### `pollForAccess(requredAccessFeatures = ['pluss'], timeout_millis = 3000): Promise<true>`
|
|
287
301
|
|
|
@@ -290,74 +304,58 @@ features are attained, or TimeoutError.
|
|
|
290
304
|
|
|
291
305
|
### `aidUrls: Record<string, URL>`
|
|
292
306
|
|
|
293
|
-
Get various, environment
|
|
294
|
-
|
|
295
|
-
### DEPRECATED: `~updateStorage(storage: Storage): void~`
|
|
296
|
-
|
|
297
|
-
[See: Writing-to-storage-namespaces](#writing-to-storage-namespaces)
|
|
298
|
-
The safest way to update a value is to use `updateStorage()`. This will send a `PATCH` to aID (Europa) to only update the specified attributes of a namespace, and keep the rest as it is. This reduces concurrency issues where someone could have updated a different attribute after you read the namespace.
|
|
299
|
-
|
|
300
|
-
Example of use:
|
|
301
|
-
|
|
302
|
-
```ts
|
|
303
|
-
updateStorage({
|
|
304
|
-
my_namespace: {
|
|
305
|
-
my: 'data',
|
|
306
|
-
},
|
|
307
|
-
});
|
|
308
|
-
```
|
|
309
|
-
|
|
310
|
-
### DEPRECATED: `~saveStorage(storage: Storage): void~`
|
|
311
|
-
|
|
312
|
-
[See: Writing-to-storage-namespaces](#writing-to-storage-namespaces)
|
|
313
|
-
Will send a `PUT` to aID (Europa) to update the entire namespace/namespaces, deleting missing data in the process. Please be advised that you may be overwriting updates done by other apps to these namespaces, so it's best to save with a recent namespace if it sees heavy writes :)
|
|
314
|
-
|
|
315
|
-
Example of use:
|
|
316
|
-
|
|
317
|
-
```ts
|
|
318
|
-
saveStorage({
|
|
319
|
-
my_namespace: {
|
|
320
|
-
my: 'data',
|
|
321
|
-
},
|
|
322
|
-
});
|
|
323
|
-
```
|
|
307
|
+
Get various, environment-aware URLs to pages often linked to from other apps. This includes pages like the aID profile
|
|
308
|
+
page, Terms of Service, Privacy Statement, Privacy Preferences, Family Sharing and the like.
|
|
324
309
|
|
|
325
310
|
## Unlocking the paywall
|
|
326
311
|
|
|
327
|
-
Amedia
|
|
312
|
+
Sites hosted through Amedia may use a Paywall. This is based on a JWT-cookie called aid.jwt that is validated and parsed
|
|
313
|
+
by Varnish. When content is requested from a backend, it returns with header information used by varnish to decide if
|
|
314
|
+
the content is available to the reader, and a header telling varnish where to get the version that includes the paywall.
|
|
315
|
+
The paywall (incentive) will use `PaywallUnlockRequest` to see if it can somehow grant access to the user.
|
|
328
316
|
|
|
329
|
-
In some cases it makes sense to create a different user interface for a paywall. If so we recommend that you use
|
|
317
|
+
In some cases it makes sense to create a different user interface for a paywall. If so we recommend that you use
|
|
318
|
+
`PaywallUnlockRequest` in order to get the same functionality.
|
|
330
319
|
|
|
331
|
-
More information about the paywall can be found here:
|
|
320
|
+
More information about the paywall can be found here:
|
|
321
|
+
[How the Paywall works](https://amedia.slite.com/app/channels/hOlqx3Miez/notes/UFqOFRV3g1)
|
|
332
322
|
|
|
333
|
-
Information about the incentive can also be useful, since you probably need to replicate this functionality if you
|
|
323
|
+
Information about the incentive can also be useful, since you probably need to replicate this functionality if you
|
|
324
|
+
create a new user interface: [How the Incentive works](https://amedia.slite.com/app/channels/hOlqx3Miez/notes/SroHksU9u)
|
|
334
325
|
|
|
335
|
-
To unlock the paywall, you first need to create a new `PaywallUnlockRequest`. Once created, you can set some options by
|
|
326
|
+
To unlock the paywall, you first need to create a new `PaywallUnlockRequest`. Once created, you can set some options by
|
|
327
|
+
calling methods on this request:
|
|
336
328
|
|
|
337
|
-
- `reloadOnAccess()`: If the paywall unlocker finds sufficient access for the user it will reload the current page
|
|
338
|
-
- `redirectOnAccess(requestedUrl: string)`: If the paywall unlocker finds sufficient access for the user, it will send
|
|
339
|
-
to `requestedUrl`. (Provides more flexibility than `reloadOnAccess()`)
|
|
340
|
-
- `withAccessFeatures(accessFeatures: string[])`: Specify what access features
|
|
341
|
-
|
|
342
|
-
- **DEPRECATED**: This will fail if you attempt to unlock a paywall on a page without a paywall or its own access features. Feature will be removed in the next major release. Use [SiteAccessRequest](#activating-subscriptions--finding-upgrade-path) instead.
|
|
329
|
+
- `reloadOnAccess()`: If the paywall unlocker finds sufficient access for the user, it will reload the current page
|
|
330
|
+
- `redirectOnAccess(requestedUrl: string)`: If the paywall unlocker finds sufficient access for the user, it will send
|
|
331
|
+
the user to `requestedUrl`. (Provides more flexibility than `reloadOnAccess()`)
|
|
332
|
+
- Deprecated (pass in constructor instead): `withAccessFeatures(accessFeatures: string[])`: Specify what access features
|
|
333
|
+
will give access to the current content.
|
|
343
334
|
|
|
344
|
-
More details about the access model can be found here:
|
|
335
|
+
More details about the access model can be found here:
|
|
336
|
+
[Access model](https://amedia.slite.com/app/channels/hOlqx3Miez/notes/nhG2Ok39BN)
|
|
345
337
|
|
|
346
|
-
Once your options have been set up, you can call `tryUnlock()`. This is when all the magic happens. The unlocker will
|
|
338
|
+
Once your options have been set up, you can call `tryUnlock()`. This is when all the magic happens. The unlocker will
|
|
339
|
+
try to autologin the user on the current domain, check access, activate subscriptions in the subscription system, check
|
|
340
|
+
for stuff like IP-based access, etc. When this is done, it will resolve the `Promise` that was returned by
|
|
341
|
+
`tryUnlock()`.
|
|
347
342
|
|
|
348
|
-
The resolution to the promise contains an object with attributes you can use to get details about why the user did not
|
|
343
|
+
The resolution to the promise contains an object with attributes you can use to get details about why the user did not
|
|
344
|
+
get access (or if he had access if you don't opt for reload or redirect). The object contains the following:
|
|
349
345
|
|
|
350
|
-
- isLoggedIn: True if the user is logged in, false otherwise. Useful if you want to show a login button, which makes no
|
|
346
|
+
- isLoggedIn: True if the user is logged in, false otherwise. Useful if you want to show a login button, which makes no
|
|
347
|
+
sense for logged-in users.
|
|
351
348
|
- hasAccess: True if the user has access. Always false if you called `reloadOnAccess()` or `redirectOnAccess()`.
|
|
352
|
-
- accessFeatures: List of access features the user has access to. Empty list if
|
|
349
|
+
- accessFeatures: List of access features the user has access to. Empty list if noy logged in or has no access. This
|
|
350
|
+
list is useful if you want to upgrade from 'pluss' to 'plussalt' for instance. You might want to give a different user
|
|
351
|
+
experience to users with some access than users with no access.
|
|
353
352
|
|
|
354
353
|
Full usage example:
|
|
355
354
|
|
|
356
355
|
```ts
|
|
357
356
|
import { PaywallUnlockRequest } from '...';
|
|
358
357
|
|
|
359
|
-
new PaywallUnlockRequest()
|
|
360
|
-
.withAccessFeatures(['pluss'])
|
|
358
|
+
new PaywallUnlockRequest(['pluss'])
|
|
361
359
|
.redirectOnAccess('https://my.neat/place') // Optional
|
|
362
360
|
.reloadOnAccess() // Optional
|
|
363
361
|
.tryUnlock()
|
|
@@ -389,22 +387,30 @@ new PaywallUnlockRequest()
|
|
|
389
387
|
});
|
|
390
388
|
```
|
|
391
389
|
|
|
392
|
-
Note that this _might result in redirects/reloads_ if the user is not already logged in. In that case you will end up
|
|
390
|
+
Note that this _might result in redirects/reloads_ if the user is not already logged in. In that case you will end up
|
|
391
|
+
here again if logging in did not result in access.
|
|
393
392
|
|
|
394
393
|
## Activating subscriptions / finding upgrade path
|
|
395
394
|
|
|
396
|
-
|
|
395
|
+
`SiteAccessRequest` checks the current users' access to a specific site. If you're on a site that has its own access
|
|
396
|
+
features (e.g. has a paywall), you should use PaywallUnlockRequest instead. This will set cookies as well.
|
|
397
397
|
|
|
398
398
|
- `withSiteDomain(siteDomain: string)` The domain you with to check access for / attempt activation against.
|
|
399
|
-
- `withAccessFeatures(accessFeatures: Array<string>)` Which access features do you require in order to consider access
|
|
399
|
+
- `withAccessFeatures(accessFeatures: Array<string>)` Which access features do you require in order to consider access
|
|
400
|
+
is granted.
|
|
400
401
|
|
|
401
|
-
Once your options have been set up, you can call `requestAccess()`. This is when all the magic happens. It will try to
|
|
402
|
+
Once your options have been set up, you can call `requestAccess()`. This is when all the magic happens. It will try to
|
|
403
|
+
autologin the user on the current domain, check access, activate subscriptions in the subscription systems, check for
|
|
404
|
+
stuff like IP-based access etc. When this is done, it will resolve the `Promise` that was returned.
|
|
402
405
|
|
|
403
406
|
The resolved promise contains the following:
|
|
404
407
|
|
|
405
|
-
- isLoggedIn: True if the user is logged in, false otherwise. Useful if you want to show a login button (see
|
|
408
|
+
- isLoggedIn: True if the user is logged in, false otherwise. Useful if you want to show a login button (see
|
|
409
|
+
[goToLoginPage(...)](#gotologinpagerequestedurl-string-context-string-void)).
|
|
406
410
|
- hasAccess: True if the user has access that fulfils your `withAccessFeatures`-requirements.
|
|
407
|
-
- accessFeatures: List of access features the user actually has at this time. Empty list if user is logged out or has no
|
|
411
|
+
- accessFeatures: List of access features the user actually has at this time. Empty list if user is logged out or has no
|
|
412
|
+
access. This list is useful if you want to upgrade from 'newspaper' to 'plussalt' for instance. You might want to give
|
|
413
|
+
a different user experience to users with some access than users with no access.
|
|
408
414
|
- primarySite: Best guess of where the user may attain the access you requested.
|
|
409
415
|
|
|
410
416
|
Full usage example:
|
|
@@ -413,9 +419,8 @@ Full usage example:
|
|
|
413
419
|
import { SiteAccessRequest } from '@amedia/user';
|
|
414
420
|
import { SiteAccessResolverError } from './SiteAccessRequest';
|
|
415
421
|
|
|
416
|
-
new SiteAccessRequest()
|
|
422
|
+
new SiteAccessRequest(['sport_premium'])
|
|
417
423
|
.withSiteDomain('www.direktesport.no')
|
|
418
|
-
.withAccessFeatures(['sport_premium'])
|
|
419
424
|
.requestAccess()
|
|
420
425
|
.then(({ isLoggedIn, hasAccess, primarySite, accessFeatures }) => {
|
|
421
426
|
console.log({ isLoggedIn, hasAccess, primarySite, accessFeatures });
|
|
@@ -435,23 +440,30 @@ new SiteAccessRequest()
|
|
|
435
440
|
});
|
|
436
441
|
```
|
|
437
442
|
|
|
438
|
-
Note that this might result in redirects/reloads if the user is not already logged in. In that case you will end up here
|
|
443
|
+
Note that this might result in redirects/reloads if the user is not already logged in. In that case you will end up here
|
|
444
|
+
again if logging in did not result in access.
|
|
439
445
|
|
|
440
446
|
### Known limitations
|
|
441
447
|
|
|
442
|
-
Subscription activation can only happen against the subscription system related to the `withSiteDomain`. #team-abo will
|
|
448
|
+
Subscription activation can only happen against the subscription system related to the `withSiteDomain`. #team-abo will
|
|
449
|
+
need to look into activation across all subscription systems to improve this behavior.
|
|
443
450
|
|
|
444
451
|
## Performance
|
|
445
452
|
|
|
446
|
-
This app aims to be able to deliver a lot of data fast. Still, we might need to call several services
|
|
453
|
+
This app aims to be able to deliver a lot of data fast. Still, we might need to call several services to get what you
|
|
454
|
+
need. We do try to cache whenever this makes sense, but please don't ask for data you don't need.
|
|
447
455
|
|
|
448
456
|
# Behind the scenes
|
|
449
457
|
|
|
450
|
-
There are a few techniques used to avoid
|
|
458
|
+
There are a few techniques used to avoid over-fetching and fetching multiple times when once would do.
|
|
451
459
|
|
|
452
460
|
## Event-based actions
|
|
453
461
|
|
|
454
|
-
Much like [node-userdata-browser/userdata-client](https://github.com/amedia/node-userdata-browser) did, we
|
|
462
|
+
Much like [node-userdata-browser/userdata-client](https://github.com/amedia/node-userdata-browser) did, we use events to
|
|
463
|
+
message that data is being requested. This allowed us to decouple your request from the particular instance that will
|
|
464
|
+
serve it. That in turn allows us to have this library loaded with multiple different components across the page and only
|
|
465
|
+
process the requests in one place. In addition, if the component currently processing requests should be unloaded for
|
|
466
|
+
whatever reason, one of the other instances will automatically take over.
|
|
455
467
|
|
|
456
468
|
## Request de-duping
|
|
457
469
|
|
|
@@ -459,7 +471,7 @@ Since we now process from a single instance of the package it's easy to avoid fe
|
|
|
459
471
|
|
|
460
472
|
## Caching
|
|
461
473
|
|
|
462
|
-
@amedia/user has a caching layer that easily
|
|
474
|
+
@amedia/user has a caching layer that easily lets us switch out the caching mechanism.
|
|
463
475
|
We have two strategies:
|
|
464
476
|
|
|
465
477
|
- SessionStorage: (to survive page loads) Used if available.
|
|
@@ -467,45 +479,6 @@ We have two strategies:
|
|
|
467
479
|
|
|
468
480
|
## Debugging
|
|
469
481
|
|
|
470
|
-
If you're curious about calls, response times etc
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
Hey, thanks! :)
|
|
475
|
-
|
|
476
|
-
It's often nice to do development while testing on a real app. You may do so using `npm link`. When you run then `npm run build` (or `npm run dev` if you want to watch for changes and build automatically) this will expose actual code, letting you develop faster. This is because we still export index.js from the package, but replaces its content with an error if used directly.
|
|
477
|
-
|
|
478
|
-
PS: Remember to comment-out the module in import maps ;-)
|
|
479
|
-
|
|
480
|
-
## Testing live
|
|
481
|
-
|
|
482
|
-
You can test your version live by utilizing a browser extension like Requestly or similar. Run `npm run dev` (which will build and watch for changes locally _and_ starts a webserver listening on localhost:9999). Then add a rule in the extension that replaces requests for @amedia/user/v0/index.js with http://localhost:9999/user.js. Now reload and watch your wonderful change do its thing.
|
|
483
|
-
|
|
484
|
-
## Publishing new versions
|
|
485
|
-
|
|
486
|
-
### Creating a new version
|
|
487
|
-
|
|
488
|
-
We use [Changesets](https://github.com/changesets/changesets/tree/main#readme).
|
|
489
|
-
|
|
490
|
-
1. `npx changeset`
|
|
491
|
-
2. Follow the instructions
|
|
492
|
-
3. Add the changeset `git add .changeset`
|
|
493
|
-
4. Commit and push
|
|
494
|
-
|
|
495
|
-
After merging a release PR will be created/updated (given that tests pass).
|
|
496
|
-
Merging this will push a new version to assets.acdn.no.
|
|
497
|
-
|
|
498
|
-
## Deploying
|
|
499
|
-
|
|
500
|
-
**First snap then prod**:
|
|
501
|
-
If amedia/user breaks in prod it may take down 100+ newspapers entirely,
|
|
502
|
-
so please test on snap first :)
|
|
503
|
-
|
|
504
|
-
We use [importmaps](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) as a means for deployment: https://github.com/amedia/importmap.
|
|
505
|
-
Follow the readme there for the current deployment practice.
|
|
506
|
-
|
|
507
|
-
Until we shut down eikserver, it's nice to have a valid alias should the
|
|
508
|
-
newly created importmap and ESI-trickery fail:
|
|
509
|
-
|
|
510
|
-
1. https://github.com/amedia/amedia-user-js/actions/workflows/deploy.yml
|
|
511
|
-
2. Run that workflow. If what you want is to update the latest alias with the latest version, you can leave the fields empty.
|
|
482
|
+
If you're curious about calls, response times, etc., there is a debug flag you can set on the URL `debug=something`. If
|
|
483
|
+
you'd like it to survive page loads, you can add a key to localStorage or sessionStorage:
|
|
484
|
+
`localStorage.setItem('amedia-user:debug', 'something')`
|
package/package.json
CHANGED
|
@@ -3,9 +3,10 @@
|
|
|
3
3
|
"description": "Client lib for working with aID user and associated data",
|
|
4
4
|
"repository": "https://github.com/amedia/amedia-user-js",
|
|
5
5
|
"author": "Amedia Produkt og Teknologi AS (https://amedia.no)",
|
|
6
|
-
"version": "1.0.
|
|
6
|
+
"version": "1.0.3",
|
|
7
7
|
"type": "module",
|
|
8
8
|
"types": "./index.d.ts",
|
|
9
|
+
"private": false,
|
|
9
10
|
"exports": {
|
|
10
11
|
".": {
|
|
11
12
|
"types": "./index.d.ts",
|
|
@@ -28,7 +29,7 @@
|
|
|
28
29
|
}
|
|
29
30
|
},
|
|
30
31
|
"scripts": {
|
|
31
|
-
"prepublishOnly": "
|
|
32
|
-
"postpublish": "
|
|
32
|
+
"prepublishOnly": "(cd ../../ && npm run build) && cp ../../dist/user.d.ts .",
|
|
33
|
+
"postpublish": "npx @eik/cli publish && rm user.d.ts"
|
|
33
34
|
}
|
|
34
35
|
}
|