@vtex/ads-stories 0.4.0 → 0.5.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 (51) hide show
  1. package/CHANGELOG.md +67 -0
  2. package/README.md +260 -28
  3. package/dist/cdn/vtex-ads-stories.js +1073 -20
  4. package/dist/cdn/vtex-ads-stories.js.map +1 -1
  5. package/dist/cjs/index.cjs +4392 -315
  6. package/dist/cjs/index.cjs.map +1 -1
  7. package/dist/cjs/index.d.cts +198 -12
  8. package/dist/cjs/react.cjs.map +1 -1
  9. package/dist/cjs/react.d.cts +46 -5
  10. package/dist/esm/index.d.ts +198 -12
  11. package/dist/esm/index.js +2819 -291
  12. package/dist/esm/index.js.map +1 -1
  13. package/dist/esm/react.d.ts +46 -5
  14. package/package.json +21 -4
  15. package/src/cdn.ts +7 -3
  16. package/src/components/card/card.ts +101 -111
  17. package/src/components/card/index.ts +1 -1
  18. package/src/components/carousel/carousel.ts +670 -0
  19. package/src/components/carousel/index.ts +15 -0
  20. package/src/components/events/events-controller.ts +212 -0
  21. package/src/components/events/index.ts +6 -0
  22. package/src/components/icons/assets/caret-left-bold.svg +1 -0
  23. package/src/components/icons/assets/caret-right-bold.svg +1 -0
  24. package/src/components/icons/assets/caret-up-bold.svg +1 -0
  25. package/src/components/icons/index.ts +30 -9
  26. package/src/components/media/index.ts +3 -0
  27. package/src/components/media/media.ts +70 -0
  28. package/src/components/media/video-controller.ts +125 -0
  29. package/src/components/player/index.ts +6 -2
  30. package/src/components/player/player.ts +946 -134
  31. package/src/components/product/cta.ts +56 -0
  32. package/src/components/product/index.ts +20 -0
  33. package/src/components/product/price.ts +86 -0
  34. package/src/components/product/product.styles.ts +369 -0
  35. package/src/components/product/product.ts +235 -0
  36. package/src/index.ts +9 -1
  37. package/src/locales/en.ts +29 -0
  38. package/src/locales/es.ts +30 -0
  39. package/src/locales/index.ts +36 -0
  40. package/src/locales/pt.ts +29 -0
  41. package/src/locales/types.ts +24 -0
  42. package/src/react.ts +49 -7
  43. package/src/story/index.ts +5 -1
  44. package/src/story/story.ts +528 -93
  45. package/src/tag-name.ts +1 -0
  46. package/src/types.ts +8 -12
  47. package/src/utils/fetch-story.ts +113 -0
  48. package/src/utils/http-url.ts +12 -0
  49. package/src/utils/hydrate-products.ts +88 -0
  50. package/src/utils/send-event.ts +71 -0
  51. package/src/utils/with-timeout.ts +43 -0
package/CHANGELOG.md CHANGED
@@ -1,5 +1,72 @@
1
1
  # @vtex/ads-stories
2
2
 
3
+ ## 0.5.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 6495795: Add the `timeout` attribute: the time limit for the ad request, in milliseconds (default `2000`). Without a Story by then, the element renders nothing. The element also cancels its pending request when an attribute changes or it leaves the page, and requests again if moved while the request was pending.
8
+ - 2952cb3: Send each Story's impression, view and click to the event URLs from the ad response, at most once per Story and session. The impression goes out when the carousel renders the Stories; the view when a card, or the open player's video, stays at least 50% on screen for 2 continuous seconds; the click on the first touch on a card, or on the product or call to action in the player. Events are posted as JSON (`session_id`, `user_id`) with `navigator.sendBeacon`, falling back to a `keepalive` fetch.
9
+ - 6495795: Request the Story from the ad API with `@vtex/ads-core` instead of rendering a fixed test Story. The element takes the `publisher-id`, `session-id` and `placement` attributes (required) and `user-id`, `account-name` and `channel` (optional), and renders nothing while loading, without a required attribute, on error or when the placement has no Story.
10
+
11
+ A failed request (other than one cancelled or past its time limit) is logged with `console.error`, so a failing request can be told apart from a placement with no Story.
12
+
13
+ The React JSX types (`@vtex/ads-stories/react`) now include these attributes, with `publisher-id`, `session-id` and `placement` required.
14
+
15
+ - e36dc60: Stories whose destination is a link (no product) show a call to action at the bottom of the card and the video: a glass pill with the text set in the campaign (the ad's `call_to_action`) and a caret, which opens the link in a new tab. On a card without the highlight, it moves the highlight, as the card does. A Story without the text shows no button.
16
+ - 17603aa: The element is now `<vtex-ads-story-carousel>` instead of `<vtex-ads-story>`, also in the React JSX types and in `document.createElement` and `querySelector` types. `<vtex-ads-story>` is no longer registered: replace the tag in the page, and in any CSS selector that targets it. The CSS variables keep their `--vtex-ads-story-` names, and the console messages now start with `[vtex-ads-story-carousel]`.
17
+
18
+ The exports follow the new name: `VtexAdsStoryElement` is now `VtexAdsStoryCarouselElement`, `defineVtexAdsStories()` is now `defineVtexAdsStoryCarousel()`, and the React types `VtexAdsStoryProps` and `VtexAdsStoryAttributes` are now `VtexAdsStoryCarouselProps` and `VtexAdsStoryCarouselAttributes`. The CDN script's global stays `window.VtexAdsStories`, with the renamed members.
19
+
20
+ - fc54bdd: Show the placement's Stories in a carousel, in a 500px tall band as wide as the element's parent. The layout depends on how many Stories come back:
21
+ - **One**: the card is centered over a background, with 24px around it (the card shrinks to 452px tall) and a soft shadow. On screens 576px wide or less, the card shows alone at its full 500px height, without the background.
22
+ - **Two**: both cards side by side. The highlighted card is full size and the other smaller and dimmed.
23
+ - **Three or more**: the highlighted card in the middle and the others on each side, smaller and dimmed, up to two per side. Every card moves one place per step. With four, the Story opposite the highlighted one shows at both ends. On screens 576px wide or less, two Stories also show this way, with the other one on both sides.
24
+
25
+ With more than one Story, the highlight moves to the next card every 5 seconds, except while the pointer is over the carousel, the keyboard focus is in it, or the player is open. It also moves with the previous and next arrows, a swipe, or a click on a dimmed card. Clicking the highlighted card opens it in the player. If the highlighted card's sound is on, the next highlighted card plays with sound too (muted instead, if the browser blocks it). With more than one Story, the mini player has previous and next buttons above its top left: they change the video in the player, and the carousel highlight follows. With the focus in the player, the left and right arrow keys do the same (not with a modifier key held); elsewhere on the page they keep working as usual. The expanded player shows the other Stories' covers beside the video, up to two per side (clicking one plays it), with previous and next beside it, and moves on to the next Story when the video ends instead of looping. With two Stories, the video moves off center with the other cover beside it. Each step animates: the video grows from the cover of the Story it now shows and the covers slide to their new places (not with reduced motion). On screens 576px wide or less, it fills the screen without the covers, with previous and next inside the video's edges.
26
+
27
+ New attributes, also in the React JSX types:
28
+ - `quantity`: how many Stories to request, the carousel positions (default `8`). A value below `1` or not a number uses the default. Changing it requests the Stories again.
29
+ - `inactive-autoplay` (off by default): off, only the highlighted card plays its video and the others show their cover. On, the visible cards without the highlight also play, muted.
30
+
31
+ New CSS variable: `--vtex-ads-story-color-surface` sets the background behind a single Story (default `#fafafa`). `--vtex-ads-story-radius` now rounds that background's corners as well as the card's.
32
+
33
+ - 17603aa: The element's texts follow its language: the buttons, "Esgotado" and the names screen readers read out come in Portuguese, Spanish and English, picked from the closest `lang` attribute like the prices (`es-AR` gets Spanish). Without a `lang`, or with another language, they stay in Portuguese.
34
+
35
+ New attributes, also in the React JSX types: `label-add-to-cart` and `label-view-product` replace the product panel's button texts in any language. Missing or blank, the language's default shows. Changing them doesn't request the Stories again.
36
+
37
+ - b4350e7: The hydration strategy takes an optional `available(product, offer)`, and the Intelligent Search one reads `AvailableQuantity`. A product that can't be bought shows **Esgotado** in place of the price, on the card and in the player, and add to cart becomes a disabled **Produto indisponível**; **Ver produto** still works and the Story keeps playing. `StoryProductDetails` gets `available`.
38
+ - bff14ea: Show the Story's product on its card: a pill at the bottom with the product image, its name (up to two lines) and its price, with the "from" price struck through when on sale. Clicking it does the same as clicking the card. The ad API doesn't send prices yet, so the card reads them from the product's `product_metadata` (`price`, and `promotional_price` when on sale) and shows only the name without them. Stories without a product (a link destination) show no pill.
39
+
40
+ The mini and expanded player show the same pill at the bottom of the video, a bit larger (72px image, 56px in the mini player on screens 576px wide or less). Clicking it opens a panel below it, as in the prototype: the pill turns white and shows an add to cart button and a view product link, which opens the product page in a new tab. Adding to the cart does nothing yet. Clicking the product on the highlighted card opens the player with the panel already open. Clicking the video closes the panel without pausing, and moving to another Story or opening the player again starts with it closed. On devices with a mouse, the closed pill lifts and darkens on hover, on the card and in the player.
41
+
42
+ Prices are formatted in the language of the closest element with a `lang` attribute, the element itself included, so a store can set one for the widget alone (`<vtex-ads-story-carousel lang="es-AR">`). Without a `lang`, or with one the browser doesn't know, they use `pt-BR`.
43
+
44
+ New attribute, also in the React JSX types: `currency`, the currency of the prices as an ISO 4217 code (`BRL`). Default `BRL`, also for a code the browser doesn't know.
45
+
46
+ New CSS variables for the open product panel: `--vtex-ads-story-color-accent` colors its buttons (default `#1b75a8`) and `--vtex-ads-story-color-accent-contrast` the text on the add to cart button (default `#fff`); `--vtex-ads-story-color-surface` is its background and the view product button's (default `#fff`); `--vtex-ads-story-color-muted` is the "from" price and the disabled add to cart (default `#6b6b6b`); `--vtex-ads-story-color-text` now also colors its text (default `#242424` there).
47
+
48
+ - 3261876: The element hydrates its products once the carousel shows, in one request, and shows their fetched prices, with a hydration strategy: the new `hydration` property (`{ fetcher, matcher, price }`), or Intelligent Search by default when `account-name` is set. `hydration="none"` turns it off, and `hydration-timeout` sets its time limit (default 5000 ms). While it runs, the price and add to cart show placeholders; the fetched price then replaces the ad server's. Without one (no strategy, failure, time limit, product not found or without a price), the ad server's price shows, as before. New types `StoryHydration` and `StoryProductDetails`.
49
+
50
+ ### Patch Changes
51
+
52
+ - Updated dependencies [6495795]
53
+ - Updated dependencies [6495795]
54
+ - Updated dependencies [3261876]
55
+ - Updated dependencies [3261876]
56
+ - Updated dependencies [b4350e7]
57
+ - Updated dependencies [3261876]
58
+ - Updated dependencies [3261876]
59
+ - Updated dependencies [6495795]
60
+ - Updated dependencies [e36dc60]
61
+ - @vtex/ads-core@0.6.0
62
+
63
+ ## 0.4.1
64
+
65
+ ### Patch Changes
66
+
67
+ - 47bdafb: `<vtex-ads-story>` is now built with Lit. It looks and behaves the same in the browser; `lit` is a new dependency of the npm package (bundled in the CJS build and in the CDN script). In Node (SSR), importing the package now installs Lit's DOM shim, so `globalThis.customElements` is defined there.
68
+ - 46b3798: The card's sound on/off button now only shows while the card's video plays. It no longer shows when the video doesn't play: for people who prefer reduced motion, when the browser blocks autoplay (as iOS Low Power Mode does), and while the player is open.
69
+
3
70
  ## 0.4.0
4
71
 
5
72
  ### Minor Changes
package/README.md CHANGED
@@ -3,8 +3,9 @@
3
3
  VTEX Ads Stories web component. Framework-agnostic: works on any HTML5 page,
4
4
  including VTEX IO, FastStore and non-VTEX storefronts.
5
5
 
6
- > Work in progress. Currently renders one fixed test Story, which opens in a
7
- > player at the bottom right. The carousel, fed by the ad API, comes next.
6
+ > Work in progress. Currently requests the placement's Stories from the ad
7
+ > API, shows them in a carousel, whose cards open in a player at the bottom
8
+ > right, and sends their impression, view and click events.
8
9
 
9
10
  ## npm
10
11
 
@@ -15,47 +16,69 @@ npm install @vtex/ads-stories
15
16
  Register the element once, on the client:
16
17
 
17
18
  ```javascript
18
- import { defineVtexAdsStories } from "@vtex/ads-stories";
19
+ import { defineVtexAdsStoryCarousel } from "@vtex/ads-stories";
19
20
 
20
- defineVtexAdsStories();
21
+ defineVtexAdsStoryCarousel();
21
22
  ```
22
23
 
23
24
  ```html
24
- <vtex-ads-story></vtex-ads-story>
25
+ <vtex-ads-story-carousel
26
+ publisher-id="your-publisher-id"
27
+ session-id="the-store-session-id"
28
+ placement="home_stories"
29
+ ></vtex-ads-story-carousel>
25
30
  ```
26
31
 
27
- Importing the package has no side effects: nothing is registered until
28
- `defineVtexAdsStories()` is called. It can be imported during server-side
29
- rendering, where `defineVtexAdsStories()` does nothing. Both ESM (`import`) and
30
- CommonJS (`require`) builds are published, with type declarations.
32
+ Importing the package registers nothing: the element is only registered when
33
+ `defineVtexAdsStoryCarousel()` is called. Both ESM (`import`) and CommonJS
34
+ (`require`) builds are published, with type declarations.
35
+
36
+ The package can be imported during server-side rendering (for example in
37
+ FastStore, which is Next.js). The element is built with
38
+ [Lit](https://lit.dev), and in Node Lit installs a minimal DOM shim, so after
39
+ the import `globalThis.customElements` is defined on the server too. Don't use
40
+ `typeof customElements` to tell the server from the browser; use
41
+ `typeof window` instead. Calling `defineVtexAdsStoryCarousel()` on the server is
42
+ safe: it registers the element in Lit's server-side registry and renders
43
+ nothing.
31
44
 
32
45
  ### TypeScript and React
33
46
 
34
- `document.createElement("vtex-ads-story")` and
35
- `document.querySelector("vtex-ads-story")` are typed as `VtexAdsStoryElement`
36
- out of the box.
47
+ `document.createElement("vtex-ads-story-carousel")` and
48
+ `document.querySelector("vtex-ads-story-carousel")` are typed as
49
+ `VtexAdsStoryCarouselElement` out of the box.
37
50
 
38
- To use `<vtex-ads-story>` in `.tsx` files, enable its JSX types once in your
39
- project (requires `@types/react` 18.2.6 or newer, including 19):
51
+ To use `<vtex-ads-story-carousel>` in `.tsx` files, enable its JSX types once
52
+ in your project (requires `@types/react` 18.2.6 or newer, including 19):
40
53
 
41
54
  ```tsx
42
55
  // e.g. in your app's entry file or a .d.ts file
43
56
  import type {} from "@vtex/ads-stories/react";
44
57
 
45
- export const Ad = () => <vtex-ads-story />;
58
+ export const Ad = () => (
59
+ <vtex-ads-story-carousel
60
+ publisher-id="your-publisher-id"
61
+ session-id="the-store-session-id"
62
+ placement="home_stories"
63
+ />
64
+ );
46
65
  ```
47
66
 
48
- Or add `"@vtex/ads-stories/react"` to `compilerOptions.types` in `tsconfig.json`.
49
- Without it, TypeScript reports
50
- `Property 'vtex-ads-story' does not exist on type 'JSX.IntrinsicElements'`.
67
+ The JSX types include the element's attributes: `publisher-id`, `session-id`
68
+ and `placement` are required, as in HTML, and `channel` only accepts `site` or
69
+ `app`.
70
+
71
+ Or add `"@vtex/ads-stories/react"` to `compilerOptions.types` in
72
+ `tsconfig.json`. Without it, TypeScript reports
73
+ `Property 'vtex-ads-story-carousel' does not exist on type 'JSX.IntrinsicElements'`.
51
74
  The types are opt-in so projects without React don't need `@types/react`.
52
75
 
53
76
  ## CDN
54
77
 
55
78
  The same build is available as a standalone script from
56
79
  [unpkg](https://unpkg.com) and [jsDelivr](https://www.jsdelivr.com). It
57
- registers `<vtex-ads-story>` when it loads, so no JavaScript is needed in the
58
- page. Always pin an exact version: a pinned URL never changes.
80
+ registers `<vtex-ads-story-carousel>` when it loads, so no JavaScript is
81
+ needed in the page. Always pin an exact version: a pinned URL never changes.
59
82
 
60
83
  ```html
61
84
  <script
@@ -64,7 +87,11 @@ page. Always pin an exact version: a pinned URL never changes.
64
87
  crossorigin="anonymous"
65
88
  ></script>
66
89
 
67
- <vtex-ads-story></vtex-ads-story>
90
+ <vtex-ads-story-carousel
91
+ publisher-id="your-publisher-id"
92
+ session-id="the-store-session-id"
93
+ placement="home_stories"
94
+ ></vtex-ads-story-carousel>
68
95
  ```
69
96
 
70
97
  - The full file URL works too:
@@ -87,21 +114,220 @@ page. Always pin an exact version: a pinned URL never changes.
87
114
  - The script also exposes `window.VtexAdsStories` with the same API as the npm
88
115
  package.
89
116
 
117
+ ## Attributes
118
+
119
+ The element requests the placement's Stories from the VTEX Ads ad API with
120
+ [`@vtex/ads-core`](../core) and shows them in a carousel (see
121
+ [Layout](#layout)).
122
+
123
+ | Attribute | Required | Description |
124
+ | -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
125
+ | `publisher-id` | Yes | The publisher the ads are requested for |
126
+ | `session-id` | Yes | The store's session id. Use the same one sent with the store's other ad events |
127
+ | `placement` | Yes | The Story placement configured for the publisher |
128
+ | `user-id` | No | The shopper's id, when known |
129
+ | `account-name` | No | The VTEX account name. Also turns on the product hydration from Intelligent Search (see [Product hydration](#product-hydration)) |
130
+ | `channel` | No | `site` or `app`. Other values are not sent |
131
+ | `timeout` | No | Time limit for the ad request, in milliseconds. Default `2000` |
132
+ | `quantity` | No | How many Stories to request: the carousel positions. Default `8`. Below `1` or not a number: the default |
133
+ | `currency` | No | Currency of the product prices, as an ISO 4217 code (`BRL`, `ARS`). Default `BRL`. An invalid code uses the default |
134
+ | `label-add-to-cart` | No | The add to cart button's text. Missing or blank: the default in the element's language (see [Language](#language)) |
135
+ | `label-view-product` | No | The view product button's text. Missing or blank: the default in the element's language |
136
+ | `inactive-autoplay` | No | With more than one Story, the visible cards without the highlight also play their video, muted. On when present without a value or `"true"`; off by default, they show only their cover |
137
+ | `hydration` | No | `none`: no product request. Any other value is ignored. To set a strategy, use the `hydration` property (see [Product hydration](#product-hydration)) |
138
+ | `hydration-timeout` | No | Time limit for the product request, in milliseconds. Default `5000` |
139
+
140
+ The element renders nothing while the request is pending, when a required
141
+ attribute is missing, when the request fails or takes longer than `timeout`,
142
+ or when the placement has no Story. Changing any of these attributes, except
143
+ `timeout`, `hydration-timeout`, `inactive-autoplay`, `currency`,
144
+ `label-add-to-cart` and `label-view-product`, requests the Stories again; a
145
+ new time limit applies to the next request.
146
+
147
+ ## Language
148
+
149
+ The element's texts (buttons, "Esgotado", and the names screen readers read
150
+ out) and its prices follow the language of the closest element with a `lang`
151
+ attribute, the element itself included: usually `<html lang>`, or
152
+ `<vtex-ads-story-carousel lang="es-AR">` for the widget alone. The texts come in
153
+ Portuguese, Spanish and English, picked by the language alone (`es-AR` and
154
+ `es-MX` both get Spanish). Without a `lang`, or with another language, they
155
+ are in Portuguese and prices use `pt-BR`.
156
+
157
+ `label-add-to-cart` and `label-view-product` replace those two buttons'
158
+ texts in any language:
159
+
160
+ ```html
161
+ <vtex-ads-story-carousel
162
+ lang="es-AR"
163
+ label-add-to-cart="Comprar"
164
+ label-view-product="Ver detalles"
165
+ ...
166
+ ></vtex-ads-story-carousel>
167
+ ```
168
+
169
+ The call to action's text comes from the campaign.
170
+
90
171
  ## Customization
91
172
 
92
173
  ```css
93
- vtex-ads-story {
174
+ vtex-ads-story-carousel {
94
175
  --vtex-ads-story-font-family: "Inter", sans-serif;
95
176
  --vtex-ads-story-color-text: #1f1f1f;
177
+ --vtex-ads-story-color-muted: #6b6b6b;
178
+ --vtex-ads-story-color-surface: #fff;
179
+ --vtex-ads-story-color-accent: #1b75a8;
180
+ --vtex-ads-story-color-accent-contrast: #fff;
96
181
  --vtex-ads-story-radius: 20px;
97
182
  }
98
183
  ```
99
184
 
100
- | Variable | Default | Used for |
101
- | ------------------------------ | --------- | ------------ |
102
- | `--vtex-ads-story-font-family` | inherited | All text |
103
- | `--vtex-ads-story-color-text` | inherited | All text |
104
- | `--vtex-ads-story-radius` | `20px` | Card corners |
185
+ | Variable | Default | Used for |
186
+ | ---------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------- |
187
+ | `--vtex-ads-story-font-family` | inherited | All text |
188
+ | `--vtex-ads-story-color-text` | inherited (`#242424` in the panel) | All text off the video, such as the open product panel's |
189
+ | `--vtex-ads-story-color-muted` | `#6b6b6b` | The panel's "from" price and its disabled add to cart |
190
+ | `--vtex-ads-story-color-surface` | `#fff` (`#fafafa` behind the card) | The open product panel, the view product button, and the background behind a single Story |
191
+ | `--vtex-ads-story-color-accent` | `#1b75a8` | The product panel's buttons |
192
+ | `--vtex-ads-story-color-accent-contrast` | `#fff` | Text on the add to cart button |
193
+ | `--vtex-ads-story-radius` | `20px` | Card and background corners |
194
+
195
+ Text over the video stays white: it sits on the video, not on a store color.
196
+
197
+ ## Layout
198
+
199
+ The element requests up to `quantity` Stories and lays them out in a 500px tall
200
+ band as wide as its parent:
201
+
202
+ - **One Story**: the card is centered over a background. On screens 576px wide
203
+ or less, the card shows alone, without the background.
204
+ - **Two Stories**: both cards side by side. One has the highlight (full size);
205
+ the other is smaller and dimmed.
206
+ - **Three or more**: the highlighted card in the middle, the others on each
207
+ side, smaller and dimmed, up to two per side. Every card moves one place per
208
+ step. With four, the Story opposite the highlighted one shows at both ends.
209
+ Two Stories also show this way on screens 576px wide or less, with the other
210
+ one on both sides.
211
+
212
+ With more than one Story, the highlight moves to the next card every 5 seconds,
213
+ except while the pointer is over the carousel, the keyboard focus is in it, or
214
+ the player is open. It also moves with the arrows, a swipe, or a click on a
215
+ dimmed card. If the highlighted card's sound is on, the next highlighted card
216
+ plays with sound too, or muted if the browser blocks it.
217
+
218
+ ### Product
219
+
220
+ When the Story's destination is a product, the card shows it at the bottom: its
221
+ image, its name (up to two lines) and its price. On sale, the "from" price
222
+ shows struck through beside it.
223
+
224
+ In the player, the same product sits at the bottom of the video. Clicking it
225
+ opens a panel with an add to cart button and a view product link (the product
226
+ page, in a new tab). Clicking the product on the highlighted card opens the
227
+ player with the panel already open; on another card, it moves the highlight, as
228
+ the card does. Clicking the video or moving to another Story closes the panel.
229
+ Adding to the cart does nothing yet.
230
+
231
+ Prices are formatted in the element's language (see [Language](#language))
232
+ and in `currency`.
233
+
234
+ #### Product hydration
235
+
236
+ The ad API sends only part of a product's details: no price yet. Once the
237
+ carousel shows, the element fetches its products in one request, with a
238
+ hydration strategy from [`@vtex/ads-core`](../core), and shows the details it
239
+ reads from them over the ad API's. For now, the price is the only one.
240
+
241
+ - **`hydration` property**: a strategy `{ fetcher, matcher, price, available? }`, as an
242
+ object. `fetcher` and `matcher` are a `ProductFetcher` and a
243
+ `ProductMatchesOffer`; `price` reads an offer's price from a fetched product
244
+ (a `ProductPriceReader`). Set it before the element is on the page, or the
245
+ Stories are requested again.
246
+ - **`hydration="none"`**: no product request.
247
+ - **Neither, with `account-name`**: Intelligent Search, from
248
+ `{account-name}.vtexcommercestable.com.br`.
249
+ - **Neither, without `account-name`**: no product request.
250
+
251
+ ```js
252
+ const story = document.querySelector("vtex-ads-story-carousel");
253
+ story.hydration = {
254
+ fetcher: async (offers, identity, { signal }) =>
255
+ fetchMyProducts(offers, signal),
256
+ matcher: (product, offer) => product.sku === offer.skuId,
257
+ price: (product) => ({ price: product.price, listPrice: product.listPrice }),
258
+ };
259
+ ```
260
+
261
+ While the request runs, the price and the panel's add to cart button show
262
+ placeholders. Then the fetched price shows, as the strategy returns it,
263
+ and so does add to cart. Without one (no strategy, a request that fails or
264
+ takes longer than `hydration-timeout`, a product not found or without a
265
+ price), the card shows the price from the product's `product_metadata`
266
+ (`price`, and `promotional_price` when on sale), or only the name without
267
+ one.
268
+
269
+ A strategy can also say whether the product can be bought, with an optional
270
+ `available(product, offer)` (a `ProductAvailabilityReader`; Intelligent
271
+ Search's reads `AvailableQuantity`). When it says no, the card and the player
272
+ show **Esgotado** in place of the price, add to cart becomes a disabled
273
+ **Produto indisponível**, and **Ver produto** still opens the product page.
274
+ The Story keeps playing. Without `available`, or when it doesn't say, the
275
+ product shows as before.
276
+
277
+ Intelligent Search's check follows the stock it reports: a SKU with an
278
+ `AvailableQuantity` of 0 or less is sold out. A retailer that allows backorder
279
+ or doesn't track stock may therefore see products as **Esgotado** that it still
280
+ sells. Pass an `available` of your own in the strategy to change that.
281
+
282
+ ### Call to action
283
+
284
+ When the Story's destination is a link (no product), the card and the player
285
+ show a call to action at the bottom instead: a button with the text set in the
286
+ campaign (the ad's `call_to_action`, such as "Saiba mais") and a caret, which
287
+ opens the link in a new tab. On a card without the highlight, it moves the
288
+ highlight, as the card does. Without a text, there is no button.
289
+
290
+ ### Player
291
+
292
+ Clicking the highlighted card opens it in the mini player, at the bottom right
293
+ of the screen, which can be expanded. With more than one Story:
294
+
295
+ - **Mini player**: previous and next buttons above its top left change the video
296
+ in the player, and the carousel highlight follows. The carousel's own advance
297
+ stays stopped while the player is open.
298
+ - **Expanded player**: the other Stories' covers sit beside the video, up to two
299
+ per side (click one to watch it), with previous and next beside it. When the
300
+ video ends, the next Story plays. With two Stories, the video moves off center
301
+ with the other cover beside it, without previous and next. On screens 576px
302
+ wide or less, it fills the screen, without the covers, and previous and next
303
+ sit inside the video's edges.
304
+ - **Keyboard**: with the focus in the player, the left and right arrow keys step
305
+ too (not with a modifier key held). Elsewhere on the page they keep working as
306
+ usual.
307
+
308
+ ## Ad events
309
+
310
+ The element sends each Story's impression, view and click to the URLs the ad
311
+ API returned for it (`impression_url`, `view_url`, `click_url`), each at most
312
+ once per Story and `session-id`:
313
+
314
+ - **Impression**: when the carousel renders the Stories.
315
+ - **View**: when a card's video, or the open player's, plays for 2 continuous
316
+ seconds while at least 50% of it is on screen, with the page visible. A card
317
+ showing only its cover, or a paused video, doesn't count, and cards behind
318
+ the expanded player don't either. Browsers without `IntersectionObserver`
319
+ send no view.
320
+ - **Click**: on the first touch on a card (its product, call to action and
321
+ sound button included), or on the player's video (its play and sound
322
+ buttons, product and call to action included). Previous, next and the
323
+ player's window buttons don't count.
324
+
325
+ Each event is a `POST` with a JSON body holding `session_id` and, when set,
326
+ `user_id`, sent with `navigator.sendBeacon` (a `fetch` with `keepalive` when
327
+ the browser can't queue the beacon), so it isn't lost when the shopper leaves
328
+ the page. A failed `fetch` is logged to the console and not sent again. The ad
329
+ API also deduplicates the events by session. A store that changes the element
330
+ takes over keeping these rules.
105
331
 
106
332
  ## Development
107
333
 
@@ -111,4 +337,10 @@ Run from the repository root:
111
337
  pnpm stories:dev
112
338
  ```
113
339
 
114
- This starts a dev server with `index.html`, reloading on save.
340
+ This starts Storybook on port 6006, with a story for each scenario (one or
341
+ more Stories, theming, slow or empty ad server, product hydration), reloading
342
+ on save. The ad server and Intelligent Search are mocked with MSW, in
343
+ `stories/handlers.ts`.
344
+
345
+ To run the same stories against the built standalone script, the file the CDN
346
+ serves, run `pnpm preview:cdn` in this package.