@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.
- package/CHANGELOG.md +67 -0
- package/README.md +260 -28
- package/dist/cdn/vtex-ads-stories.js +1073 -20
- package/dist/cdn/vtex-ads-stories.js.map +1 -1
- package/dist/cjs/index.cjs +4392 -315
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/cjs/index.d.cts +198 -12
- package/dist/cjs/react.cjs.map +1 -1
- package/dist/cjs/react.d.cts +46 -5
- package/dist/esm/index.d.ts +198 -12
- package/dist/esm/index.js +2819 -291
- package/dist/esm/index.js.map +1 -1
- package/dist/esm/react.d.ts +46 -5
- package/package.json +21 -4
- package/src/cdn.ts +7 -3
- package/src/components/card/card.ts +101 -111
- package/src/components/card/index.ts +1 -1
- package/src/components/carousel/carousel.ts +670 -0
- package/src/components/carousel/index.ts +15 -0
- package/src/components/events/events-controller.ts +212 -0
- package/src/components/events/index.ts +6 -0
- package/src/components/icons/assets/caret-left-bold.svg +1 -0
- package/src/components/icons/assets/caret-right-bold.svg +1 -0
- package/src/components/icons/assets/caret-up-bold.svg +1 -0
- package/src/components/icons/index.ts +30 -9
- package/src/components/media/index.ts +3 -0
- package/src/components/media/media.ts +70 -0
- package/src/components/media/video-controller.ts +125 -0
- package/src/components/player/index.ts +6 -2
- package/src/components/player/player.ts +946 -134
- package/src/components/product/cta.ts +56 -0
- package/src/components/product/index.ts +20 -0
- package/src/components/product/price.ts +86 -0
- package/src/components/product/product.styles.ts +369 -0
- package/src/components/product/product.ts +235 -0
- package/src/index.ts +9 -1
- package/src/locales/en.ts +29 -0
- package/src/locales/es.ts +30 -0
- package/src/locales/index.ts +36 -0
- package/src/locales/pt.ts +29 -0
- package/src/locales/types.ts +24 -0
- package/src/react.ts +49 -7
- package/src/story/index.ts +5 -1
- package/src/story/story.ts +528 -93
- package/src/tag-name.ts +1 -0
- package/src/types.ts +8 -12
- package/src/utils/fetch-story.ts +113 -0
- package/src/utils/http-url.ts +12 -0
- package/src/utils/hydrate-products.ts +88 -0
- package/src/utils/send-event.ts +71 -0
- 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
|
|
7
|
-
>
|
|
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 {
|
|
19
|
+
import { defineVtexAdsStoryCarousel } from "@vtex/ads-stories";
|
|
19
20
|
|
|
20
|
-
|
|
21
|
+
defineVtexAdsStoryCarousel();
|
|
21
22
|
```
|
|
22
23
|
|
|
23
24
|
```html
|
|
24
|
-
<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
|
|
28
|
-
`
|
|
29
|
-
|
|
30
|
-
|
|
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
|
|
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
|
|
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 = () =>
|
|
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
|
-
|
|
49
|
-
|
|
50
|
-
`
|
|
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
|
|
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
|
|
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
|
|
101
|
-
|
|
|
102
|
-
| `--vtex-ads-story-font-family`
|
|
103
|
-
| `--vtex-ads-story-color-text`
|
|
104
|
-
| `--vtex-ads-story-
|
|
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
|
|
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.
|