@vtex/ads-stories 0.5.0 → 0.8.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 +33 -0
- package/README.md +29 -297
- package/dist/cdn/vtex-ads-stories.js +438 -113
- package/dist/cdn/vtex-ads-stories.js.map +1 -1
- package/dist/cjs/index.cjs +932 -189
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/cjs/index.d.cts +42 -196
- package/dist/cjs/react.cjs.map +1 -1
- package/dist/cjs/react.d.cts +13 -3
- package/dist/cjs/story-Ba9J0rbL.d.cts +276 -0
- package/dist/esm/index.d.ts +42 -196
- package/dist/esm/index.js +956 -212
- package/dist/esm/index.js.map +1 -1
- package/dist/esm/react.d.ts +13 -3
- package/dist/esm/story-Ba9J0rbL.d.ts +276 -0
- package/package.json +1 -1
- package/src/commerce-events.ts +93 -0
- package/src/components/card/card.ts +16 -3
- package/src/components/carousel/carousel-skeleton.ts +113 -0
- package/src/components/carousel/carousel.ts +53 -8
- package/src/components/carousel/index.ts +7 -0
- package/src/components/events/events-controller.ts +23 -13
- package/src/components/icons/assets/minus.svg +1 -0
- package/src/components/icons/assets/plus.svg +1 -0
- package/src/components/icons/assets/trash.svg +1 -0
- package/src/components/icons/assets/warning-circle-fill.svg +1 -0
- package/src/components/icons/index.ts +8 -0
- package/src/components/media/index.ts +7 -1
- package/src/components/media/media.styles.ts +113 -0
- package/src/components/media/media.ts +108 -11
- package/src/components/media/video-controller.ts +80 -6
- package/src/components/player/player.ts +42 -17
- package/src/components/product/cta.ts +3 -3
- package/src/components/product/index.ts +2 -0
- package/src/components/product/product.styles.ts +63 -6
- package/src/components/product/product.ts +130 -29
- package/src/index.ts +8 -0
- package/src/locales/en.ts +13 -3
- package/src/locales/es.ts +13 -3
- package/src/locales/index.ts +6 -0
- package/src/locales/pt.ts +13 -3
- package/src/locales/types.ts +22 -2
- package/src/react.ts +12 -2
- package/src/story/story.ts +218 -20
- package/src/utils/hydrate-products.ts +30 -6
- package/src/utils/media-ready.ts +58 -0
- package/src/utils/safe-url.ts +36 -0
- package/src/utils/send-event.ts +1 -1
- package/src/utils/http-url.ts +0 -12
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,38 @@
|
|
|
1
1
|
# @vtex/ads-stories
|
|
2
2
|
|
|
3
|
+
## 0.8.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 8184763: `label-unavailable` and `label-sold-out` replace the disabled button's text for a product that can't be bought and the sold out text shown with its price (and read by screen readers), as `label-add-to-cart` and `label-view-product` already do for their buttons. Missing or blank, each keeps the default in the element's language. They are also the `labelUnavailable` and `labelSoldOut` properties.
|
|
8
|
+
|
|
9
|
+
## 0.7.0
|
|
10
|
+
|
|
11
|
+
### Minor Changes
|
|
12
|
+
|
|
13
|
+
- a0cf1b9: Add to cart in the player dispatches `vtex-ads-story:add-to-cart` from the element, with `{ sku, seller, quantity }` (the product's `product_sku`, its `seller_id` when the ad API sends one, and `1`). The event bubbles and is composed, has no default action, and leaves the player open. A product without a SKU has no add to cart. `ADD_TO_CART_EVENT`, `StoryAddToCartDetail` and `StoryAddToCartEvent` are exported.
|
|
14
|
+
- a0cf1b9: Once a product is added from the player, a stepper takes add to cart's place: minus (a trash with one left), the quantity and plus. Plus dispatches `vtex-ads-story:add-to-cart`, and minus the new `vtex-ads-story:remove-from-cart`, with the same `{ sku, seller, quantity }` detail (`quantity` is how many to remove, always 1). The quantity counts what was added and removed, for each SKU and seller, since the player opened; it doesn't read the store's cart, and opening the player again starts it over. `REMOVE_FROM_CART_EVENT`, `StoryRemoveFromCartDetail` and `StoryRemoveFromCartEvent` are exported.
|
|
15
|
+
- 8b3f105: `--vtex-ads-story-radius` now also shapes the product and call to action pills, the covers beside the expanded video, the product panel's buttons (add to cart, its stepper, view product) and the video's **Tentar de novo**, not only the cards. The product image follows it 8px in, so its corners stay parallel to the pill's. Unset, each keeps its current corners. The round icon buttons on the video stay round.
|
|
16
|
+
|
|
17
|
+
From about `38px` up, the 60px product image becomes a circle. Use `0px`, not `0`, for square corners.
|
|
18
|
+
|
|
19
|
+
- cb5a966: A Story's `destination_url` can be a path on the store (`/product/p`) as well as an absolute http(s) URL, for both the product card and the call to action. Paths that would lead to another host (`//host`, `/\host`) are ignored.
|
|
20
|
+
- 80d967a: New `slide-duration` attribute, also in the React JSX types: with more than one Story, how long each one stays highlighted before the carousel moves to the next, in milliseconds (default `5000`). `0` turns the automatic advance off, so the highlight moves only with the arrows, swipes and clicks. Other values are limited to between `2000` and `120000`. A negative value or one that isn't a number uses the default. Changing it doesn't request the Stories again: the highlighted Story's time starts over with the new duration.
|
|
21
|
+
- cb5a966: A product that can't be bought keeps showing its price (fetched, or the ad server's from `product_metadata`) on the card and in the player; **Esgotado** only shows in its place when there is no price. Add to cart is still the disabled **Produto indisponível**. Screen readers hear that it's sold out either way: the product button's label ends with **Esgotado**, after the price when there is one.
|
|
22
|
+
- cb5a966: A video that can't load no longer leaves only its cover: the card shows a **Video unavailable** notice over it, and the player shows **Couldn't load the video** with a **Try again** button. Retrying shows a spinner with **Loading video** until the video loads, then plays it with the sound on, or shows the notice again if it fails. `StoryLabels` gets `videoUnavailable`, `videoFailed`, `videoLoading` and `retry`, in Portuguese, Spanish and English.
|
|
23
|
+
|
|
24
|
+
### Patch Changes
|
|
25
|
+
|
|
26
|
+
- cb5a966: A hydration strategy whose `price()` returns no amount, `NaN`, a string or a negative amount no longer shows "R$ NaN": the ad server's price shows instead. A `listPrice` that isn't an amount above the price is dropped.
|
|
27
|
+
- 80d967a: Opening a Story in the player now plays its video with the sound on, since the shopper chose to watch it. If the browser blocks playing with sound, the video plays muted and the sound button offers to turn it on.
|
|
28
|
+
- 80d967a: With `prefers-reduced-motion: reduce`, the carousel no longer moves the highlight on its own: it stays on the cards' covers and moves only with the arrows, swipes and clicks, whatever `slide-duration` says. The player still plays the video once the shopper opens it.
|
|
29
|
+
|
|
30
|
+
## 0.6.0
|
|
31
|
+
|
|
32
|
+
### Minor Changes
|
|
33
|
+
|
|
34
|
+
- 563672a: Show a skeleton of the carousel while the ad request is pending and then while the first Story's cover loads, and fade it out once the cards are ready, so the first card doesn't appear piece by piece. The cards show anyway 3 seconds after the Stories arrive, and a broken cover doesn't hold them. Without a required attribute, or when the request fails or the placement has no Story, the element still renders nothing. The Stories' views start counting only once the cards are visible.
|
|
35
|
+
|
|
3
36
|
## 0.5.0
|
|
4
37
|
|
|
5
38
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -5,7 +5,8 @@ including VTEX IO, FastStore and non-VTEX storefronts.
|
|
|
5
5
|
|
|
6
6
|
> Work in progress. Currently requests the placement's Stories from the ad
|
|
7
7
|
> API, shows them in a carousel, whose cards open in a player at the bottom
|
|
8
|
-
> right,
|
|
8
|
+
> right, sends their impression, view and click events, and tells the store
|
|
9
|
+
> when a product is added to or removed from the cart.
|
|
9
10
|
|
|
10
11
|
## npm
|
|
11
12
|
|
|
@@ -29,60 +30,18 @@ defineVtexAdsStoryCarousel();
|
|
|
29
30
|
></vtex-ads-story-carousel>
|
|
30
31
|
```
|
|
31
32
|
|
|
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.
|
|
44
|
-
|
|
45
|
-
### TypeScript and React
|
|
46
|
-
|
|
47
|
-
`document.createElement("vtex-ads-story-carousel")` and
|
|
48
|
-
`document.querySelector("vtex-ads-story-carousel")` are typed as
|
|
49
|
-
`VtexAdsStoryCarouselElement` out of the box.
|
|
50
|
-
|
|
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):
|
|
53
|
-
|
|
54
|
-
```tsx
|
|
55
|
-
// e.g. in your app's entry file or a .d.ts file
|
|
56
|
-
import type {} from "@vtex/ads-stories/react";
|
|
57
|
-
|
|
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
|
-
);
|
|
65
|
-
```
|
|
66
|
-
|
|
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'`.
|
|
74
|
-
The types are opt-in so projects without React don't need `@types/react`.
|
|
75
|
-
|
|
76
33
|
## CDN
|
|
77
34
|
|
|
78
35
|
The same build is available as a standalone script from
|
|
79
36
|
[unpkg](https://unpkg.com) and [jsDelivr](https://www.jsdelivr.com). It
|
|
80
37
|
registers `<vtex-ads-story-carousel>` when it loads, so no JavaScript is
|
|
81
|
-
needed in the page. Always pin an exact version:
|
|
38
|
+
needed in the page. Always pin an exact version: replace `<version>` below
|
|
39
|
+
with a version published on
|
|
40
|
+
[npm](https://www.npmjs.com/package/@vtex/ads-stories?activeTab=versions).
|
|
82
41
|
|
|
83
42
|
```html
|
|
84
43
|
<script
|
|
85
|
-
src="https://unpkg.com/@vtex/ads-stories
|
|
44
|
+
src="https://unpkg.com/@vtex/ads-stories@<version>"
|
|
86
45
|
integrity="sha384-<hash>"
|
|
87
46
|
crossorigin="anonymous"
|
|
88
47
|
></script>
|
|
@@ -94,253 +53,26 @@ needed in the page. Always pin an exact version: a pinned URL never changes.
|
|
|
94
53
|
></vtex-ads-story-carousel>
|
|
95
54
|
```
|
|
96
55
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
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
|
-
|
|
171
|
-
## Customization
|
|
172
|
-
|
|
173
|
-
```css
|
|
174
|
-
vtex-ads-story-carousel {
|
|
175
|
-
--vtex-ads-story-font-family: "Inter", sans-serif;
|
|
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;
|
|
181
|
-
--vtex-ads-story-radius: 20px;
|
|
182
|
-
}
|
|
183
|
-
```
|
|
184
|
-
|
|
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.
|
|
331
|
-
|
|
332
|
-
## Development
|
|
333
|
-
|
|
334
|
-
Run from the repository root:
|
|
335
|
-
|
|
336
|
-
```bash
|
|
337
|
-
pnpm stories:dev
|
|
338
|
-
```
|
|
339
|
-
|
|
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.
|
|
56
|
+
## Documentation
|
|
57
|
+
|
|
58
|
+
The full guide is on the
|
|
59
|
+
[VTEX Ads JS SDK documentation](https://vtex.github.io/ads-js/docs/ads-stories/quickstart):
|
|
60
|
+
|
|
61
|
+
- [Quickstart](https://vtex.github.io/ads-js/docs/ads-stories/quickstart):
|
|
62
|
+
npm and CDN (integrity hash, Content-Security-Policy), server-side
|
|
63
|
+
rendering, TypeScript and React.
|
|
64
|
+
- [Configuration](https://vtex.github.io/ads-js/docs/ads-stories/configuration):
|
|
65
|
+
attributes, language and labels, CSS variables.
|
|
66
|
+
- [Layout and player](https://vtex.github.io/ads-js/docs/ads-stories/layout-and-player):
|
|
67
|
+
the carousel, the product and its cart stepper, the call to action, the
|
|
68
|
+
player and video errors.
|
|
69
|
+
- [Product hydration](https://vtex.github.io/ads-js/docs/ads-stories/product-hydration):
|
|
70
|
+
where prices and availability come from, and custom strategies.
|
|
71
|
+
- [Events](https://vtex.github.io/ads-js/docs/ads-stories/events): the add
|
|
72
|
+
and remove from cart events for the store, and the ad events the element
|
|
73
|
+
sends.
|
|
74
|
+
|
|
75
|
+
## Contributing
|
|
76
|
+
|
|
77
|
+
To run the element locally or contribute a change, see
|
|
78
|
+
[CONTRIBUTING.md](https://github.com/vtex/ads-js/blob/main/CONTRIBUTING.md).
|