@sesamy/sesamy-components 2.28.0 → 2.30.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/README.md CHANGED
@@ -268,7 +268,7 @@ The container also emits the `viewArticle` and `content_unlocked` interactions t
268
268
 
269
269
  **When access cannot be resolved:**
270
270
 
271
- The container only removes the `content` slot on a definite denial. If the access check fails (no token, a network error) or does not answer within 10 seconds, the state is unknown and the `preview` slot is shown, with the article left in place. The container then checks again by itself after 1s, 3s and 10s, then every 30s, and straight away when the browser comes back online or the tab becomes visible again, until it gets an answer. A slow answer that arrives after its check timed out is still used. Once an article is shown, a later check that cannot be resolved does not hide it. `content_access_unresolved` and `content_access_recovered` report how often this happens.
271
+ The container only removes the `content` slot on a definite denial. If the access check fails (no token, a network error) or does not answer within 10 seconds, the state is unknown and the `preview` slot is shown, with the article left in place. The container then checks again by itself after 1s, 3s and 10s, then every 30s, and straight away when the browser comes back online or the tab becomes visible again, until it gets an answer. A slow answer that arrives after its check timed out is still used. Once an article is shown, a later check that cannot be resolved does not hide it. `content_access_unresolved` and `content_access_recovered` report how often this happens. With a sesamy-js that provides `sesamy.errors.report`, the same two moments are also sent to Sesamy's error reporting (category `component`, with the reason, attempts and elapsed time), alongside the auth and API failures sesamy-js reports itself.
272
272
 
273
273
  ```js
274
274
  const el = document.querySelector('sesamy-content-container');
@@ -295,7 +295,7 @@ el.addEventListener('sesamy:content-unlocked', (e) => {
295
295
 
296
296
  ### sesamy-paywall
297
297
 
298
- A web component that displays a paywall for content, loading paywall settings from a remote URL and supporting different templates (Article, Boxes, Login).
298
+ A web component that displays a paywall for content, loading paywall settings from a remote URL and supporting different templates (Article, Boxes, Login, Email).
299
299
 
300
300
  **Props/Attributes:**
301
301
 
@@ -304,6 +304,7 @@ A web component that displays a paywall for content, loading paywall settings fr
304
304
  - `price`: Price of the content
305
305
  - `currency`: Currency code for the price
306
306
  - `redirect-url`: URL to redirect after purchase
307
+ - `redirect-label`: Label for the button back to the redirect URL on the checkout confirmation page and in the order confirmation email
307
308
  - `utm-source`, `utm-medium`, `utm-campaign`, `utm-term`, `utm-content`: UTM parameters for tracking
308
309
  - `pass`: Pass ID for access
309
310
 
@@ -323,6 +324,63 @@ of sending a broken `redirect-url` to checkout. Single purchases have no
323
324
  per-option redirect, so they start at level 2; subscription options of type URL
324
325
  link straight out and never reach checkout at all.
325
326
 
327
+ **Redirect button label:**
328
+
329
+ The checkout confirmation page and the order confirmation email have a button
330
+ that takes the buyer back to the redirect URL. It reads "Go to {vendor}" unless
331
+ a label is set. The label resolves through the same levels as the redirect,
332
+ first non-blank value winning:
333
+
334
+ 1. `redirectLabel` on the chosen subscription option
335
+ 2. `settings.redirectLabel` on the paywall
336
+ 3. the `redirect-label` attribute on the element
337
+
338
+ It is plain text and not translated. Blank values fall through. With none set,
339
+ no label is sent and the checkout keeps its default. This needs an api2 that
340
+ accepts `redirectLabel` on `POST /checkouts`. Older api2 versions ignore it.
341
+
342
+ **Email template:**
343
+
344
+ With `settings.template` set to `EMAIL`, the paywall sells one offer and asks
345
+ only for an email address, then sends the reader to checkout with the address
346
+ filled in. Everything it shows comes from the paywall settings, so each
347
+ publisher configures their own copy and branding:
348
+
349
+ | Shown | Taken from |
350
+ | -------------------------- | ------------------------------------------------------------ |
351
+ | Logo | `logoUrl`, when `settings.useDefaultLogo` is on |
352
+ | Headline | `headline` |
353
+ | Text below the headline | `description` of the offer |
354
+ | Benefits list | `features` of the offer, else the paywall-wide `features` |
355
+ | Button text | `buttonText` of the offer, else the translated "Continue" |
356
+ | "Already subscribing?" row | shown to logged-out readers when `showLoginButton` is on |
357
+ | Colors and background | `mainColor` and `settings.styling`, like the other templates |
358
+
359
+ The offer is the subscription option marked `selected`, or the first one. With
360
+ no options the paywall renders nothing. The checkout is created with the
361
+ option's discount code, the same redirect and redirect label resolution as the
362
+ other templates, and `email` set to the address. A reader who is logged in but
363
+ has no access gets their account's address filled in. An option of type URL
364
+ links straight out, as in the other templates.
365
+
366
+ The address is part of the `payload` of the cancelable
367
+ `sesamyPaywallCreateCheckout` event. A listener that forwards that payload to an
368
+ analytics or tag manager is sending personal data, so pick the fields it sends.
369
+
370
+ It renders as a compact, centered card. On top of the shared paywall tokens
371
+ (`--sesamy-paywall-primary-color`, `--sesamy-paywall-bg-color`,
372
+ `--sesamy-paywall-border-radius`, `--sesamy-paywall-btn-bg-color`, …) it reads:
373
+
374
+ ```css
375
+ sesamy-paywall {
376
+ --sesamy-paywall-headline-font-family: Georgia, serif; /* default: --sesamy-font-family */
377
+ --sesamy-paywall-headline-font-weight: 500; /* default 700 */
378
+ --sesamy-paywall-max-width: 560px; /* default 490px at a 16px base size */
379
+ }
380
+ ```
381
+
382
+ The payment method logos are shown only when `footerPaymentMethods` is set.
383
+
326
384
  **Events:**
327
385
 
328
386
  Per-element events dispatched directly on the `<sesamy-paywall>` element (bubble, composed):
@@ -356,6 +414,7 @@ The paywall also emits the `addToCart` interaction through sesamy-js when the us
356
414
  - `features`: Content rendered in the features section of the paywall (e.g., feature list, benefits)
357
415
  - `login-button-text`: Replaces the text of the "already subscribing" login button
358
416
  - `logout-button-text`: Replaces the "Log out" text in the row a logged-in reader without access sees
417
+ - `below-button`: Content rendered below the continue button, for example terms or a privacy notice (`EMAIL` template only)
359
418
 
360
419
  **Basic Usage Example:**
361
420
 
@@ -378,13 +437,13 @@ The paywall also emits the `addToCart` interaction through sesamy-js when the us
378
437
 
379
438
  #### Slots
380
439
 
381
- The `sesamy-paywall` component provides five slots for customization:
440
+ The `sesamy-paywall` component provides six slots for customization:
382
441
 
383
442
  ##### headline
384
443
 
385
444
  - **Purpose:** Replaces the headline configured in the paywall settings.
386
445
  - **Behavior:** When you provide content in the `headline` slot, it is rendered in place of the stored headline, with the headline's own styling (size, weight, max width). When you leave it empty, the headline from the paywall settings is shown. Use this to vary the copy per placement (e.g., article vs. front page) while reusing one paywall configuration.
387
- - **Availability:** All templates (`ARTICLE`, `BOXES`, `LOGIN`).
446
+ - **Availability:** All templates (`ARTICLE`, `BOXES`, `LOGIN`, `EMAIL`).
388
447
  - **Example:**
389
448
  ```html
390
449
  <sesamy-paywall settings-url="https://api.example.com/paywall/settings">
@@ -395,7 +454,7 @@ The `sesamy-paywall` component provides five slots for customization:
395
454
  ##### below-headline
396
455
 
397
456
  - **Purpose:** Inserts custom content directly below the paywall headline.
398
- - **Behavior:** The content you provide in this slot will be rendered in addition to the default paywall content, immediately below the headline. Use this for adding extra information, banners, or custom elements.
457
+ - **Behavior:** The content you provide in this slot will be rendered in addition to the default paywall content, immediately below the headline. Use this for adding extra information, banners, or custom elements. In the `EMAIL` template the slot replaces the offer's description, which is rendered there by default.
399
458
  - **Example:**
400
459
  ```html
401
460
  <sesamy-paywall settings-url="https://api.example.com/paywall/login-settings">
@@ -407,7 +466,7 @@ The `sesamy-paywall` component provides five slots for customization:
407
466
 
408
467
  - **Purpose:** Replaces the default features section of the paywall.
409
468
  - **Behavior:** When you provide content in the `features` slot, it will completely replace the built-in features list or section. Use this slot to fully customize the list of benefits, features, or selling points shown to the user. Slotted content is static: it does not switch when the visitor selects a different subscription option the way the built-in list does.
410
- - **Availability:** Only the `ARTICLE` template renders a paywall-wide features list. The `BOXES` template shows features inside each box, so the slot has no effect there.
469
+ - **Availability:** The `ARTICLE` and `EMAIL` templates render a features list. The `BOXES` template shows features inside each box, so the slot has no effect there.
411
470
  - **Example:**
412
471
  ```html
413
472
  <sesamy-paywall settings-url="https://api.example.com/paywall/settings">
@@ -425,7 +484,7 @@ The `sesamy-paywall` component provides five slots for customization:
425
484
 
426
485
  - **Purpose:** Replaces the text of the "already subscribing" login button the paywall renders above the headline.
427
486
  - **Behavior:** The paywall embeds a nested `sesamy-login` component and forwards this slot into that component's own `button-text` slot. When you leave it empty, the default translated text (`Already subscribing? Login`) is used.
428
- - **Availability:** Only the `ARTICLE` template renders this login button. The `BOXES` template hides it, and the `LOGIN` template doesn't embed a `sesamy-login` at all, so the slot has no effect there.
487
+ - **Availability:** The `ARTICLE` and `EMAIL` templates render this login button (the `EMAIL` template below the form). The `BOXES` template hides it, and the `LOGIN` template doesn't embed a `sesamy-login` at all, so the slot has no effect there.
429
488
  - **Styling:** Inside the paywall this button is rendered borderless and underlined (4px offset), at the base font size (16px by default) rather than the 14px a standalone `sesamy-login` uses, and it fades to 80% opacity on hover. Set `--sesamy-login-button-text-size` on the paywall to override the size; the other `--sesamy-login-button-*` variables apply as usual.
430
489
  - **Example:**
431
490
  ```html
@@ -446,9 +505,21 @@ The `sesamy-paywall` component provides five slots for customization:
446
505
  </sesamy-paywall>
447
506
  ```
448
507
 
508
+ ##### below-button
509
+
510
+ - **Purpose:** Inserts custom content directly below the continue button.
511
+ - **Behavior:** Rendered in addition to the default content. Use it for terms, a privacy notice or other small print that belongs next to the button.
512
+ - **Availability:** Only the `EMAIL` template.
513
+ - **Example:**
514
+ ```html
515
+ <sesamy-paywall settings-url="https://api.example.com/paywall/email-settings">
516
+ <small slot="below-button">By continuing you accept our terms.</small>
517
+ </sesamy-paywall>
518
+ ```
519
+
449
520
  **Note:**
450
521
 
451
- - The `below-headline` slot adds to the paywall, while the `headline`, `features` and `login-button-text` slots replace the default content entirely. The `logout-button-text` slot replaces only the "Log out" label.
522
+ - The `below-headline` and `below-button` slots add to the paywall, while the `headline`, `features` and `login-button-text` slots replace the default content entirely. The `logout-button-text` slot replaces only the "Log out" label.
452
523
 
453
524
  ### sesamy-visibility
454
525