@atomic.io/action-cards-web-sdk-cdn-icons 24.2.1 → 24.3.0

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 (6) hide show
  1. package/README.md +295 -128
  2. package/package.json +1 -1
  3. package/public/LICENSES.txt +1 -1
  4. package/public/iframe-manager.js +3 -3
  5. package/public/sdk.d.ts +210 -93
  6. package/public/sdk.js +3 -3
package/README.md CHANGED
@@ -1,12 +1,12 @@
1
1
  [![codecov](https://codecov.io/github/atomic-app/action-cards-web-sdk/branch/master/graph/badge.svg?token=BNXNRL8ASJ)](https://codecov.io/github/atomic-app/action-cards-web-sdk)
2
2
 
3
- # Web SDK - Current (24.2.1)
3
+ # Web SDK - Current (24.3.0)
4
4
 
5
5
  ## Introduction
6
6
 
7
7
  The Atomic Web SDK allows you to integrate an Atomic stream container into your web app or site, presenting cards from a stream to your customers.
8
8
 
9
- The current stable release is **24.2.1**.
9
+ The current stable release is **24.3.0**.
10
10
 
11
11
  ### Browser support
12
12
 
@@ -18,10 +18,10 @@ We currently do not have a boilerplate app for the Web SDK. [Contact us](mailto:
18
18
 
19
19
  ## Installation
20
20
 
21
- The current version of the Atomic Web SDK is `24.2.1`, and is hosted on our CDN at `https://downloads.atomic.io/web-sdk/release/24.2.1/sdk.js`.
21
+ The current version of the Atomic Web SDK is `24.3.0`, and is hosted on our CDN at `https://downloads.atomic.io/web-sdk/release/24.3.0/sdk.js`.
22
22
 
23
23
  As of version `24.2.1` the Web SDK also offers a bundle variant which does not include the font used for icons in action cards. Instead this font is fetched via CDN as required, allowing the size of your initial bundle loaded by the browser to be smaller. Both variations function identically in all other respects.
24
- This variant is hosted on our CDN at `https://downloads.atomic.io/web-sdk/release/24.2.1/sdk-cdn-icons.js`.
24
+ This variant is hosted on our CDN at `https://downloads.atomic.io/web-sdk/release/24.3.0/sdk-cdn-icons.js`.
25
25
 
26
26
  To integrate it, add the script for your chosen variant as a source to your web page:
27
27
 
@@ -29,11 +29,13 @@ To integrate it, add the script for your chosen variant as a source to your web
29
29
  <html>
30
30
  ...
31
31
  <body>
32
- <script src="https://downloads.atomic.io/web-sdk/release/24.2.1/sdk.js"></script>
32
+ <script src="https://downloads.atomic.io/web-sdk/release/24.3.0/sdk.js"></script>
33
33
  </body>
34
34
  </html>
35
35
  ```
36
36
 
37
+ The SDK can be installed via npm, with the bundled font variant being [@atomic.io/action-cards-web-sdk](https://www.npmjs.com/package/@atomic.io/action-cards-web-sdk) and the variant excluding icon fonts being [@atomic.io/action-cards-web-sdk-cdn-icons](https://www.npmjs.com/package/@atomic.io/action-cards-web-sdk-cdn-icons).
38
+
37
39
  When Atomic releases a new version of the Web SDK, you will need to manually update your scripts with a url that references the download location of the latest version.
38
40
 
39
41
  ### Content Security Policy
@@ -73,7 +75,7 @@ AtomicSDK.setSessionDelegate(() => {
73
75
  })
74
76
  ```
75
77
 
76
- Your callback will be invoked when the SDK requires a JWT. The token returned by your callback will be cached by the SDK and used for subsequent authenticated requests until expiry. After expiry the callback will be invoked once again to request a fresh token. The callback must return the token within 5 seconds, otherwise error handling will be triggered within the SDK. More information on the JWT structure is available in the [Authentication](../sdks/auth-SDK) section.
78
+ Your callback will be invoked when the SDK requires a JWT. The token returned by your callback will be cached by the SDK and used for subsequent authenticated requests until expiry. After expiry the callback will be invoked once again to request a fresh token. The callback must return the token within 5 seconds, otherwise error handling will be triggered within the SDK. More information on the JWT structure is available in the [Authentication](https://documentation.atomic.io/sdks/auth-SDK) section.
77
79
 
78
80
  #### JWT Expiry interval
79
81
 
@@ -93,13 +95,13 @@ AtomicSDK.setSessionDelegate(() => {
93
95
 
94
96
  ### Login convenience method
95
97
 
96
- To be ready to display a stream container you need to have [initialised](#displaying-a-stream-container) the SDK & set the [Session Delegate](#authenticating-requests-with-a-jwt). _**As of SDK 1.6.0**_ you can use the convenience method `login` to accomplish this in one call. This method has the following parameters:
98
+ To be ready to display a stream container you need to have [initialised](https://documentation.atomic.io/sdks/web#displaying-a-stream-container) the SDK & set the [Session Delegate](https://documentation.atomic.io/sdks/web#authenticating-requests-with-a-jwt). You can use the convenience method `login` to accomplish this in one call. This method has the following parameters:
97
99
 
98
100
  - `apiHost`: a string value representing your API host
99
101
  - `apiKey`: a string value representing your API key
100
102
  - `environmentId`: a string value representing your environment id
101
103
  - `sessionDelegate`: a function that resolves to a promise which supplies an authentication token to the SDK
102
- - `retryInterval`: (optional) a number which defines the [JWT Retry interval](#jwt-retry-interval)
104
+ - `retryInterval`: (optional) a number which defines the [JWT Retry interval](https://documentation.atomic.io/sdks/web#jwt-retry-interval)
103
105
 
104
106
  This method should be called in the following manner:
105
107
 
@@ -115,8 +117,6 @@ AtomicSDK.login(
115
117
 
116
118
  ### WebSockets and HTTP API protocols
117
119
 
118
- _Available in SDK version 1.0.0 and above_
119
-
120
120
  You can specify the protocol the SDK uses to communicate with the Atomic Platform when fetching cards. This can be done by calling the `setApiProtocol` method before calling `initialise`, so that the SDK knows which protocol to use when establishing a connection to the platform:
121
121
 
122
122
  ```javascript
@@ -131,9 +131,7 @@ The SDK provides a method `AtomicSDK.logout` for clearing user-related data when
131
131
 
132
132
  The method accepts an optional parameter `deregisterNotifications`, a boolean that indicates whether the device should be deregistered for notifications upon logging out. This parameter only affects a Cordova integration at present as Web push notifications are currently not supported.
133
133
 
134
- **info:** New log-out behaviour
135
-
136
- As of Release 1.6.0, the following behaviours have been applied to this method:
134
+ **info:** log-out behavior
137
135
 
138
136
  - After logging out, you **must** log in to the SDK (by calling either `AtomicSDK.login` or `AtomicSDK.initialise` & `AtomicSDK.setSessionDelegate`) to proceed with another user. Otherwise, the Atomic SDK will raise exceptions.
139
137
  - This method also purges all cached card data stored by the SDK and disables all SDK activities.
@@ -181,13 +179,13 @@ Some configuration options are common for all types of container, other options
181
179
 
182
180
  #### Style and presentation
183
181
 
184
- A selection of UI elements can be customized within stream containers (this customization does **not apply to single card views**). These are configured using the `enabledUiElements` property on a stream container configuration object:
182
+ A selection of UI elements can be customized within stream containers (this customization does **not apply to single card views**, with the exception of `toastConfig`). These are configured using the `enabledUiElements` property on a stream container configuration object:
185
183
 
186
184
  - `cardListToast` - defaults to `true`. Set to `false` to turn off toast messages on the card list.
187
185
  - `customToastContainer` - defaults to `false`. Set to `true` to use an [alternative toast message presentation](https://documentation.atomic.io/sdks/web#custom-toast-message-positioning) for standalone or launcher stream containers which allows you to reposition the toast message.
188
- - `toastConfig` - an optional configuration object to customise the toast messages displayed by the SDK.
186
+ - `toastConfig` - an optional configuration object to customize the toast messages displayed by the SDK.
189
187
  - `timeout`: optionally supply a number that sets how long the toast message should be displayed for in milliseconds.
190
- - `toastMessages`: an optional object where you can set custom strings for the following properties: `submittedCard`, `dismissedCard`, `snoozedCard` & `feedbackReceived`. These will be displayed as the toast message for the respective card event.
188
+ - `toastMessages`: an optional object where you can set custom strings for the following properties: `submittedCard`, `dismissedCard`, `snoozedCard`, `feedbackReceived` & `fileUploadFailed`. These will be displayed as the toast message for the respective card event.
191
189
  - `cardListHeader` - defaults to `true`. Set to `false` to disable the display of the title at the top of the card list.
192
190
  - `customContainerHeader` - can optionally supply a custom header to be displayed above the card feed when displaying a `launch` or `embed` type stream container.
193
191
  - `scrollHeader`: an optional boolean to control whether the custom header scrolls with the card feed, defaults to `true`.
@@ -212,7 +210,8 @@ AtomicSDK.launch({
212
210
  submittedCard: 'Custom submitted message',
213
211
  dismissedCard: 'Custom dismissed message',
214
212
  snoozedCard: 'Custom snoozed message',
215
- feedbackReceived: 'Custom feedback message'
213
+ feedbackReceived: 'Custom feedback message',
214
+ fileUploadFailed: 'Custom file upload failed message'
216
215
  }
217
216
  },
218
217
  cardListHeader: true,
@@ -239,15 +238,15 @@ AtomicSDK.launch({
239
238
  - `onRuntimeVariablesRequested`: an optional property that can be used on the configuration object to allow your app to resolve runtime variables. If this callback is not implemented, runtime variables will fall back to their default values, as defined in the Atomic Workbench.
240
239
  - `runtimeVariableResolutionTimeout` defaults to 5 seconds (5000 ms) if not provided.
241
240
 
242
- Read more about runtime variables in the [Runtime variables section](#runtime-variables).
241
+ Read more about runtime variables in the [Runtime variables section](https://documentation.atomic.io/sdks/web#runtime-variables).
243
242
 
244
243
  ##### CardListRefreshInterval
245
244
 
246
245
  As of release 0.18.0, the Atomic Web SDK uses WebSockets to keep the card list up-to-date.
247
246
 
248
- If a WebSocket connection cannot be established, or is not permitted, the SDK will revert to polling for new cards, which is the behaviour in SDK versions prior to 0.18.0. Also if the SDK has been configured to use HTTP for its communication protocol, via the [`setApiProtocol`](#configuring-api-communication-protocol) method, polling will be used to update the card list.
247
+ If a WebSocket connection cannot be established, or is not permitted, the SDK will revert to polling for new cards, which is the behavior in SDK versions prior to 0.18.0. Also if the SDK has been configured to use HTTP for its communication protocol, via the [`setApiProtocol`](https://documentation.atomic.io/sdks/web#configuring-api-communication-protocol) method, polling will be used to update the card list.
249
248
 
250
- When the SDK reverts to polling, it will check for new cards every 15 seconds by default. You can customise how frequently this happens by specifying a value for the `cardListRefreshInterval` configuration option:
249
+ When the SDK reverts to polling, it will check for new cards every 15 seconds by default. You can customize how frequently this happens by specifying a value for the `cardListRefreshInterval` configuration option:
251
250
 
252
251
  ```js
253
252
  AtomicSDK.launch({
@@ -270,6 +269,8 @@ You can customize the following strings used by the Web SDK, using the `customSt
270
269
  - The error message shown when the user does not have an internet connection (`noInternetConnectionMessage`).
271
270
  - The error message shown when the theme or card list cannot be loaded due to an API error (`dataLoadFailedMessage`).
272
271
  - The title of the button allowing the user to retry the failed request for the card list or theme (`tryAgainTitle`).
272
+ - The text displayed on the card overlay while a file upload is in progress (`processingStateMessage`).
273
+ - The title of the button on the card overlay allowing the user to cancel file uploads that are currently in progress (`processingStateCancelButtonTitle`).
273
274
 
274
275
  If you don't provide these custom strings, the SDK defaults will be used:
275
276
 
@@ -283,6 +284,8 @@ If you don't provide these custom strings, the SDK defaults will be used:
283
284
  - `noInternetConnectionMessage`: "No internet connection"
284
285
  - `dataLoadFailedMessage`: "Couldn't load data"
285
286
  - `tryAgainTitle`: "Try again"
287
+ - `processingStateMessage`: "Sending, please wait..."
288
+ - `processingStateCancelButtonTitle`: "Cancel process"
286
289
 
287
290
  The code snippet below shows how to customize some of these strings.
288
291
 
@@ -296,7 +299,12 @@ AtomicSDK.launch({
296
299
  cardSnoozeTitle: 'Snooze',
297
300
  votingUsefulTitle: 'Positive feedback',
298
301
  votingNotUsefulTitle: 'Negative feedback',
299
- votingFeedbackTitle: 'Tell us more'
302
+ votingFeedbackTitle: 'Tell us more',
303
+ noInternetConnectionMessage: 'No internet connection available',
304
+ dataLoadFailedMessage: 'Failed to load cards',
305
+ tryAgainTitle: 'Please try again',
306
+ processingStateMessage: 'File uploads in progress',
307
+ processingStateCancelButtonTitle: 'Cancel file upload'
300
308
  }
301
309
  });
302
310
  ```
@@ -305,7 +313,7 @@ AtomicSDK.launch({
305
313
 
306
314
  The Web SDK supports displaying a custom header above your card feed for stream containers created using the `launch` or `embed` methods. It has no effect for `singleCard` stream containers.
307
315
 
308
- The custom header is supplied as an HTML string to the `customContainerHeader` property of the [customized UI elements](#style-and-presentation). Styles should be applied inline to the HTML elements. Do not attempt to reference classes or other styling from your host application stylesheets because these will not be applied.
316
+ The custom header is supplied as an HTML string to the `customContainerHeader` property of the [customized UI elements](https://documentation.atomic.io/sdks/web#style-and-presentation). Styles should be applied inline to the HTML elements. Do not attempt to reference classes or other styling from your host application stylesheets because these will not be applied.
309
317
 
310
318
  #### Resizing standalone embeds to fit content
311
319
 
@@ -340,8 +348,6 @@ The minimum height is specified in pixels.
340
348
 
341
349
  #### Single card container toast messages
342
350
 
343
- _(introduced in 23.3.0)_
344
-
345
351
  Toast messages will now be displayed for the single card stream container. The toast messages are enabled by default, as they are for the other stream container variants. The single card toast message can be configured (or disabled) in the same way as they can for the other stream container variants, see the [style and presentation](https://documentation.atomic.io/sdks/web#style-and-presentation) section of the Web SDK for details on how to do this.
346
352
 
347
353
  The default position of single card toast notifications is in the centre at the bottom of the viewport and with a maximum width of 500px. The SDK exposes a class (`toast-container`) on the iframe containing the toast messages which can be used to apply your own styling should you wish to do so. See the CSS code snippet below for an example of how to reposition single card toasts to the bottom right of the viewport and with a smaller width, if your embed element id was `host-embed-element`.
@@ -380,7 +386,7 @@ The code sample below shows how to use the `AtomicSDK.launch(config)` method, to
380
386
  ...
381
387
  <body>
382
388
  <!-- Installation -->
383
- <script src="https://downloads.atomic.io/web-sdk/release/24.2.1/sdk.js"></script>
389
+ <script src="https://downloads.atomic.io/web-sdk/release/24.3.0/sdk.js"></script>
384
390
 
385
391
  <script>
386
392
  AtomicSDK.initialise('<apiHost>', '<apiKey>', '<environmentId>')
@@ -421,9 +427,9 @@ When creating a stream container in the launcher mode you can supply an optional
421
427
 
422
428
  ### Opening and closing the launcher externally
423
429
 
424
- If you choose to embed an Atomic stream container in the launcher mode (using `AtomicSDK.launch`), you can open or close the stream container from another trigger, such as a button or link, instead of using the launcher button in the bottom right of the screen. If required you can disable the built-in launcher button using the `enabledUiElements` property of the [customized UI elements](#style-and-presentation).
430
+ If you choose to embed an Atomic stream container in the launcher mode (using `AtomicSDK.launch`), you can open or close the stream container from another trigger, such as a button or link, instead of using the launcher button in the bottom right of the screen. If required you can disable the built-in launcher button using the `enabledUiElements` property of the [customized UI elements](https://documentation.atomic.io/sdks/web#style-and-presentation).
425
431
 
426
- Read the [manually controlling a launcher stream container](#manually-controlling-a-launcher-stream-container) section for more details.
432
+ Read the [manually controlling a launcher stream container](https://documentation.atomic.io/sdks/web#manually-controlling-a-launcher-stream-container) section for more details.
427
433
 
428
434
  ## Displaying a single card
429
435
 
@@ -455,7 +461,7 @@ The iframe generated by the `singleCard` method can be styled just like any othe
455
461
  ...
456
462
  <body>
457
463
  <!--Installation-->
458
- <script src="https://downloads.atomic.io/web-sdk/release/24.2.1/sdk.js"></script>
464
+ <script src="https://downloads.atomic.io/web-sdk/release/24.3.0/sdk.js"></script>
459
465
 
460
466
  <script>
461
467
  AtomicSDK.initialise('<apiHost>', '<apiKey>', '<environmentId>')
@@ -488,7 +494,7 @@ The iframe generated by the `embed` method can be styled just like any other DOM
488
494
  ...
489
495
  <body>
490
496
  <!--Installation-->
491
- <script src="https://downloads.atomic.io/web-sdk/release/24.2.1/sdk.js"></script>
497
+ <script src="https://downloads.atomic.io/web-sdk/release/24.3.0/sdk.js"></script>
492
498
 
493
499
  <script>
494
500
  AtomicSDK.initialise('<apiHost>', '<apiKey>', '<environmentId>')
@@ -565,14 +571,14 @@ The SDK provides the ability to create an "API-driven" card container that can b
565
571
  - `streamContainerId`: a string representing the id of the stream container you want to observe.
566
572
  - `cardFeedHandler`: a callback function that will be invoked with a `cards` parameter when the card feed is updated, this parameter is an array of cards.
567
573
  - `cardListRefreshInterval`: an optional number value representing the interval in milliseconds between HTTP polls of the card feed when the SDK is operating with the HTTP communication protocol, defaults to 15 seconds if not provided.
568
- - `onRuntimeVariablesRequested`: an optional function that the SDK will use to resolve runtime variables, read more about these in the [runtime variables section](#runtime-variables).
574
+ - `onRuntimeVariablesRequested`: an optional function that the SDK will use to resolve runtime variables, read more about these in the [runtime variables section](https://documentation.atomic.io/sdks/web#runtime-variables).
569
575
  - `runtimeVariableResolutionTimeout`: an optional number value representing the time in milliseconds the SDK will wait for your app to resolve runtime variables, defaults to 5 seconds if not provided.
570
- - `onCardCountChanged`: an optional callback function that will be invoked when the card count changes in the container, read more in the [onCardCountChanged callback section](#oncardcountchanged-callback).
571
- - `features`: an optional object that accepts one property `runtimeVariableAnalytics` which is a boolean value indicating whether [runtime variable analytics](#sdk-analytics) are enabled for this container.
576
+ - `onCardCountChanged`: an optional callback function that will be invoked when the card count changes in the container, read more in the [onCardCountChanged callback section](https://documentation.atomic.io/sdks/web#oncardcountchanged-callback).
577
+ - `features`: an optional object that accepts one property `runtimeVariableAnalytics` which is a boolean value indicating whether [runtime variable analytics](https://documentation.atomic.io/sdks/web#sdk-analytics) are enabled for this container.
572
578
 
573
- When you initialize one of these stream containers you are returned an instance of `AACHeadlessStreamContainer`. Calling the `start` method on this instance will start observing changes in the card feed, using either WebSockets or HTTP polling depending on how you have configured the SDK network protocol using [`AtomicSDK.setApiProtocol`](#configuring-api-communication-protocol). Updates to the card feed will be passed to the callback function provided as the `cardFeedHandler`.
579
+ When you initialize one of these stream containers you are returned an instance of `AACHeadlessStreamContainer`. Calling the `start` method on this instance will start observing changes in the card feed, using either WebSockets or HTTP polling depending on how you have configured the SDK network protocol using [`AtomicSDK.setApiProtocol`](https://documentation.atomic.io/sdks/web#configuring-api-communication-protocol). Updates to the card feed will be passed to the callback function provided as the `cardFeedHandler`.
574
580
 
575
- To stop observing card feed updates call the `stop` method on the instance. Observation will also stop when you call the [`AtomicSDK.logout`](#logging-out-the-current-user) method.
581
+ To stop observing card feed updates call the `stop` method on the instance. Observation will also stop when you call the [`AtomicSDK.logout`](https://documentation.atomic.io/sdks/web#logging-out-the-current-user) method.
576
582
 
577
583
  The following code snippet illustrates how to initialise one of these API-driven containers:
578
584
 
@@ -771,7 +777,7 @@ instance.setOpen(true);
771
777
 
772
778
  ### Manually controlling other stream container variants
773
779
 
774
- If you have a single card, horizontal or vertical stream container that is selectively displayed to the user (such as one that is hidden inside of a notification drawer) you need to inform the SDK when this stream container is "open" and viewable by the user. This is important so that analytics events such as `stream-displayed` & `card-displayed` are correctly dispatched. Failing to do so will result in an incorrect count of seen and unread cards, as described in the [retrieving the count of cards section](#retrieving-the-count-of-active-and-unseen-cards) of this guide.
780
+ If you have a single card, horizontal or vertical stream container that is selectively displayed to the user (such as one that is hidden inside of a notification drawer) you need to inform the SDK when this stream container is "open" and viewable by the user. This is important so that analytics events such as `stream-displayed` & `card-displayed` are correctly dispatched. Failing to do so will result in an incorrect count of seen and unread cards, as described in the [retrieving the count of cards section](https://documentation.atomic.io/sdks/web#retrieving-the-count-of-active-and-unseen-cards) of this guide.
775
781
 
776
782
  Use the `controlledContainerOpenState` feature flag in the configuration object when initialising your stream container. This ensures that your container will be initialised in the "closed" state. After initialisation of the container, it is then the responsibility of the host app to call the `setOpen` method on the stream container instance when the stream container is being displayed to or hidden from the user:
777
783
 
@@ -809,7 +815,7 @@ instance.stop()
809
815
 
810
816
  When a stream container with a given ID is launched for the first time on a user's device, the SDK loads the theme and caches it in the browser for future use. On subsequent launches of the same stream container, the cached theme is used and the theme is updated in the background, for the next launch. Note that this first time loading screen is not presented in single card view - if a single card view fails to load, it collapses to a height of 0.
811
817
 
812
- The SDK supports some basic properties to style the first time load screen, which displays a loading spinner in the center of the container. If the theme fails to load for the first time, an error message is displayed with a 'Try again' button. One of two default error messages are possible - 'Couldn't load data' or 'No internet connection'. See the [custom strings](#custom-strings) section of this guide if you want to change the default wording.
818
+ The SDK supports some basic properties to style the first time load screen, which displays a loading spinner in the center of the container. If the theme fails to load for the first time, an error message is displayed with a 'Try again' button. One of two default error messages are possible - 'Couldn't load data' or 'No internet connection'. See the [custom strings](https://documentation.atomic.io/sdks/web#custom-strings) section of this guide if you want to change the default wording.
813
819
 
814
820
  First time loading screen colors are customized using the following SDK configuration properties:
815
821
 
@@ -888,7 +894,7 @@ The filter value is used to filter cards in a stream container. The table below
888
894
 
889
895
  ### Filter operators
890
896
 
891
- The filter operator is the operational logic applied to a filter. The table below summarises the available operators as well as the value types each will accept. The available value types are further narrowed depending on which _**filter value**_ you are filtering on.
897
+ The filter operator is the operational logic applied to a filter. The table below summarizes the available operators as well as the value types each will accept. The available value types are further narrowed depending on which _**filter value**_ you are filtering on.
892
898
 
893
899
  | Operator | Description | Supported value types |
894
900
  | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
@@ -929,7 +935,7 @@ instance.streamFilters.clearFilters()
929
935
  _(introduced in 24.1.0)_
930
936
  _This is a beta feature in the Atomic Workbench_
931
937
 
932
- Image elements can be used to trigger a navigation action. In the Atomic Workbench you can configure the behavior of the link to trigger a subview navigation, open a URL or to send a payload to your app. For information on how to handle the image link payload see [custom action payloads on image links](#supporting-custom-action-payloads-on-image-links)
938
+ Image elements can be used to trigger a navigation action. In the Atomic Workbench you can configure the behavior of the link to trigger a subview navigation, open a URL or to send a payload to your app. For information on how to handle the image link payload see [custom action payloads on image links](https://documentation.atomic.io/sdks/web#supporting-custom-action-payloads-on-image-links)
933
939
 
934
940
  ## Custom action payloads
935
941
 
@@ -962,13 +968,13 @@ AtomicSDK.launch({
962
968
 
963
969
  ### Supporting custom action payloads on image links
964
970
 
965
- Similar to action payloads on buttons you can also create an image link with a custom action payload. When such an image is tapped, the `onLinkButtonPressed` callback is triggered and is passed an object with the same properties as for a [button with a custom action payload](#supporting-custom-action-payloads-on-link--submit-buttons).
971
+ Similar to action payloads on buttons you can also create an image link with a custom action payload. When such an image is tapped, the `onLinkButtonPressed` callback is triggered and is passed an object with the same properties as for a [button with a custom action payload](https://documentation.atomic.io/sdks/web#supporting-custom-action-payloads-on-link--submit-buttons).
966
972
 
967
973
  ## Customizing toast messages for card events
968
974
 
969
- You can customize any of the toast messages used when dismissing, completing, snoozing and placing feedback on a card. This is configurable for each stream container. You simply supply a string for each custom message. If you do not supply a string, the defaults will be used. See the [custom strings](#custom-strings) section of this guide if you want to change the default wording.
975
+ You can customize any of the toast messages used when dismissing, completing, snoozing and placing feedback on a card. This is configurable for each stream container. You simply supply a string for each custom message. If you do not supply a string, the defaults will be used. See the [custom strings](https://documentation.atomic.io/sdks/web#custom-strings) section of this guide if you want to change the default wording.
970
976
 
971
- Read the [Style and presentation section](#style-and-presentation) to understand how to do this using the `toastConfig` configuration object. That section also has a code example.
977
+ Read the [Style and presentation section](https://documentation.atomic.io/sdks/web#style-and-presentation) to understand how to do this using the `toastConfig` configuration object. That section also has a code example.
972
978
 
973
979
  ## Card snoozing
974
980
 
@@ -976,7 +982,19 @@ The Atomic SDKs provide the ability to snooze a card from a stream container or
976
982
 
977
983
  Selecting snooze option from either location brings up the snooze date and time selection screen. The user selects a date and time in the future until which the card will be snoozed. Snoozing a card will result in the card disappearing from the user’s card list or single card view, and reappearing again at the selected date and time. A user can snooze a card more than once.
978
984
 
979
- See the [custom strings](#custom-strings) section of this guide if you want to change the default wording.
985
+ See the [custom strings](https://documentation.atomic.io/sdks/web#custom-strings) section of this guide if you want to change the default wording.
986
+
987
+ ### Preventing snoozing beyond card expiry date
988
+
989
+ Selecting a date & time combination beyond a card's expiry date is prevented when snoozing a card using the SDK's built-in interface.
990
+
991
+ There are three ways to snooze a card in the Atomic SDK:
992
+
993
+ 1. **Overflow Menu**: Select the overflow menu item (default "Remind me"), then choose a date & time in the built-in selector.
994
+ 2. **Snooze Button**: Click a snooze button on the card and select a date & time via the built-in selector.
995
+ 3. **Pre-set Snooze Button**: Click a snooze button with a pre-set snooze period, which snoozes the card immediately without showing the selector.
996
+
997
+ If an expiry date is set on the card, you cannot select dates beyond this expiry in scenarios 1 and 2. Scenario 3 remains unaffected, as the snooze period is explicitly pre-configured in the Workbench.
980
998
 
981
999
  ## Card voting
982
1000
 
@@ -992,7 +1010,7 @@ If they indicate that the card was not useful, they are presented with a seconda
992
1010
 
993
1011
  If they select "Something else", a free-form input is presented, where the user can provide additional feedback. The free form input is limited to 280 characters. After tapping "Submit", an analytics event containing this feedback is sent (`card-voted-down`).
994
1012
 
995
- See the [custom strings](#custom-strings) section of this guide if you want to change the default wording.
1013
+ See the [custom strings](https://documentation.atomic.io/sdks/web#custom-strings) section of this guide if you want to change the default wording.
996
1014
 
997
1015
  Card voting is disabled by default. You can enable positive card voting ("This is useful"), negative card voting ("This isn’t useful"), or both:
998
1016
 
@@ -1044,7 +1062,7 @@ The identifier for the event is available in the `type` property, and will be on
1044
1062
 
1045
1063
  ## Sending custom events
1046
1064
 
1047
- A custom event can be used in the Workbench to create segments for card targeting. For more details of custom events, see [Custom Events](../advanced/analytics#custom-events).
1065
+ A custom event can be used in the Workbench to create segments for card targeting. For more details of custom events, see [Custom Events](https://documentation.atomic.io/guide/customers/custom-events#sending-custom-events-to-atomic).
1048
1066
 
1049
1067
  You can send custom events directly to the Atomic Platform for the logged in user, via the `sendCustomEvent` method, passing it an object with an `eventName` and optionally `properties` where you can add additional data for your event.
1050
1068
 
@@ -1063,8 +1081,6 @@ AtomicSDK.sendCustomEvent({
1063
1081
 
1064
1082
  ## SDK Event Observer
1065
1083
 
1066
- _(introduced in 23.3.0)_
1067
-
1068
1084
  The SDK provides the ability to observe actions within the SDK via the SDK event observer, this observer is a callback that you set via the `observeSDKEvents` SDK method. The callback will be invoked with an event object that conforms to a particular event type.
1069
1085
 
1070
1086
  The code snippet below shows how to set the event observer callback:
@@ -1077,27 +1093,30 @@ AtomicSDK.observeSDKEvents(event => {
1077
1093
 
1078
1094
  The actions that will trigger this callback include card & stream actions, the table below contains the full list of actions that the event observer may be called with and their corresponding event type.
1079
1095
 
1080
- | Event name | Event type | Description |
1081
- | :----------------------- | :----------------------------- | :--------------------------------------------------------------------------------------------------------- |
1082
- | card-completed | SDKCardCompletedEvent | The user has completed a card |
1083
- | card-dismissed | SDKCardDismissedEvent | The user has dismissed a card |
1084
- | card-snoozed | SDKCardSnoozedEvent | The user has snoozed a card |
1085
- | card-feed-updated | SDKFeedEvent | A stream container has had its card feed updated |
1086
- | card-displayed | SDKCardDisplayedEvent | A card has been displayed to the user |
1087
- | card-voted-up | SDKCardVotedUpEvent | The user provided positive feedback on a card |
1088
- | card-voted-down | SDKCardVotedDownEvent | The user provided negative feedback on a card |
1089
- | runtime-vars-updated | SDKRuntimeVarsUpdatedEvent | One or more runtime variables have been resolved |
1090
- | stream-displayed | SDKStreamDisplayedEvent | A stream container has been displayed to the user |
1091
- | user-redirected | SDKRedirectedEvent | The user is redirected by a URL or a custom payload |
1092
- | snooze-options-displayed | SDKSnoozeOptionsDisplayedEvent | The snooze date/time selector has been displayed |
1093
- | snooze-options-canceled | SDKSnoozeOptionsCanceledEvent | The user has exited the snooze date/time selector |
1094
- | card-subview-displayed | SDKSubviewDisplayedEvent | A card subview has been opened |
1095
- | card-subview-exited | SDKSubviewExitedEvent | A card subview has been exited |
1096
- | video-played | SDKVideoPlayedEvent | The user has started playback of a video |
1097
- | video-completed | SDKVideoCompletedEvent | The user has watched a video to completion |
1098
- | sdk-initialized | SDKInitEvent | The SDK has been initialized and supplied with a valid auth token |
1099
- | request-failed | SDKRequestFailedEvent | A request to the Atomic client API has failed or a WebSocket failure has caused a fallback to HTTP polling |
1100
- | notification-received | SDKNotificationReceivedEvent | A push notification has been received |
1096
+ | Event name | Event type | Description |
1097
+ | :-------------------------- | :------------------------------- | :--------------------------------------------------------------------------------------------------------- |
1098
+ | card-completed | SDKCardCompletedEvent | The user has completed a card |
1099
+ | card-dismissed | SDKCardDismissedEvent | The user has dismissed a card |
1100
+ | card-snoozed | SDKCardSnoozedEvent | The user has snoozed a card |
1101
+ | card-feed-updated | SDKFeedEvent | A stream container has had its card feed updated |
1102
+ | card-displayed | SDKCardDisplayedEvent | A card has been displayed to the user |
1103
+ | card-voted-up | SDKCardVotedUpEvent | The user provided positive feedback on a card |
1104
+ | card-voted-down | SDKCardVotedDownEvent | The user provided negative feedback on a card |
1105
+ | runtime-vars-updated | SDKRuntimeVarsUpdatedEvent | One or more runtime variables have been resolved |
1106
+ | stream-displayed | SDKStreamDisplayedEvent | A stream container has been displayed to the user |
1107
+ | user-redirected | SDKRedirectedEvent | The user is redirected by a URL or a custom payload |
1108
+ | snooze-options-displayed | SDKSnoozeOptionsDisplayedEvent | The snooze date/time selector has been displayed |
1109
+ | snooze-options-canceled | SDKSnoozeOptionsCanceledEvent | The user has exited the snooze date/time selector |
1110
+ | card-subview-displayed | SDKSubviewDisplayedEvent | A card subview has been opened |
1111
+ | card-subview-exited | SDKSubviewExitedEvent | A card subview has been exited |
1112
+ | video-played | SDKVideoPlayedEvent | The user has started playback of a video |
1113
+ | video-completed | SDKVideoCompletedEvent | The user has watched a video to completion |
1114
+ | sdk-initialized | SDKInitEvent | The SDK has been initialized and supplied with a valid auth token |
1115
+ | request-failed | SDKRequestFailedEvent | A request to the Atomic client API has failed or a WebSocket failure has caused a fallback to HTTP polling |
1116
+ | notification-received | SDKNotificationReceivedEvent | A push notification has been received |
1117
+ | user-file-uploads-started | SDKUserFileUploadsStartedEvent | A user has started the process of uploading files for a card |
1118
+ | user-file-uploads-completed | SDKUserFileUploadsCompletedEvent | A user has successfully completed the process of uploading files for a card |
1119
+ | user-file-uploads-failed | SDKUserFileUploadsFailedEvent | A user has completed the process of uploading files, with one or more uploads failing |
1101
1120
 
1102
1121
  ### Accessing properties for a particular event
1103
1122
 
@@ -1114,9 +1133,7 @@ AtomicSDK.observeSDKEvents(event => {
1114
1133
  })
1115
1134
  ```
1116
1135
 
1117
- :::info
1118
1136
  There are some additional properties on the event objects not specified in the types or the provided examples. These properties are provided for debugging purposes and are subject to change so should not be relied upon in production code.
1119
- :::
1120
1137
 
1121
1138
  ### Stopping event observation
1122
1139
 
@@ -1126,6 +1143,86 @@ To stop observing events call the `observeSDKEvents` SDK method passing in a `nu
1126
1143
  AtomicSDK.observeSDKEvents(null)
1127
1144
  ```
1128
1145
 
1146
+ ### Metadata pass-through
1147
+
1148
+ Any metadata sent from an API request can now be accessed from within the SDK using the [SDK Event Observer](https://documentation.atomic.io/sdks/web#sdk-event-observer), once [enabled](https://documentation.atomic.io/guide/configuration/metadata) in the Workbench
1149
+
1150
+ Currently the metadata is only returned in the _card-displayed_ event.
1151
+
1152
+ An example body in an API request to an Action Flow trigger endpoint might look like:
1153
+
1154
+ ```json
1155
+ {
1156
+ "flows": [
1157
+ {
1158
+ "payload": {
1159
+ "metadata": {
1160
+ "account": "123445",
1161
+ "fruit": "apple"
1162
+ }
1163
+ },
1164
+ "target": {
1165
+ "type": "user",
1166
+ "targetUserIds": "user-123"
1167
+ }
1168
+ }
1169
+ ]
1170
+ }
1171
+ ```
1172
+
1173
+ To retrieve the metadata just capture the card-displayed event in an SDK Event Observer, such as:
1174
+
1175
+ ```Javascript
1176
+ AtomicSDK.observeSDKEvents(event => {
1177
+ if (event.eventName === "card-displayed") {
1178
+ console.log(JSON.stringify(event));
1179
+ }
1180
+ });
1181
+ ```
1182
+
1183
+ The json returned in the event data will take the following shape:
1184
+
1185
+ ```json
1186
+ {
1187
+ "id": "043195e2-8b1d-40b2-b4f2-12a70bd1467e",
1188
+ "endUserId": "user-123",
1189
+ "timestamp": "2024-08-27T23:13:18.587Z",
1190
+ "properties": {
1191
+ "account": "123445",
1192
+ "fruit": "apple"
1193
+ },
1194
+ "eventContext": {
1195
+ "userLocalTimestamp": "2024-08-28T11:13:18.587+12:00"
1196
+ },
1197
+ "analyticsEvent": "card-displayed",
1198
+ "hostContext": {},
1199
+ "sdkContext": {
1200
+ "containerId": "my-container"
1201
+ },
1202
+ "streamContext": {
1203
+ "streamLength": 0,
1204
+ "streamLengthVisible": 1,
1205
+ "cardPositionInStream": 1
1206
+ },
1207
+ "cardContext": {
1208
+ "cardInstanceId": "286c3fe4-a0ad-5879-a585-9736de8e2cdb",
1209
+ "cardInstanceStatus": "active",
1210
+ "cardViewState": "topview",
1211
+ "cardPresentation": "individual"
1212
+ },
1213
+ "eventName": "card-displayed"
1214
+ }
1215
+ ```
1216
+
1217
+ The metadata is included in the properties object:
1218
+
1219
+ ```json
1220
+ "properties": {
1221
+ "account": "123445",
1222
+ "fruit": "apple"
1223
+ },
1224
+ ```
1225
+
1129
1226
  ### Event observer use cases
1130
1227
 
1131
1228
  #### Trigger a user metrics request on SDK event
@@ -1200,7 +1297,7 @@ AtomicSDK.registerStreamContainersForNotifications([containerId])
1200
1297
 
1201
1298
  You will need to do this each time the logged-in user changes.
1202
1299
 
1203
- This method takes an optional parameter - `notificationsEnabled`. This parameter updates the user's `notificationsEnabled` preference in the Atomic Platform. You can also inspect and update this preference using the [Atomic API documentation for user preferences](../api/user-preferences#notificationsenabled) or using the [updateUser method](#updating-user-data).
1300
+ This method takes an optional parameter - `notificationsEnabled`. This parameter updates the user's `notificationsEnabled` preference in the Atomic Platform. You can also inspect and update this preference using the [Atomic API documentation for user preferences](https://documentation.atomic.io/api/user-preferences#notificationsenabled) or using the [updateUser method](https://documentation.atomic.io/sdks/web#updating-user-data).
1204
1301
 
1205
1302
  If you pass `false` for this parameter, the user's `notificationsEnabled` preference will be set to `false`, which means that they will not receive notifications on any eligible devices, even if their device is registered in this step, and the device push token is passed to Atomic in the next step. If you pass `true`, the user's `notificationEnabled` preference will be set to `true`, which is the default, and allows the user to receive notifications on any eligible device. This allows you to explicitly enable or disable notifications for the current user, via UI in your own app - such as a notification settings screen.
1206
1303
 
@@ -1276,7 +1373,7 @@ push.on('notification', data => {
1276
1373
 
1277
1374
  Due to the limitations of the mobile platforms, tracking when a push notification is received is not straightforward if the app is not open when the notification is received.
1278
1375
 
1279
- On iOS, to track when push notifications are delivered to your user's device you must use a native [Notification Service Extension](https://developer.apple.com/documentation/usernotifications/unnotificationserviceextension). This requires you to write native code and to use our iOS native SDK - further information on tracking notification receipt is available in the [iOS SDK guide](../sdks/ios).
1376
+ On iOS, to track when push notifications are delivered to your user's device you must use a native [Notification Service Extension](https://developer.apple.com/documentation/usernotifications/unnotificationserviceextension). This requires you to write native code and to use our iOS native SDK - further information on tracking notification receipt is available in the [iOS SDK guide](https://documentation.atomic.io/sdks/ios).
1280
1377
 
1281
1378
  On Android tracking if the notification is received in the background is not supported by the Atomic SDK, but delivery can be tracked using Firebase.
1282
1379
 
@@ -1331,7 +1428,7 @@ AtomicSDK.requestUserMetrics()
1331
1428
 
1332
1429
  Open and viewable containers
1333
1430
 
1334
- If you have a single card, horizontal or vertical stream container that is selectively displayed to the user (such as one that is hidden inside of a notification drawer) you need to inform the SDK when this stream container is "open" and viewable by the user to make sure the card count is updated correctly. See the [manually controlling the open state of a stream container](#manually-controlling-the-open-state-of-a-stream-container) section for detailed instructions on how to do this.
1431
+ If you have a single card, horizontal or vertical stream container that is selectively displayed to the user (such as one that is hidden inside of a notification drawer) you need to inform the SDK when this stream container is "open" and viewable by the user to make sure the card count is updated correctly. See the [manually controlling the open state of a stream container](https://documentation.atomic.io/sdks/web#manually-controlling-the-open-state-of-a-stream-container) section for detailed instructions on how to do this.
1335
1432
 
1336
1433
  ### onCardCountChanged callback
1337
1434
 
@@ -1408,11 +1505,11 @@ instance.updateVariables();
1408
1505
 
1409
1506
  ## Accessibility
1410
1507
 
1411
- Accessibility attributes, such as appropriate titles and ARIA attributes, are available as of SDK release 0.13.0.
1508
+ Accessibility attributes, such as appropriate titles and ARIA attributes, are available.
1412
1509
 
1413
1510
  ### Alternate text
1414
1511
 
1415
- As of SDK 0.19.1, alternate text is supported on all image and video components. This alternate text is supplied by you when authoring a card, and is used to describe the image or video itself. Alternate text forms part of a description that is passed to the system screen reader (when enabled).
1512
+ Alternate text is supported on all image and video components. This alternate text is supplied by you when authoring a card, and is used to describe the image or video itself. Alternate text forms part of a description that is passed to the system screen reader (when enabled).
1416
1513
 
1417
1514
  The following description is used for each image or video format:
1418
1515
 
@@ -1470,27 +1567,30 @@ AtomicSDK.observeSDKEvents(event => {
1470
1567
 
1471
1568
  The actions that will trigger this callback include card & stream actions, the table below contains the full list of actions that the event observer may be called with and their corresponding event type.
1472
1569
 
1473
- | Event name | Event type | Description |
1474
- | :----------------------- | :----------------------------- | :--------------------------------------------------------------------------------------------------------- |
1475
- | card-completed | SDKCardCompletedEvent | The user has completed a card |
1476
- | card-dismissed | SDKCardDismissedEvent | The user has dismissed a card |
1477
- | card-snoozed | SDKCardSnoozedEvent | The user has snoozed a card |
1478
- | card-feed-updated | SDKFeedEvent | A stream container has had its card feed updated |
1479
- | card-displayed | SDKCardDisplayedEvent | A card has been displayed to the user |
1480
- | card-voted-up | SDKCardVotedUpEvent | The user provided positive feedback on a card |
1481
- | card-voted-down | SDKCardVotedDownEvent | The user provided negative feedback on a card |
1482
- | runtime-vars-updated | SDKRuntimeVarsUpdatedEvent | One or more runtime variables have been resolved |
1483
- | stream-displayed | SDKStreamDisplayedEvent | A stream container has been displayed to the user |
1484
- | user-redirected | SDKRedirectedEvent | The user is redirected by a URL or a custom payload |
1485
- | snooze-options-displayed | SDKSnoozeOptionsDisplayedEvent | The snooze date/time selector has been displayed |
1486
- | snooze-options-canceled | SDKSnoozeOptionsCanceledEvent | The user has exited the snooze date/time selector |
1487
- | card-subview-displayed | SDKSubviewDisplayedEvent | A card subview has been opened |
1488
- | card-subview-exited | SDKSubviewExitedEvent | A card subview has been exited |
1489
- | video-played | SDKVideoPlayedEvent | The user has started playback of a video |
1490
- | video-completed | SDKVideoCompletedEvent | The user has watched a video to completion |
1491
- | sdk-initialized | SDKInitEvent | The SDK has been initialized and supplied with a valid auth token |
1492
- | request-failed | SDKRequestFailedEvent | A request to the Atomic client API has failed or a WebSocket failure has caused a fallback to HTTP polling |
1493
- | notification-received | SDKNotificationReceivedEvent | A push notification has been received |
1570
+ | Event name | Event type | Description |
1571
+ | :-------------------------- | :------------------------------- | :--------------------------------------------------------------------------------------------------------- |
1572
+ | card-completed | SDKCardCompletedEvent | The user has completed a card |
1573
+ | card-dismissed | SDKCardDismissedEvent | The user has dismissed a card |
1574
+ | card-snoozed | SDKCardSnoozedEvent | The user has snoozed a card |
1575
+ | card-feed-updated | SDKFeedEvent | A stream container has had its card feed updated |
1576
+ | card-displayed | SDKCardDisplayedEvent | A card has been displayed to the user |
1577
+ | card-voted-up | SDKCardVotedUpEvent | The user provided positive feedback on a card |
1578
+ | card-voted-down | SDKCardVotedDownEvent | The user provided negative feedback on a card |
1579
+ | runtime-vars-updated | SDKRuntimeVarsUpdatedEvent | One or more runtime variables have been resolved |
1580
+ | stream-displayed | SDKStreamDisplayedEvent | A stream container has been displayed to the user |
1581
+ | user-redirected | SDKRedirectedEvent | The user is redirected by a URL or a custom payload |
1582
+ | snooze-options-displayed | SDKSnoozeOptionsDisplayedEvent | The snooze date/time selector has been displayed |
1583
+ | snooze-options-canceled | SDKSnoozeOptionsCanceledEvent | The user has exited the snooze date/time selector |
1584
+ | card-subview-displayed | SDKSubviewDisplayedEvent | A card subview has been opened |
1585
+ | card-subview-exited | SDKSubviewExitedEvent | A card subview has been exited |
1586
+ | video-played | SDKVideoPlayedEvent | The user has started playback of a video |
1587
+ | video-completed | SDKVideoCompletedEvent | The user has watched a video to completion |
1588
+ | sdk-initialized | SDKInitEvent | The SDK has been initialized and supplied with a valid auth token |
1589
+ | request-failed | SDKRequestFailedEvent | A request to the Atomic client API has failed or a WebSocket failure has caused a fallback to HTTP polling |
1590
+ | notification-received | SDKNotificationReceivedEvent | A push notification has been received |
1591
+ | user-file-uploads-started | SDKUserFileUploadsStartedEvent | A user has started the process of uploading files for a card |
1592
+ | user-file-uploads-completed | SDKUserFileUploadsCompletedEvent | A user has successfully completed the process of uploading files for a card |
1593
+ | user-file-uploads-failed | SDKUserFileUploadsFailedEvent | A user has completed the process of uploading files, with one or more uploads failing |
1494
1594
 
1495
1595
  ### Accessing properties for a particular event
1496
1596
 
@@ -1505,9 +1605,7 @@ AtomicSDK.observeSDKEvents(event => {
1505
1605
  })
1506
1606
  ```
1507
1607
 
1508
- :::info
1509
1608
  There are some additional properties on the event objects not specified in the types or the provided examples. These properties are provided for debugging purposes and are subject to change so should not be relied upon.
1510
- :::
1511
1609
 
1512
1610
  ### Stopping event observation
1513
1611
 
@@ -1547,7 +1645,7 @@ The user update object has two optional properties, `profile` & `preferences`, e
1547
1645
 
1548
1646
  ### Profile fields
1549
1647
 
1550
- The following optional profile fields can be supplied to update the data for the user. Any fields which have not been supplied will remain unmodified after the user update. Further custom fields can be supplied, however these must first be defined in the workbench as described in the [Custom fields](../workbench/customers.md#custom-fields) section of the documentation.
1648
+ The following optional profile fields can be supplied to update the data for the user. Any fields which have not been supplied will remain unmodified after the user update. Further custom fields can be supplied, however these must first be defined in the workbench as described in the [Custom fields](https://documentation.atomic.io/guide/customers/custom-fields#add-a-custom-field) section of the documentation.
1551
1649
 
1552
1650
  - `external_id`: An optional string that can be used as an identifier for the user.
1553
1651
  - `name`: An optional string.
@@ -1607,51 +1705,76 @@ const userUpdateObject = {
1607
1705
  AtomicSDK.updateUser(userUpdateObject)
1608
1706
  ```
1609
1707
 
1610
- ## Utility methods
1708
+ ## File Upload
1611
1709
 
1612
- ### Debug logging
1710
+ _This is currently a preview feature in the Workbench_
1613
1711
 
1614
- Enable debug logging to view verbose logs of activity within the SDK, output to the browser console. Debug logging is disabled by default, and should not be enabled in release builds.
1712
+ ### Card & feed overlay during file upload
1615
1713
 
1616
- ```javascript
1617
- AtomicSDK.enableDebugMode(level)
1618
- ```
1714
+ The file upload process will commence when a user attempts to submit a card that has files attached. While the file upload is in progress the card (or card subview when submitting from a subview) will be replaced with an overlay to prevent user interaction while this takes place. This overlay displays a loading indicator, a message indicating what is taking place, and a button that may be used to cancel the file upload.
1619
1715
 
1620
- The level parameter is a number that indicates the verbosity of the logs exposed:
1716
+ If the card is within a launcher, vertical or horizontal stream container variant, any other cards within the feed will be covered by a scrim while the upload is in progress, to prevent user interaction with other cards in the feed and visually indicate that the upload has not finished.
1621
1717
 
1622
- - Level 0: Default, no logs exposed
1623
- - Level 1: Operations and transactions are exposed
1624
- - Level 2: Operations, transactions and its details are exposed, plus level 1.
1625
- - Level 3: Internal developer logs, plus level 2
1718
+ #### Single card & Horizontal stream container overlay
1626
1719
 
1627
- ### Error handling
1720
+ The modal iframe, used to present subviews in the single card & horizontal stream containers, has an 'uploading-files' class added to the iframe element while there is a file upload in progress. This can be used to trigger any UI you may wish to display in your application while the file upload is in progress.
1628
1721
 
1629
- The SDK allows you to set a callback via the `AtomicSDK.onError` property. This passes javascript errors that may occur in the SDK.
1722
+ The following code snippet is an example of how you could detect this:
1630
1723
 
1631
1724
  ```js
1632
- AtomicSDK.onError = function (error) {
1633
- // handle the reported error as required
1634
- console.error('An error occured in the Atomic SDK: ', error)
1635
- }
1725
+ // An observer to observe changes in the modal subview iframe class list
1726
+ const observer = new MutationObserver(mutations => {
1727
+ mutations.forEach(mutation => {
1728
+ if (mutation.target.classList.contains('uploading-files')) {
1729
+ // Uploading has commenced, modify UI as required
1730
+ } else {
1731
+ // Uploading has finished, modify UI as required
1732
+ }
1733
+ })
1734
+ })
1735
+
1736
+ // Observe changes in the relevant modal subview, in this case one that
1737
+ // has been embedded inside of a host element with the ID "embed-container".
1738
+ observer.observe(document.querySelector('#embed-container>.modal-subview'), {
1739
+ attributeFilter: ['class']
1740
+ })
1636
1741
  ```
1637
1742
 
1638
- The callback you set will receive errors that occur within the stream containers you have created. If you do not set this callback, errors will instead be logged to the browser console.
1743
+ ### Custom strings
1639
1744
 
1640
- Errors resulting from communication between the SDK & the Atomic platform, such as authentication & network errors, will be logged via the [debug logger](#debug-logging) at the level of verbosity you have chosen. These logs can be observed in the browser console and will be a string consisting of the error name and error description.
1745
+ The card overlay message & cancel button label text can be customized using the [custom strings](https://documentation.atomic.io/sdks/web#custom-strings) feature of the SDK. If you wish to change the text used you would supply a value for the `processingStateMessage` and/or the `processingStateCancelButtonTitle` for the stream container(s) that you wanted to customize this for.
1641
1746
 
1642
- ### Setting the version of the client app
1747
+ ### Toast message
1643
1748
 
1644
- The SDK provides a method `AtomicSDK.setClientAppVersion` for setting the current version of your app. This app version is attached to generated analytics events to make it easy to track issues between app versions and to get insight into version usage.
1749
+ If a file upload fails to successfully complete the user will be displayed a toast message indicating this and providing the option to retry. By default the text of this message will be "Couldn't upload file(s)", if you wish to customize this you may do so via the [toast config](https://documentation.atomic.io/sdks/web#style-and-presentation) configuration object for the stream container, setting a value for the `fileUploadFailed` toast message.
1645
1750
 
1646
- Version strings have a maximum length of 128 characters, if you supply a longer string it will be trimmed to that length.
1751
+ ### SDK events
1647
1752
 
1648
- The following example sets the client app version to `Version 2.3.1`.
1753
+ There are new events that are emitted during the file upload process. When a user attempts to submit a card that has files attached, the file upload process will commence and these events can be used to track its progression:
1754
+
1755
+ - `user-file-uploads-started`, emitted once the file upload process has started.
1756
+ - `user-file-uploads-completed`, emitted once the file upload process has completed, with all files having been successfully uploaded.
1757
+ - `user-file-uploads-failed`, emitted once the file upload process has completed or been cancelled, with one or more files having failed to upload.
1758
+
1759
+ These events can be observed using the [SDK event observer](https://documentation.atomic.io/sdks/web#sdk-event-observer). The details for the relevant files are found in the `properties` of the event object, keyed by the form field they were submitted, for example:
1649
1760
 
1650
1761
  ```js
1651
- AtomicSDK.setClientAppVersion('Version 2.3.1')
1762
+ {
1763
+ eventName: "user-file-uploads-completed",
1764
+ ...
1765
+ properties: {
1766
+ upload_fieldname: {
1767
+ filename: "filename_in_S3_bucket.png",
1768
+ targetBucketId: "S3_bucket_id"
1769
+ }
1770
+ }
1771
+ }
1652
1772
  ```
1653
1773
 
1654
- ## Custom icons {#custom-icons}
1774
+ **Upload cancellation events**
1775
+ Currently, no event is generated to indicate when a user cancels an upload. We will add a corresponding SDK event in upcoming versions.
1776
+
1777
+ ## Custom icons
1655
1778
 
1656
1779
  _(introduced in 24.2.0)_
1657
1780
 
@@ -1684,7 +1807,7 @@ If the provided SVG image fails to load due to a broken URL or network issues th
1684
1807
  1. The fallback FontAwesome icon is used if it is set in Atomic Workbench for this custom icon.
1685
1808
  2. Otherwise, a default placeholder image is displayed.
1686
1809
 
1687
- ## Image things {#media-display-height}
1810
+ ## Image things
1688
1811
 
1689
1812
  _(introduced in 24.2.0)_
1690
1813
 
@@ -1707,10 +1830,10 @@ To use the SDK with your Cordova or Capacitor app:
1707
1830
 
1708
1831
  1. Download the Atomic SDK from our CDN, and bundle it with your application. There are two files you need to download:
1709
1832
 
1710
- - `https://downloads.atomic.io/web-sdk/release/24.2.1/iframe-manager.js`
1711
- - `https://downloads.atomic.io/web-sdk/release/24.2.1/sdk.js`
1833
+ - `https://downloads.atomic.io/web-sdk/release/24.3.0/iframe-manager.js`
1834
+ - `https://downloads.atomic.io/web-sdk/release/24.3.0/sdk.js`
1712
1835
 
1713
- _Where `24.2.1` is the version number of the SDK you wish to use._
1836
+ _Where `24.3.0` is the version number of the SDK you wish to use._
1714
1837
 
1715
1838
  2. **(Cordova only)**: Modify the `Content-Security-Policy` meta tag in your Cordova app to allow the following URLs, after the `default-src` directive:
1716
1839
 
@@ -1751,9 +1874,53 @@ To use the SDK with your Cordova or Capacitor app:
1751
1874
  </html>
1752
1875
  ```
1753
1876
 
1877
+ ## Utility methods
1878
+
1879
+ ### Debug logging
1880
+
1881
+ Enable debug logging to view verbose logs of activity within the SDK, output to the browser console. Debug logging is disabled by default, and should not be enabled in release builds.
1882
+
1883
+ ```javascript
1884
+ AtomicSDK.enableDebugMode(level)
1885
+ ```
1886
+
1887
+ The level parameter is a number that indicates the verbosity of the logs exposed:
1888
+
1889
+ - Level 0: Default, no logs exposed
1890
+ - Level 1: Operations and transactions are exposed
1891
+ - Level 2: Operations, transactions and its details are exposed, plus level 1.
1892
+ - Level 3: Internal developer logs, plus level 2
1893
+
1894
+ ### Error handling
1895
+
1896
+ The SDK allows you to set a callback via the `AtomicSDK.onError` property. This passes javascript errors that may occur in the SDK.
1897
+
1898
+ ```js
1899
+ AtomicSDK.onError = function (error) {
1900
+ // handle the reported error as required
1901
+ console.error('An error occured in the Atomic SDK: ', error)
1902
+ }
1903
+ ```
1904
+
1905
+ The callback you set will receive errors that occur within the stream containers you have created. If you do not set this callback, errors will instead be logged to the browser console.
1906
+
1907
+ Errors resulting from communication between the SDK & the Atomic platform, such as authentication & network errors, will be logged via the [debug logger](#debug-logging) at the level of verbosity you have chosen. These logs can be observed in the browser console and will be a string consisting of the error name and error description.
1908
+
1909
+ ### Setting the version of the client app
1910
+
1911
+ The SDK provides a method `AtomicSDK.setClientAppVersion` for setting the current version of your app. This app version is attached to generated analytics events to make it easy to track issues between app versions and to get insight into version usage.
1912
+
1913
+ Version strings have a maximum length of 128 characters, if you supply a longer string it will be trimmed to that length.
1914
+
1915
+ The following example sets the client app version to `Version 2.3.1`.
1916
+
1917
+ ```js
1918
+ AtomicSDK.setClientAppVersion('Version 2.3.1')
1919
+ ```
1920
+
1754
1921
  ## Third-party dependencies
1755
1922
 
1756
- The Atomic Web SDK (as at the current release `24.2.1`) uses the following third-party dependencies:
1923
+ The Atomic Web SDK (as at the current release `24.3.0`) uses the following third-party dependencies:
1757
1924
 
1758
1925
  - Font Awesome Free `5.13.1`
1759
1926
  - snarkdown `1.2.1`