From 5f7cb1890df26ca30aa07d5e8fa6475315d77d1a Mon Sep 17 00:00:00 2001 From: rockwellll Date: Sat, 5 Sep 2026 23:45:25 -0300 Subject: [PATCH] Add Push setup and troubleshooting guides --- _config.yml | 3 + _developers/setup-push-with-hellotext-js.md | 20 ++ .../setup-push-with-hellotext-js.md | 224 ++++++++++++++++++ _i18n/en/integrations/connect-shopify.md | 6 + _i18n/en/integrations/connect-vtex.md | 6 + _i18n/en/integrations/setup-overview.md | 2 + .../integrations/setup-push-notifications.md | 70 ++++++ _i18n/en/numbers/messaging-overview.md | 2 + .../troubleshoot-push-notifications.md | 97 ++++++++ .../troubleshooting-overview.md | 2 + .../setup-push-with-hellotext-js.md | 224 ++++++++++++++++++ _i18n/es/integrations/connect-shopify.md | 6 + _i18n/es/integrations/connect-vtex.md | 6 + _i18n/es/integrations/setup-overview.md | 2 + .../integrations/setup-push-notifications.md | 70 ++++++ _i18n/es/numbers/messaging-overview.md | 2 + .../troubleshoot-push-notifications.md | 97 ++++++++ .../troubleshooting-overview.md | 2 + _integrations/setup-push-notifications.md | 20 ++ .../troubleshoot-push-notifications.md | 19 ++ 20 files changed, 880 insertions(+) create mode 100644 _developers/setup-push-with-hellotext-js.md create mode 100644 _i18n/en/developers/setup-push-with-hellotext-js.md create mode 100644 _i18n/en/integrations/setup-push-notifications.md create mode 100644 _i18n/en/troubleshooting-deliverability/troubleshoot-push-notifications.md create mode 100644 _i18n/es/developers/setup-push-with-hellotext-js.md create mode 100644 _i18n/es/integrations/setup-push-notifications.md create mode 100644 _i18n/es/troubleshooting-deliverability/troubleshoot-push-notifications.md create mode 100644 _integrations/setup-push-notifications.md create mode 100644 _troubleshooting-deliverability/troubleshoot-push-notifications.md diff --git a/_config.yml b/_config.yml index dfda5965..ac9b97fc 100644 --- a/_config.yml +++ b/_config.yml @@ -213,6 +213,7 @@ collections: - product-catalog-sync.md - connect-whatsapp.md - connect-catalog-to-whatsapp.md + - setup-push-notifications.md - transferring-ownership.md developers: output: true @@ -229,6 +230,7 @@ collections: - send-sms-with-api.md - tracking-events.md - custom-actions.md + - setup-push-with-hellotext-js.md - objects.md - tracking-on-campaigns-and-journeys.md - tracking-unidentified-customers.md @@ -239,6 +241,7 @@ collections: - troubleshooting-checklist.md - why-a-message-did-not-send.md - troubleshoot-whatsapp-templates.md + - troubleshoot-push-notifications.md - troubleshoot-a-capture.md - troubleshoot-missing-signals-or-activity.md - troubleshoot-pages-that-do-not-load.md diff --git a/_developers/setup-push-with-hellotext-js.md b/_developers/setup-push-with-hellotext-js.md new file mode 100644 index 00000000..c145b369 --- /dev/null +++ b/_developers/setup-push-with-hellotext-js.md @@ -0,0 +1,20 @@ +--- +navigation_group: extensibility +languages: ["en", "es"] + +en: + title: Set up Push with Hellotext.js + description: Publish a notification service worker and add Subscribe and Unsubscribe buttons to a custom storefront. +es: + title: Configura Push con Hellotext.js + description: Publica un service worker de notificaciones y agrega botones de suscripción y cancelación a una tienda personalizada. + +permalink: setup-push-with-hellotext-js +permalink_es: configurar-push-con-hellotext-js + +layout: guide +topic: developers +popular: false +--- + +{% translate_file developers/setup-push-with-hellotext-js.md %} diff --git a/_i18n/en/developers/setup-push-with-hellotext-js.md b/_i18n/en/developers/setup-push-with-hellotext-js.md new file mode 100644 index 00000000..0a8c8436 --- /dev/null +++ b/_i18n/en/developers/setup-push-with-hellotext-js.md @@ -0,0 +1,224 @@ +Use this guide to add Push subscription controls to your storefront with Hellotext.js. The examples cover installing the notification service worker, connecting your buttons, and checking that subscribing and unsubscribing work. + +> **Using Shopify or VTEX?** Connecting your store to Hellotext automatically installs the notification service worker and initializes Hellotext.js with it. Skip steps 1 and 2. Start at step 3 if you are building your own subscription buttons. See [Set up Push notifications]({% link _integrations/setup-push-notifications.md %}) for the platform setup paths. + +## Before you start + +You need: + +- A **Pro or Enterprise** plan with Push available for your business. For a custom store, confirm with Hellotext that Push is enabled before testing; publishing the worker alone does not complete business setup. +- Access to your storefront code and hosting, including the ability to publish a JavaScript file on your store's HTTPS domain. +- Hellotext.js installed and your public Business ID. Follow [Integrate a custom store with Hellotext]({% link _developers/custom-store-integration.md %}) if you have not installed it yet. +- A browser that supports Web Push. See [Troubleshoot Push notifications]({% link _troubleshooting-deliverability/troubleshoot-push-notifications.md %}) for device requirements and browser differences. + +You do not need to generate or configure VAPID keys, provide a private API token, or build subscription API requests. Hellotext.js receives the public configuration it needs and manages the subscription requests for you. + +## 1. Publish the notification service worker + +A service worker is a JavaScript file that the browser uses to receive and display notifications. It must be available as its own file on your store, even when you load Hellotext.js from a CDN. + +1. Create a file named `hellotext-sw.js` in the public root of your storefront. +2. Copy the following code into it. +3. Deploy it so that `https://store.example.com/hellotext-sw.js` serves the file. Replace `store.example.com` with the exact domain visitors use. + +```javascript +self.addEventListener('install', event => { + event.waitUntil(self.skipWaiting()) +}) + +self.addEventListener('push', event => { + if (!event.data) return + + let payload + + try { + payload = event.data.json() + } catch (error) { + return + } + + if ( + !payload || + payload.source !== 'hellotext' || + typeof payload.title !== 'string' || + !payload.title + ) { + return + } + + event.stopImmediatePropagation() + + const options = payload.options || {} + + event.waitUntil( + self.registration.showNotification(payload.title, { + ...options, + data: { ...options.data, source: 'hellotext' }, + }), + ) +}) + +self.addEventListener('notificationclick', event => { + const { data } = event.notification + + if (!data || data.source !== 'hellotext') return + + event.notification.close() + + let url + + try { + url = new URL(data.url || '/', self.location.origin) + } catch (error) { + return + } + + if (url.protocol !== 'https:' && url.protocol !== 'http:') return + + event.waitUntil( + self.clients.matchAll({ type: 'window', includeUncontrolled: true }).then(clients => { + const client = clients.find(windowClient => windowClient.url === url.href) + + return client ? client.focus() : self.clients.openWindow(url.href) + }), + ) +}) +``` + +The worker displays a notification and opens its destination when clicked. Keep the `install` handler: it allows an updated version to activate while visitors still have your store open, instead of waiting for them to close every tab. See [how `skipWaiting()` works](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerGlobalScope/skipWaiting) for details. + +### Check the published URL + +Open the worker URL directly in your browser. Confirm that: + +- It returns the JavaScript above with an HTTP `200` response. +- Its `Content-Type` is a JavaScript type, such as `text/javascript`. +- It uses the same origin as the storefront: the same scheme, hostname, and port. For a page on `https://www.example.com`, publish the worker on `https://www.example.com`, not `https://example.com` or a separate CDN domain. +- It does not redirect to a login page or return your storefront's HTML fallback. + +Putting the file at the public root, as shown above, gives it a default scope covering the storefront. If your framework uses a `public` directory, check the deployed URL: the URL should be `/hellotext-sw.js`, not `/public/hellotext-sw.js`. These requirements come from [service worker registration](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerContainer/register). + +### If you already have a service worker + +Add these handlers to the worker you already maintain and use that file's URL in step 2. Preserve its existing caching and other behavior. + +Place the Hellotext `push` handler **before any generic push handler**, including before code that imports one. Its `event.stopImmediatePropagation()` call applies only to Hellotext messages and prevents a later generic handler from displaying the same notification again. Include the Hellotext handlers only once in the final worker file. + +## 2. Pass the worker URL when initializing Hellotext + +Find your existing `Hellotext.initialize()` call. Add the `push` option to that call and keep your other settings. Do not add a second initialization just for Push. + +The minimal initialization looks like this: + +```javascript +await Hellotext.initialize('BUSINESS_ID', { + push: { + serviceWorkerUrl: '/hellotext-sw.js', + }, +}) +``` + +Replace `BUSINESS_ID` with your public Hellotext Business ID and the worker URL with the file you published. An absolute URL is also valid if it is on the same origin as the page. + +Run the button setup in the next steps after initialization has finished and the button elements exist in the page. If Shopify or VTEX handles initialization, use its existing initialized Hellotext instance. + +If your storefront already registers and activates the worker for the current page, you can omit `serviceWorkerUrl`. In that case, your existing registration code is responsible for updating and activating the worker. + +You can also pass `push.channelId` if Hellotext has given you a specific Push channel ID to use. Otherwise, leave it out. + +## 3. Add a Subscribe button + +Add the following elements where visitors manage notifications: + +```html + + +

+``` + +After Hellotext initialization, connect the Subscribe button: + +```javascript +const subscribeButton = document.querySelector('#push-subscribe') +const unsubscribeButton = document.querySelector('#push-unsubscribe') +const pushStatus = document.querySelector('#push-status') + +subscribeButton.disabled = !Hellotext.push +unsubscribeButton.disabled = !Hellotext.push + +subscribeButton.addEventListener('click', async () => { + if (!Hellotext.push) return + + try { + const response = await Hellotext.push.subscribe() + + if (response?.succeeded) { + pushStatus.textContent = 'You are subscribed to notifications.' + } else if (response?.failed) { + pushStatus.textContent = 'We could not complete your subscription. Please try again.' + } + } catch (error) { + pushStatus.textContent = 'Subscription was not completed. Check notification permissions and try again.' + } +}) +``` + +Call `Hellotext.push.subscribe()` directly from the click handler. Do not wait for another asynchronous operation before calling it; the browser may require the visitor's click to show its permission prompt. The method also works when permission has already been granted and reuses an existing Hellotext subscription when one is present. + +Show the subscribed confirmation only when `response.succeeded` is true. The presence of `Hellotext.push`, a granted browser permission, or a browser subscription alone does not confirm that registration with Hellotext succeeded. If no response is returned, do not show a success message. + +When `Hellotext.push` is unavailable, keep these controls disabled or hide them. Push can be unavailable because the browser does not support it, the page disables it, or the required configuration is unavailable. + +## 4. Add the Unsubscribe action + +Add this handler alongside the Subscribe handler. It uses the same button and status elements from step 3: + +```javascript +unsubscribeButton.addEventListener('click', async () => { + if (!Hellotext.push) return + + try { + const response = await Hellotext.push.unsubscribe() + + if (response === null || response?.succeeded) { + pushStatus.textContent = 'You are unsubscribed from notifications.' + } else if (response?.failed) { + pushStatus.textContent = 'We could not unsubscribe you. Please try again.' + } + } catch (error) { + pushStatus.textContent = 'We could not unsubscribe you. Please try again.' + } +}) +``` + +A `null` result means there was no subscription to remove, so it is safe to confirm that the visitor is already unsubscribed. A failed response or a rejected request should leave the action available for another attempt. A missing response is not a success result. + +Unsubscribing applies to the current browser subscription. It does not revoke the site's browser permission or remove subscriptions from the visitor's other browsers or devices. + +## 5. Verify the complete flow + +1. Open your deployed storefront in a supported browser. +2. Select **Subscribe to notifications** and complete the browser prompt if one appears. +3. Confirm that your page displays the success message from `response.succeeded`. +4. Reload the page and confirm that initialization does not report a worker error. Existing Hellotext subscriptions are restored automatically. +5. Select **Unsubscribe from notifications** and wait for its confirmation. +6. Select **Subscribe to notifications** again to verify that visitors can subscribe again. + +These steps verify subscription setup. To test delivery as well, ask Hellotext to arrange a test notification for your browser. Check that it appears once and that clicking it opens the intended page. Image and action-button support depends on the browser and operating system; use [Troubleshoot Push notifications]({% link _troubleshooting-deliverability/troubleshoot-push-notifications.md %}) if the result differs between devices. + +## Disable Push on a particular page + +Set `push: false` in that page's existing initialization options: + +```javascript +await Hellotext.initialize('BUSINESS_ID', { push: false }) +``` + +Keep any other initialization options your page uses. This makes `Hellotext.push` unavailable on the page. It does not unsubscribe previous visitors; use `Hellotext.push.unsubscribe()` while Push is enabled to remove the current browser subscription. + +## Related guides + +- [Set up Push notifications]({% link _integrations/setup-push-notifications.md %}) +- [Troubleshoot Push notifications]({% link _troubleshooting-deliverability/troubleshoot-push-notifications.md %}) +- [Integrate a custom store with Hellotext]({% link _developers/custom-store-integration.md %}) +- [Hellotext.js Push reference](https://github.com/hellotext/hellotext.js/blob/main/docs/push.md) diff --git a/_i18n/en/integrations/connect-shopify.md b/_i18n/en/integrations/connect-shopify.md index 61e49176..5c95e530 100644 --- a/_i18n/en/integrations/connect-shopify.md +++ b/_i18n/en/integrations/connect-shopify.md @@ -42,6 +42,12 @@ If you start an import, you do not need to wait on the page until it finishes. C If you see your Shopify store listed as connected, the integration is ready. +## Automatic Push installation + +Connecting Shopify through the Hellotext integration automatically installs and configures Push notifications on your storefront. Push is available on Pro and Enterprise. You do not need to upload a service-worker file or add another Hellotext.js initialization. + +If your store was already connected, make sure its Hellotext app is up to date and reload the live storefront after the update is available. Then follow [Set up Push notifications]({% link _integrations/setup-push-notifications.md %}) to add subscription controls where needed and verify the setup. + ## Verify the connection Before launching a broad playbook or campaign, run a small end-to-end test. diff --git a/_i18n/en/integrations/connect-vtex.md b/_i18n/en/integrations/connect-vtex.md index 757e750d..ad7a40e0 100644 --- a/_i18n/en/integrations/connect-vtex.md +++ b/_i18n/en/integrations/connect-vtex.md @@ -54,6 +54,12 @@ unlocks insight into what your customers do on the website, including: - Cart Modifications (additions or removals) - Order Placement +#### Automatic Push installation + +The Hellotext VTEX integration also installs and configures Push notifications through its storefront pixel. Push is available on Pro and Enterprise. Complete the pixel installation above; you do not need to upload a separate worker or add another Hellotext.js initialization. + +If the pixel was installed before Push became available, make sure the Hellotext app is up to date and wait for the updated pixel to reach the live storefront. Follow [Set up Push notifications]({% link _integrations/setup-push-notifications.md %}) for subscription controls and verification. + #### Checkout Funnel Tracking diff --git a/_i18n/en/integrations/setup-overview.md b/_i18n/en/integrations/setup-overview.md index 9e7162f3..3aa65375 100644 --- a/_i18n/en/integrations/setup-overview.md +++ b/_i18n/en/integrations/setup-overview.md @@ -52,6 +52,8 @@ Keep reading: - [Connect Facebook Messenger]({% link _integrations/connect-facebook-messenger.md %}) - [Facebook Messenger fundamentals]({% link _numbers/facebook-messenger-fundamentals.md %}) +For Push notifications on Pro and Enterprise, Shopify and VTEX handle installation automatically. Custom storefronts use Hellotext.js. Follow [Set up Push notifications]({% link _integrations/setup-push-notifications.md %}) for the setup path and subscription test. + ### 4. Add capture and checkout tools Once your data source and messaging channel are ready, add the capture tools customers will use to subscribe. diff --git a/_i18n/en/integrations/setup-push-notifications.md b/_i18n/en/integrations/setup-push-notifications.md new file mode 100644 index 00000000..e3b6beaa --- /dev/null +++ b/_i18n/en/integrations/setup-push-notifications.md @@ -0,0 +1,70 @@ +Push notifications let your store reach subscribed visitors through notifications displayed by their browser or device. Selecting a notification takes the visitor to the destination you included, such as a product or promotion. + +Push is available on the **Pro** and **Enterprise** plans. + +> **Shopify and VTEX install Push automatically.** Connect your store through the Hellotext integration and complete its storefront installation. You do not need to upload a service-worker file or initialize Hellotext.js yourself. Continue with the subscription controls and verification below. + +## 1. Choose your setup path + +| Your storefront | What to do | +| --- | --- | +| **Shopify** | Complete [Connect Shopify]({% link _integrations/connect-shopify.md %}). The integration handles Push installation. | +| **VTEX** | Complete [Connect VTEX]({% link _integrations/connect-vtex.md %}), including the Hellotext pixel installation. The integration handles Push installation. | +| **A custom storefront or another platform** | Ask your developer to follow [Set up Push with Hellotext.js]({% link _developers/setup-push-with-hellotext-js.md %}). | + +Use the Hellotext business connected to the store you want visitors to subscribe to. Test on the published HTTPS storefront customers actually visit, rather than a theme editor or preview window. + +## 2. Complete automatic installation on Shopify or VTEX + +1. Open the correct business in Hellotext. +2. Go to **Settings > Integrations** and check whether your store is already connected. +3. If it is not connected, follow the [Shopify connection guide]({% link _integrations/connect-shopify.md %}) or the [VTEX connection guide]({% link _integrations/connect-vtex.md %}). Complete all storefront installation steps in that guide. +4. If your store was connected before Push became available, make sure the installed Hellotext app or pixel is up to date. You do not need to remove and reconnect a working integration. +5. Open the live storefront and reload it after the updated integration is available. + +The integration supplies the notification worker and configures Hellotext.js to use it. Later updates to that installation are handled through the integration and the browser's worker-update process. + +There is no separate Push credential to create or paste into the integration. If an updated app or pixel has not reached the live storefront yet, allow the platform update to finish before testing. See [Troubleshoot Push notifications]({% link _troubleshooting-deliverability/troubleshoot-push-notifications.md %}) if setup is still unavailable. + +## 3. Set up a custom storefront + +Skip this section if you use the automatic Shopify or VTEX installation. + +1. Confirm with Hellotext support that Push is enabled for the business you are connecting. +2. Give your developer the [Hellotext.js Push setup guide]({% link _developers/setup-push-with-hellotext-js.md %}). +3. Have them publish the notification worker on your website, configure the existing Hellotext.js initialization, and add the subscription controls. +4. Test on the live storefront after those changes are published. + +If your store is not yet connected to Hellotext at all, start with [Integrate a custom store with Hellotext]({% link _developers/custom-store-integration.md %}). + +## 4. Give visitors a way to subscribe and unsubscribe + +Your website needs a visible subscription action, such as **Subscribe to notifications**, and a way to unsubscribe. If these controls are not yet present, ask your developer to connect them using the [Subscribe and Unsubscribe steps]({% link _developers/setup-push-with-hellotext-js.md %}). This also applies to stores with automatic installation. + +A visitor selects the subscription action and allows notifications when the browser asks. The website should confirm success only after the subscription finishes. Installing the integration does not subscribe visitors by itself. + +A subscription belongs to the browser and device where the visitor created it. Test each browser or device separately; allowing notifications on one does not subscribe another. + +## 5. Verify the setup + +Use a browser and device where you can receive notifications: + +1. Open the published store and select its notification subscription action. +2. Allow notifications if the browser asks, then wait for the website's successful subscription confirmation. +3. Keep track of the storefront URL, browser, device, and approximate time of the test. +4. Contact Hellotext support to arrange a test notification to that subscription. Share those details so the team can identify your test. +5. Confirm that the notification appears and that selecting it opens the expected page. +6. Use the website's unsubscribe action and wait for its confirmation. If you need to test again, subscribe again from the same page. + +Start with a simple text notification. Images and buttons can display differently across browsers and operating systems, so a missing image does not by itself mean delivery failed. + +If the subscription or delivery test fails, follow [Troubleshoot Push notifications]({% link _troubleshooting-deliverability/troubleshoot-push-notifications.md %}). + +## Related guides + +- [Set up Push with Hellotext.js]({% link _developers/setup-push-with-hellotext-js.md %}) +- [Troubleshoot Push notifications]({% link _troubleshooting-deliverability/troubleshoot-push-notifications.md %}) +- [Connect Shopify]({% link _integrations/connect-shopify.md %}) +- [Connect VTEX]({% link _integrations/connect-vtex.md %}) +- [Messaging channels overview]({% link _numbers/messaging-overview.md %}) +- [Contact Hellotext Support]({% link _troubleshooting-deliverability/contact-hellotext-support.md %}) diff --git a/_i18n/en/numbers/messaging-overview.md b/_i18n/en/numbers/messaging-overview.md index 9dbe3edc..68f18c24 100644 --- a/_i18n/en/numbers/messaging-overview.md +++ b/_i18n/en/numbers/messaging-overview.md @@ -12,6 +12,8 @@ Use **Instagram DM** when customers discover your business on Instagram and init Use **Facebook Messenger** when customers contact your Facebook Page and your team needs those conversations in the Inbox. +Use **Push notifications** to reach visitors who subscribe through your website. Push is available on Pro and Enterprise, with automatic installation through Shopify and VTEX. Start with [Set up Push notifications]({% link _integrations/setup-push-notifications.md %}). + Use **Mercado Libre** when you sell through the marketplace and need transaction-specific post-sale conversations in the Inbox. It is tied to eligible Mercado Libre orders and is not a general campaign destination. Many businesses use several channels: SMS for reach, WhatsApp for richer outbound and conversational experiences, Instagram or Messenger for customer-initiated social conversations, and Mercado Libre for marketplace post-sale support. Campaigns, routes, and playbooks can use the channels differently, so confirm how channel selection works for the experience you are launching. diff --git a/_i18n/en/troubleshooting-deliverability/troubleshoot-push-notifications.md b/_i18n/en/troubleshooting-deliverability/troubleshoot-push-notifications.md new file mode 100644 index 00000000..3887fa0e --- /dev/null +++ b/_i18n/en/troubleshooting-deliverability/troubleshoot-push-notifications.md @@ -0,0 +1,97 @@ +Use this guide when a customer cannot subscribe to your store's Push notifications, a notification does not arrive, or its appearance differs between browsers. + +For alerts about conversations received by your team in Hellotext, use [Inbox browser notifications]({% link _team/inbox-browser-notifications.md %}). + +## Before you start + +Use one test device and browser first. Note the store URL, browser and operating system versions, and the time of the problem. If a notification arrived, keep a screenshot before dismissing it. + +Push is available on **Pro and Enterprise**. Shopify and VTEX connections install the required components automatically. Merchants using those integrations do not need to publish a service-worker file or initialize Hellotext.js manually. For the complete setup path, see [Set up Push notifications]({% link _integrations/setup-push-notifications.md %}). + +## 1. A notification does not arrive + +Work through these checks in order: + +1. **Open the live store on the device you are testing.** Use the same browser profile and exact store address where you subscribed. A subscription in one browser or device does not subscribe your other browsers or devices. +2. **Confirm that you completed the store's notification opt-in.** A browser showing notifications as allowed is only one part of setup: the store must also finish subscribing that browser to Hellotext. If the opt-in showed an error or never confirmed success, retry it once after reloading the store. +3. **Check the site's notification setting.** If you previously blocked notifications, change that setting in the browser before using the store's opt-in again. The store cannot override a blocked permission. +4. **Check your device's notification settings.** Allow notifications for the browser or installed web app. Check Focus, Do Not Disturb, and the notification center: a notification may have arrived without showing a banner. +5. **Check recent browser changes.** If you cleared site data, removed the installed web app, or switched browser profiles, open the store and complete its opt-in again. Use a regular browser window for testing. +6. **Confirm the delivery test.** Ask [Hellotext Support]({% link _troubleshooting-deliverability/contact-hellotext-support.md %}) to check the subscription and arrange a controlled test to that browser. Record the test time and whether it appears in the notification center. + +On **iPhone and iPad**, Web Push requires iOS or iPadOS 16.4 or later and a web app added to the Home Screen. Open the store from its Home Screen icon and complete its opt-in there. If it opens as a normal browser tab, ask your developer to check the store's web app setup. See [WebKit's Home Screen requirements](https://webkit.org/blog/13878/web-push-for-web-apps-on-ios-and-ipados/). + +## 2. Setup fails or a service-worker warning appears + +A service worker is the small background script that receives notifications for your store. A warning such as `Push service worker is not available` means the browser could not obtain an active worker for Push. + +### Shopify or VTEX + +1. Confirm that the store is connected to the correct Hellotext business. +2. Confirm that the current Hellotext integration is installed and enabled on the live storefront. +3. After an integration update, reopen or reload the live store before retrying the opt-in. +4. If the warning persists, send Support the store URL and the exact warning text. + +The integration manages the worker. Do not replace the platform's worker or add a second manual installation to fix this warning. + +### A custom website using Hellotext.js + +Ask your developer to follow [Set up Push with Hellotext.js]({% link _developers/setup-push-with-hellotext-js.md %}) and check: + +1. The live site uses HTTPS. +2. The configured worker URL serves the JavaScript file on the same origin as the storefront, without a login page or an error response. +3. The worker has become active and includes the Hellotext notification handlers. +4. The page initializes Hellotext.js with the intended worker URL and waits for initialization before offering the opt-in. + +Include the exact error rather than repeatedly reinstalling the integration or clearing browser data. + +## 3. The notification arrives without an image or buttons + +The browser and operating system control the appearance of a notification. Receiving the text without every visual element does not, by itself, mean delivery failed. + +| Where you are testing | What to expect | +| --- | --- | +| Safari | Large notification images and custom action buttons are not supported. | +| Chrome and other Chromium browsers using native macOS notifications | Large images are ignored. Actions may be behind the notification's hover or **More** menu. | +| Other browser and device combinations | Appearance and the number of visible actions vary. Expand the notification and test the actual browser and device your customers use. | + +See [Safari's notification options](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/Modules/notifications/NotificationOptions.idl) and [Chrome's macOS notification behavior](https://developer.chrome.com/blog/native-mac-os-notifications). + +If an image is missing in a browser that supports it, ask your developer to confirm that its URL loads without signing in. Keep the message understandable from its title and body, and check that clicking the notification opens the expected page. + +## 4. Two notifications appear for one message + +One notification with the complete content and another with only the title can mean the store displays the same delivery twice. This can happen when two notification handlers process one message. + +1. Note whether both notifications arrive at the same time and have the same title. +2. Take a screenshot of both, including any difference in text or buttons. +3. For Shopify or VTEX, confirm the current integration is installed, then reopen the live store and repeat one controlled test. +4. If it continues, contact Support. For a custom site, ask your developer to check that a Hellotext message is displayed only once, following [the developer setup guide]({% link _developers/setup-push-with-hellotext-js.md %}). + +Do not remove other store services or overwrite the platform worker to troubleshoot duplicates. + +## 5. Clicking the notification opens the wrong page + +Record the destination you expected and the URL that actually opened. Check whether the same happens when clicking the notification itself and, where available, an action button. + +For a custom implementation, ask your developer to review the notification's destination and click handler. For an integrated store, send the example to Support. Displaying a custom action button does not automatically give it a different destination. + +## When to contact Support + +Include: + +- Your Hellotext business and live store URL. +- Whether you use Shopify, VTEX, or a custom installation. +- The browser, operating system, and device used for the test. +- The approximate time and time zone. +- Whether the opt-in completed and whether any notification arrived. +- The exact warning, screenshot, or unexpected destination. +- Any recent integration update, domain change, or browser data reset. + +See [Contact Hellotext Support]({% link _troubleshooting-deliverability/contact-hellotext-support.md %}) for contact details. + +## Related guides + +- [Set up Push notifications]({% link _integrations/setup-push-notifications.md %}) +- [Set up Push with Hellotext.js]({% link _developers/setup-push-with-hellotext-js.md %}) +- [Inbox browser notifications]({% link _team/inbox-browser-notifications.md %}) diff --git a/_i18n/en/troubleshooting-deliverability/troubleshooting-overview.md b/_i18n/en/troubleshooting-deliverability/troubleshooting-overview.md index 683e1460..1715a354 100644 --- a/_i18n/en/troubleshooting-deliverability/troubleshooting-overview.md +++ b/_i18n/en/troubleshooting-deliverability/troubleshooting-overview.md @@ -29,6 +29,8 @@ If the issue is a WhatsApp template under review, rejected, flagged, or paused, For channel setup context, keep reading: [Messaging channels overview]({% link _numbers/messaging-overview.md %}). +If a Push notification does not arrive, appears twice, or is missing an image or buttons, follow [Troubleshoot Push notifications]({% link _troubleshooting-deliverability/troubleshoot-push-notifications.md %}). + ## Campaigns If a campaign result looks lower than expected, review the selected audience, channel, message content, links, timing, and report metrics before comparing results. diff --git a/_i18n/es/developers/setup-push-with-hellotext-js.md b/_i18n/es/developers/setup-push-with-hellotext-js.md new file mode 100644 index 00000000..48adc919 --- /dev/null +++ b/_i18n/es/developers/setup-push-with-hellotext-js.md @@ -0,0 +1,224 @@ +Usa esta guía para agregar controles de suscripción a notificaciones push a tu tienda con Hellotext.js. Los ejemplos incluyen la instalación del service worker de notificaciones, la conexión de los botones y la verificación de la suscripción y su cancelación. + +> **¿Usas Shopify o VTEX?** Al conectar tu tienda con Hellotext, la integración instala automáticamente el service worker de notificaciones e inicializa Hellotext.js con él. Omite los pasos 1 y 2. Comienza en el paso 3 si vas a crear tus propios botones de suscripción. Consulta [Configura las notificaciones push]({% link _integrations/setup-push-notifications.md %}) para ver las instrucciones de cada plataforma. + +## Antes de empezar + +Necesitas: + +- Un plan **Pro o Enterprise** con Push disponible para tu negocio. Si tienes una tienda personalizada, confirma con Hellotext que Push esté habilitado antes de probarlo; publicar el worker por sí solo no completa la configuración del negocio. +- Acceso al código y al alojamiento de tu tienda, con la posibilidad de publicar un archivo JavaScript en el dominio HTTPS de la tienda. +- Hellotext.js instalado y el Business ID público de tu negocio. Si todavía no lo instalaste, sigue [Integra una tienda propia con Hellotext]({% link _developers/custom-store-integration.md %}). +- Un navegador compatible con Web Push. Consulta [Soluciona problemas con las notificaciones push]({% link _troubleshooting-deliverability/troubleshoot-push-notifications.md %}) para conocer los requisitos del dispositivo y las diferencias entre navegadores. + +No necesitas generar ni configurar claves VAPID, proporcionar un token privado de la API ni crear solicitudes de suscripción a la API. Hellotext.js recibe la configuración pública que necesita y administra las solicitudes de suscripción. + +## 1. Publica el service worker de notificaciones + +Un service worker es un archivo JavaScript que el navegador usa para recibir y mostrar notificaciones. Debe estar disponible como un archivo independiente en tu tienda, incluso si cargas Hellotext.js desde un CDN. + +1. Crea un archivo llamado `hellotext-sw.js` en la raíz pública de tu tienda. +2. Copia el siguiente código en él. +3. Publícalo para que `https://store.example.com/hellotext-sw.js` devuelva el archivo. Reemplaza `store.example.com` por el dominio exacto que usan tus visitantes. + +```javascript +self.addEventListener('install', event => { + event.waitUntil(self.skipWaiting()) +}) + +self.addEventListener('push', event => { + if (!event.data) return + + let payload + + try { + payload = event.data.json() + } catch (error) { + return + } + + if ( + !payload || + payload.source !== 'hellotext' || + typeof payload.title !== 'string' || + !payload.title + ) { + return + } + + event.stopImmediatePropagation() + + const options = payload.options || {} + + event.waitUntil( + self.registration.showNotification(payload.title, { + ...options, + data: { ...options.data, source: 'hellotext' }, + }), + ) +}) + +self.addEventListener('notificationclick', event => { + const { data } = event.notification + + if (!data || data.source !== 'hellotext') return + + event.notification.close() + + let url + + try { + url = new URL(data.url || '/', self.location.origin) + } catch (error) { + return + } + + if (url.protocol !== 'https:' && url.protocol !== 'http:') return + + event.waitUntil( + self.clients.matchAll({ type: 'window', includeUncontrolled: true }).then(clients => { + const client = clients.find(windowClient => windowClient.url === url.href) + + return client ? client.focus() : self.clients.openWindow(url.href) + }), + ) +}) +``` + +El worker muestra una notificación y abre su destino al hacer clic. Conserva el manejador de `install`: permite que una versión actualizada se active mientras los visitantes tienen la tienda abierta, en lugar de esperar a que cierren todas las pestañas. Consulta [cómo funciona `skipWaiting()`](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerGlobalScope/skipWaiting) para más detalles. + +### Revisa la URL publicada + +Abre la URL del worker directamente en el navegador. Confirma que: + +- Devuelve el JavaScript anterior con una respuesta HTTP `200`. +- Su `Content-Type` es un tipo JavaScript, como `text/javascript`. +- Usa el mismo origen que la tienda: el mismo esquema, nombre de host y puerto. Para una página en `https://www.example.com`, publica el worker en `https://www.example.com`, no en `https://example.com` ni en un dominio de CDN independiente. +- No redirige a una página de inicio de sesión ni devuelve el HTML de tu tienda como respuesta alternativa. + +Publicar el archivo en la raíz pública, como en el ejemplo, le da un alcance predeterminado que cubre la tienda. Si tu framework usa un directorio `public`, revisa la URL publicada: debe ser `/hellotext-sw.js`, no `/public/hellotext-sw.js`. Estos requisitos corresponden al [registro de service workers](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerContainer/register). + +### Si ya tienes un service worker + +Agrega estos manejadores al worker que ya mantienes y usa la URL de ese archivo en el paso 2. Conserva su comportamiento de caché y las demás funciones existentes. + +Coloca el manejador de `push` de Hellotext **antes de cualquier manejador genérico de push**, incluso antes del código que importe uno. Su llamada a `event.stopImmediatePropagation()` se aplica solo a los mensajes de Hellotext e impide que un manejador genérico posterior vuelva a mostrar la misma notificación. Incluye los manejadores de Hellotext una sola vez en el archivo final del worker. + +## 2. Pasa la URL del worker al inicializar Hellotext + +Busca la llamada a `Hellotext.initialize()` que ya usa tu tienda. Agrega la opción `push` a esa llamada y conserva las demás opciones. No agregues una segunda inicialización solo para Push. + +La inicialización mínima es: + +```javascript +await Hellotext.initialize('BUSINESS_ID', { + push: { + serviceWorkerUrl: '/hellotext-sw.js', + }, +}) +``` + +Reemplaza `BUSINESS_ID` por el Business ID público de tu negocio en Hellotext y la URL del worker por la del archivo que publicaste. También puedes usar una URL absoluta si pertenece al mismo origen que la página. + +Ejecuta la configuración de los botones de los próximos pasos después de que termine la inicialización y cuando los elementos ya existan en la página. Si Shopify o VTEX se encarga de la inicialización, usa la instancia de Hellotext que ya inicializó la integración. + +Si tu tienda ya registra y activa el worker para la página actual, puedes omitir `serviceWorkerUrl`. En ese caso, el código de registro que ya tienes es responsable de actualizar y activar el worker. + +También puedes pasar `push.channelId` si Hellotext te proporcionó un ID específico de canal Push. De lo contrario, omítelo. + +## 3. Agrega un botón de suscripción + +Agrega los siguientes elementos donde tus visitantes administran las notificaciones: + +```html + + +

+``` + +Después de inicializar Hellotext, conecta el botón de suscripción: + +```javascript +const subscribeButton = document.querySelector('#push-subscribe') +const unsubscribeButton = document.querySelector('#push-unsubscribe') +const pushStatus = document.querySelector('#push-status') + +subscribeButton.disabled = !Hellotext.push +unsubscribeButton.disabled = !Hellotext.push + +subscribeButton.addEventListener('click', async () => { + if (!Hellotext.push) return + + try { + const response = await Hellotext.push.subscribe() + + if (response?.succeeded) { + pushStatus.textContent = 'Te suscribiste a las notificaciones.' + } else if (response?.failed) { + pushStatus.textContent = 'No pudimos completar la suscripción. Inténtalo de nuevo.' + } + } catch (error) { + pushStatus.textContent = 'La suscripción no se completó. Revisa los permisos de notificaciones e inténtalo de nuevo.' + } +}) +``` + +Llama a `Hellotext.push.subscribe()` directamente desde el manejador del clic. No esperes a que termine otra operación asíncrona antes de llamarlo; el navegador puede necesitar el clic del visitante para mostrar la solicitud de permiso. El método también funciona cuando el permiso ya está concedido y reutiliza una suscripción existente de Hellotext cuando la hay. + +Muestra la confirmación de suscripción solo cuando `response.succeeded` sea verdadero. La presencia de `Hellotext.push`, el permiso concedido en el navegador o una suscripción del navegador por sí solos no confirman que el registro en Hellotext haya sido exitoso. Si el método no devuelve una respuesta, no muestres un mensaje de éxito. + +Cuando `Hellotext.push` no esté disponible, mantén los controles deshabilitados u ocúltalos. Puede no estar disponible porque el navegador no lo admite, la página lo desactiva o falta la configuración necesaria. + +## 4. Agrega la acción para cancelar la suscripción + +Agrega este manejador junto al de suscripción. Usa los mismos elementos de botón y estado del paso 3: + +```javascript +unsubscribeButton.addEventListener('click', async () => { + if (!Hellotext.push) return + + try { + const response = await Hellotext.push.unsubscribe() + + if (response === null || response?.succeeded) { + pushStatus.textContent = 'La suscripción a las notificaciones está cancelada.' + } else if (response?.failed) { + pushStatus.textContent = 'No pudimos cancelar la suscripción. Inténtalo de nuevo.' + } + } catch (error) { + pushStatus.textContent = 'No pudimos cancelar la suscripción. Inténtalo de nuevo.' + } +}) +``` + +Un resultado `null` significa que no había una suscripción para eliminar, por lo que puedes confirmar que ya estaba cancelada. Ante una respuesta fallida o una solicitud rechazada, deja la acción disponible para volver a intentarlo. La ausencia de una respuesta no equivale a un resultado exitoso. + +La cancelación se aplica a la suscripción del navegador actual. No revoca el permiso que el navegador concedió al sitio ni elimina las suscripciones de otros navegadores o dispositivos del visitante. + +## 5. Verifica el flujo completo + +1. Abre tu tienda publicada en un navegador compatible. +2. Selecciona **Suscribirme a las notificaciones** y completa la solicitud del navegador si aparece. +3. Confirma que la página muestra el mensaje de éxito correspondiente a `response.succeeded`. +4. Recarga la página y confirma que la inicialización no muestra errores del worker. Las suscripciones existentes de Hellotext se recuperan automáticamente. +5. Selecciona **Cancelar la suscripción** y espera la confirmación. +6. Selecciona **Suscribirme a las notificaciones** de nuevo para verificar que el visitante puede volver a suscribirse. + +Estos pasos verifican la configuración de la suscripción. Para probar también la entrega, pide a Hellotext que coordine el envío de una notificación de prueba a tu navegador. Revisa que aparezca una sola vez y que al hacer clic abra la página correcta. La compatibilidad con imágenes y botones de acción depende del navegador y del sistema operativo; consulta [Soluciona problemas con las notificaciones push]({% link _troubleshooting-deliverability/troubleshoot-push-notifications.md %}) si el resultado varía entre dispositivos. + +## Desactiva Push en una página específica + +Agrega `push: false` a las opciones de inicialización que ya usa esa página: + +```javascript +await Hellotext.initialize('BUSINESS_ID', { push: false }) +``` + +Conserva las demás opciones de inicialización de la página. Esto hace que `Hellotext.push` no esté disponible en ella. No cancela las suscripciones anteriores; usa `Hellotext.push.unsubscribe()` mientras Push esté habilitado para eliminar la suscripción del navegador actual. + +## Guías relacionadas + +- [Configura las notificaciones push]({% link _integrations/setup-push-notifications.md %}) +- [Soluciona problemas con las notificaciones push]({% link _troubleshooting-deliverability/troubleshoot-push-notifications.md %}) +- [Integra una tienda propia con Hellotext]({% link _developers/custom-store-integration.md %}) +- [Referencia de Push en Hellotext.js](https://github.com/hellotext/hellotext.js/blob/main/docs/push.md) diff --git a/_i18n/es/integrations/connect-shopify.md b/_i18n/es/integrations/connect-shopify.md index 288d5a5a..fddbaddd 100644 --- a/_i18n/es/integrations/connect-shopify.md +++ b/_i18n/es/integrations/connect-shopify.md @@ -42,6 +42,12 @@ Si inicias una importación, no necesitas esperar en la página hasta que termin Si ves tu tienda Shopify listada como conectada, la integración está lista. +## Instalación automática de Push + +Conectar Shopify mediante la integración de Hellotext instala y configura automáticamente las notificaciones push en tu tienda. Push está disponible en Pro y Enterprise. No necesitas subir un archivo de service worker ni agregar otra inicialización de Hellotext.js. + +Si tu tienda ya estaba conectada, asegúrate de que su app de Hellotext esté actualizada y recarga el sitio publicado cuando la actualización esté disponible. Después, sigue [Configura las notificaciones push]({% link _integrations/setup-push-notifications.md %}) para agregar controles de suscripción si hacen falta y verificar la configuración. + ## Verifica la conexión Antes de lanzar un playbook o campaña amplia, haz una prueba completa en pequeño. diff --git a/_i18n/es/integrations/connect-vtex.md b/_i18n/es/integrations/connect-vtex.md index 40c5d262..a44ad87b 100644 --- a/_i18n/es/integrations/connect-vtex.md +++ b/_i18n/es/integrations/connect-vtex.md @@ -52,6 +52,12 @@ En este paso, se te pedirá instalar el píxel de Hellotext en tu cuenta de VTEX - Modificaciones del carrito (agregados o eliminaciones) - Realización de pedidos +#### Instalación automática de Push + +La integración de Hellotext con VTEX también instala y configura las notificaciones push mediante su píxel en la tienda. Push está disponible en Pro y Enterprise. Completa la instalación del píxel anterior; no necesitas subir otro worker ni agregar otra inicialización de Hellotext.js. + +Si instalaste el píxel antes de que Push estuviera disponible, asegúrate de que la app de Hellotext esté actualizada y espera a que el píxel actualizado llegue a la tienda publicada. Sigue [Configura las notificaciones push]({% link _integrations/setup-push-notifications.md %}) para agregar controles de suscripción y verificar la configuración. + #### Seguimiento del Embudo de Checkout diff --git a/_i18n/es/integrations/setup-overview.md b/_i18n/es/integrations/setup-overview.md index 877858bd..4920c388 100644 --- a/_i18n/es/integrations/setup-overview.md +++ b/_i18n/es/integrations/setup-overview.md @@ -52,6 +52,8 @@ Sigue leyendo: - [Conecta Facebook Messenger]({% link _integrations/connect-facebook-messenger.md %}) - [Fundamentos de Facebook Messenger]({% link _numbers/facebook-messenger-fundamentals.md %}) +Para las notificaciones push en Pro y Enterprise, Shopify y VTEX se encargan de la instalación automáticamente. Las tiendas personalizadas usan Hellotext.js. Sigue [Configura las notificaciones push]({% link _integrations/setup-push-notifications.md %}) para elegir cómo instalarlas y probar la suscripción. + ### 4. Agrega herramientas de captura y checkout Cuando tu fuente de datos y canal de mensajería estén listos, agrega las herramientas de captura que usarán tus clientes para suscribirse. diff --git a/_i18n/es/integrations/setup-push-notifications.md b/_i18n/es/integrations/setup-push-notifications.md new file mode 100644 index 00000000..0ce62f75 --- /dev/null +++ b/_i18n/es/integrations/setup-push-notifications.md @@ -0,0 +1,70 @@ +Las notificaciones push permiten que tu tienda llegue a los visitantes suscritos mediante avisos que muestra su navegador o dispositivo. Al seleccionar una notificación, el visitante abre el destino que incluiste, como un producto o una promoción. + +Push está disponible en los planes **Pro** y **Enterprise**. + +> **Shopify y VTEX instalan Push automáticamente.** Conecta tu tienda mediante la integración de Hellotext y completa la instalación en el sitio. No necesitas subir un archivo de service worker ni inicializar Hellotext.js por tu cuenta. Continúa con los controles de suscripción y la verificación que se explican abajo. + +## 1. Elige cómo configurar tu tienda + +| Tu tienda | Qué hacer | +| --- | --- | +| **Shopify** | Completa [Conecta Shopify]({% link _integrations/connect-shopify.md %}). La integración se encarga de instalar Push. | +| **VTEX** | Completa [Conecta VTEX]({% link _integrations/connect-vtex.md %}), incluida la instalación del píxel de Hellotext. La integración se encarga de instalar Push. | +| **Una tienda personalizada u otra plataforma** | Pide a tu desarrollador que siga [Configura Push con Hellotext.js]({% link _developers/setup-push-with-hellotext-js.md %}). | + +Usa el negocio de Hellotext conectado a la tienda a la que quieres que se suscriban los visitantes. Haz las pruebas en el sitio HTTPS publicado que visitan tus clientes, en lugar de una vista previa o el editor del tema. + +## 2. Completa la instalación automática en Shopify o VTEX + +1. Abre el negocio correcto en Hellotext. +2. Ve a **Configuración > Integraciones** y comprueba si tu tienda ya está conectada. +3. Si no está conectada, sigue la [guía de conexión de Shopify]({% link _integrations/connect-shopify.md %}) o la [guía de conexión de VTEX]({% link _integrations/connect-vtex.md %}). Completa todos los pasos de instalación en el sitio que indica la guía. +4. Si conectaste tu tienda antes de que Push estuviera disponible, asegúrate de que la app o el píxel de Hellotext instalado esté actualizado. No necesitas eliminar y volver a conectar una integración que funciona. +5. Abre la tienda publicada y recárgala después de que la integración actualizada esté disponible. + +La integración proporciona el worker de notificaciones y configura Hellotext.js para usarlo. Las actualizaciones posteriores se gestionan mediante la integración y el proceso de actualización de workers del navegador. + +No hay una credencial de Push adicional que debas crear o pegar en la integración. Si la actualización de la app o del píxel todavía no llegó a la tienda publicada, espera a que la plataforma termine de aplicarla antes de probar. Consulta [Soluciona problemas con las notificaciones push]({% link _troubleshooting-deliverability/troubleshoot-push-notifications.md %}) si la configuración sigue sin estar disponible. + +## 3. Configura una tienda personalizada + +Omite esta sección si usas la instalación automática de Shopify o VTEX. + +1. Confirma con soporte de Hellotext que Push esté habilitado para el negocio que vas a conectar. +2. Comparte con tu desarrollador la [guía de configuración de Push con Hellotext.js]({% link _developers/setup-push-with-hellotext-js.md %}). +3. Pídele que publique el worker de notificaciones en tu sitio, configure la inicialización existente de Hellotext.js y agregue los controles de suscripción. +4. Haz una prueba en la tienda publicada después de que esos cambios estén disponibles. + +Si tu tienda todavía no está conectada a Hellotext, empieza por [Integra una tienda propia con Hellotext]({% link _developers/custom-store-integration.md %}). + +## 4. Ofrece una forma de suscribirse y cancelar la suscripción + +Tu sitio necesita una acción visible, como **Suscribirme a las notificaciones**, y una forma de cancelar la suscripción. Si esos controles todavía no existen, pide a tu desarrollador que los conecte siguiendo los [pasos de suscripción y cancelación]({% link _developers/setup-push-with-hellotext-js.md %}). Esto también se aplica a las tiendas con instalación automática. + +El visitante selecciona la acción de suscripción y permite las notificaciones cuando el navegador lo solicita. El sitio debe confirmar el éxito solo cuando la suscripción haya terminado. Instalar la integración no suscribe a los visitantes por sí solo. + +La suscripción pertenece al navegador y dispositivo donde el visitante la creó. Prueba cada navegador o dispositivo por separado: permitir notificaciones en uno no suscribe a otro. + +## 5. Verifica la configuración + +Usa un navegador y dispositivo en el que puedas recibir notificaciones: + +1. Abre la tienda publicada y selecciona su acción de suscripción a notificaciones. +2. Permite las notificaciones si el navegador lo solicita y espera a que el sitio confirme la suscripción. +3. Anota la URL de la tienda, el navegador, el dispositivo y la hora aproximada de la prueba. +4. Contacta a soporte de Hellotext para coordinar una notificación de prueba a esa suscripción. Comparte esos datos para que el equipo pueda identificarla. +5. Confirma que aparezca la notificación y que, al seleccionarla, se abra la página esperada. +6. Usa la acción para cancelar la suscripción en el sitio y espera su confirmación. Si necesitas repetir la prueba, vuelve a suscribirte desde la misma página. + +Empieza con una notificación de texto sencilla. Las imágenes y los botones pueden mostrarse de manera diferente según el navegador y el sistema operativo; que falte una imagen no significa por sí solo que haya fallado la entrega. + +Si falla la suscripción o la prueba de entrega, sigue [Soluciona problemas con las notificaciones push]({% link _troubleshooting-deliverability/troubleshoot-push-notifications.md %}). + +## Guías relacionadas + +- [Configura Push con Hellotext.js]({% link _developers/setup-push-with-hellotext-js.md %}) +- [Soluciona problemas con las notificaciones push]({% link _troubleshooting-deliverability/troubleshoot-push-notifications.md %}) +- [Conecta Shopify]({% link _integrations/connect-shopify.md %}) +- [Conecta VTEX]({% link _integrations/connect-vtex.md %}) +- [Resumen de canales de mensajería]({% link _numbers/messaging-overview.md %}) +- [Contacta a soporte de Hellotext]({% link _troubleshooting-deliverability/contact-hellotext-support.md %}) diff --git a/_i18n/es/numbers/messaging-overview.md b/_i18n/es/numbers/messaging-overview.md index f0c92d7a..1853b248 100644 --- a/_i18n/es/numbers/messaging-overview.md +++ b/_i18n/es/numbers/messaging-overview.md @@ -12,6 +12,8 @@ Usa **Instagram DM** cuando los clientes descubren tu negocio en Instagram e ini Usa **Facebook Messenger** cuando los clientes escriben a tu página de Facebook y tu equipo necesita gestionar esas conversaciones en el Inbox. +Usa **notificaciones push** para llegar a los visitantes que se suscriben desde tu sitio. Push está disponible en Pro y Enterprise, con instalación automática mediante Shopify y VTEX. Empieza por [Configura las notificaciones push]({% link _integrations/setup-push-notifications.md %}). + Usa **Mercado Libre** cuando vendes por el marketplace y necesitas gestionar conversaciones posventa asociadas a operaciones específicas desde el Inbox. Está vinculado a órdenes elegibles de Mercado Libre y no es un destino general para campañas. Muchos negocios usan varios canales: SMS para alcance, WhatsApp para experiencias salientes y conversacionales más ricas, Instagram o Messenger para conversaciones sociales iniciadas por el cliente y Mercado Libre para atención posventa del marketplace. Las campañas, rutas y playbooks pueden usar los canales de maneras diferentes, por lo que debes confirmar cómo funciona la selección de canal para la experiencia que vas a lanzar. diff --git a/_i18n/es/troubleshooting-deliverability/troubleshoot-push-notifications.md b/_i18n/es/troubleshooting-deliverability/troubleshoot-push-notifications.md new file mode 100644 index 00000000..f7224093 --- /dev/null +++ b/_i18n/es/troubleshooting-deliverability/troubleshoot-push-notifications.md @@ -0,0 +1,97 @@ +Usa esta guía cuando un cliente no puede suscribirse a las notificaciones push de tu tienda, una notificación no llega o su apariencia cambia entre navegadores. + +Para las alertas que recibe tu equipo sobre conversaciones en Hellotext, consulta [Notificaciones del navegador para Inbox]({% link _team/inbox-browser-notifications.md %}). + +## Antes de empezar + +Empieza con un dispositivo y un navegador de prueba. Anota la URL de la tienda, las versiones del navegador y del sistema operativo, y la hora del problema. Si llegó una notificación, toma una captura antes de cerrarla. + +Push está disponible en **Pro y Enterprise**. Las conexiones con Shopify y VTEX instalan automáticamente los componentes necesarios. Si usas estas integraciones, no necesitas publicar un archivo service worker ni inicializar Hellotext.js manualmente. Consulta el proceso completo en [Configura las notificaciones push]({% link _integrations/setup-push-notifications.md %}). + +## 1. Una notificación no llega + +Revisa estos pasos en orden: + +1. **Abre la tienda publicada en el dispositivo de prueba.** Usa el mismo perfil del navegador y la misma dirección de la tienda donde te suscribiste. Suscribirte en un navegador o dispositivo no suscribe tus otros navegadores o dispositivos. +2. **Confirma que completaste la suscripción a las notificaciones de la tienda.** Que el navegador permita notificaciones es solo una parte del proceso: la tienda también debe terminar de suscribir ese navegador a Hellotext. Si el proceso mostró un error o nunca confirmó que terminó, recarga la tienda y vuelve a intentarlo una vez. +3. **Revisa el permiso de notificaciones del sitio.** Si antes las bloqueaste, cambia ese permiso en el navegador antes de volver a suscribirte desde la tienda. La tienda no puede anular un permiso bloqueado. +4. **Revisa la configuración de notificaciones del dispositivo.** Permite las notificaciones del navegador o de la aplicación web instalada. Revisa los modos de concentración, No molestar y el centro de notificaciones: una notificación puede haber llegado sin mostrar un aviso en pantalla. +5. **Revisa los cambios recientes del navegador.** Si borraste los datos del sitio, eliminaste la aplicación web instalada o cambiaste de perfil del navegador, abre la tienda y vuelve a completar la suscripción. Usa una ventana normal del navegador para la prueba. +6. **Confirma la prueba de entrega.** Pide a [Soporte de Hellotext]({% link _troubleshooting-deliverability/contact-hellotext-support.md %}) que revise la suscripción y coordine una prueba controlada a ese navegador. Anota la hora y si aparece en el centro de notificaciones. + +En **iPhone y iPad**, Web Push requiere iOS o iPadOS 16.4 o posterior y una aplicación web agregada a la pantalla de inicio. Abre la tienda desde ese icono y completa la suscripción allí. Si se abre como una pestaña normal, pide a tu desarrollador que revise la configuración de la aplicación web. Consulta [los requisitos de WebKit](https://webkit.org/blog/13878/web-push-for-web-apps-on-ios-and-ipados/). + +## 2. La configuración falla o aparece un aviso sobre el service worker + +Un service worker es un pequeño script que recibe las notificaciones de tu tienda en segundo plano. Un aviso como `Push service worker is not available` significa que el navegador no pudo obtener un worker activo para Push. + +### Shopify o VTEX + +1. Confirma que la tienda está conectada al negocio correcto de Hellotext. +2. Confirma que la integración actual de Hellotext está instalada y habilitada en la tienda publicada. +3. Después de actualizar la integración, vuelve a abrir o recarga la tienda publicada antes de intentar suscribirte otra vez. +4. Si el aviso continúa, envía a Soporte la URL de la tienda y el texto exacto del aviso. + +La integración administra el worker. No reemplaces el worker de la plataforma ni agregues otra instalación manual para resolver este aviso. + +### Un sitio personalizado con Hellotext.js + +Pide a tu desarrollador que siga [Configura Push con Hellotext.js]({% link _developers/setup-push-with-hellotext-js.md %}) y revise: + +1. El sitio publicado usa HTTPS. +2. La URL configurada del worker sirve el archivo JavaScript desde el mismo origen que la tienda, sin una página de inicio de sesión ni una respuesta de error. +3. El worker está activo e incluye el código de Hellotext que recibe las notificaciones. +4. La página inicializa Hellotext.js con la URL correcta del worker y espera a que termine la inicialización antes de ofrecer la suscripción. + +Incluye el error exacto en lugar de reinstalar repetidamente la integración o borrar los datos del navegador. + +## 3. La notificación llega sin imagen o sin botones + +El navegador y el sistema operativo controlan la apariencia de las notificaciones. Recibir el texto sin todos los elementos visuales no significa, por sí solo, que la entrega falló. + +| Dónde haces la prueba | Qué esperar | +| --- | --- | +| Safari | No admite imágenes grandes ni botones de acción personalizados en las notificaciones. | +| Chrome y otros navegadores Chromium que usan las notificaciones nativas de macOS | Las imágenes grandes se ignoran. Las acciones pueden aparecer al pasar el cursor o en el menú **Más** de la notificación. | +| Otras combinaciones de navegador y dispositivo | La apariencia y la cantidad de acciones visibles varían. Expande la notificación y prueba el navegador y dispositivo que usan tus clientes. | + +Consulta [las opciones de notificación de Safari](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/Modules/notifications/NotificationOptions.idl) y [el comportamiento de Chrome en macOS](https://developer.chrome.com/blog/native-mac-os-notifications). + +Si falta una imagen en un navegador que la admite, pide a tu desarrollador que confirme que su URL carga sin iniciar sesión. Asegúrate de que el título y el cuerpo sean suficientes para entender el mensaje, y comprueba que al hacer clic se abra la página esperada. + +## 4. Aparecen dos notificaciones por un mismo mensaje + +Una notificación con el contenido completo y otra solo con el título pueden indicar que la tienda muestra dos veces la misma entrega. Esto puede pasar cuando dos partes del código procesan el mismo mensaje. + +1. Anota si ambas notificaciones llegan al mismo tiempo y tienen el mismo título. +2. Toma una captura de ambas, incluidas las diferencias de texto o botones. +3. Para Shopify o VTEX, confirma que está instalada la integración actual. Luego vuelve a abrir la tienda publicada y repite una prueba controlada. +4. Si continúa, contacta a Soporte. Para un sitio personalizado, pide a tu desarrollador que revise que cada mensaje de Hellotext se muestre una sola vez, siguiendo [la guía para desarrolladores]({% link _developers/setup-push-with-hellotext-js.md %}). + +No elimines otros servicios de la tienda ni sobrescribas el worker de la plataforma para investigar duplicados. + +## 5. Al hacer clic se abre la página equivocada + +Anota el destino esperado y la URL que se abrió. Comprueba si ocurre lo mismo al hacer clic en la notificación y, cuando estén disponibles, en sus botones de acción. + +Para una implementación personalizada, pide a tu desarrollador que revise el destino de la notificación y el código que procesa el clic. Para una tienda integrada, envía el ejemplo a Soporte. Mostrar un botón de acción personalizado no le asigna automáticamente un destino distinto. + +## Cuándo contactar a Soporte + +Incluye: + +- Tu negocio de Hellotext y la URL de la tienda publicada. +- Si usas Shopify, VTEX o una instalación personalizada. +- El navegador, sistema operativo y dispositivo de la prueba. +- La hora aproximada y la zona horaria. +- Si la suscripción terminó y si llegó alguna notificación. +- El aviso exacto, una captura o el destino inesperado. +- Cualquier actualización reciente de la integración, cambio de dominio o borrado de datos del navegador. + +Consulta [Contacta a Soporte de Hellotext]({% link _troubleshooting-deliverability/contact-hellotext-support.md %}) para ver las opciones de contacto. + +## Guías relacionadas + +- [Configura las notificaciones push]({% link _integrations/setup-push-notifications.md %}) +- [Configura Push con Hellotext.js]({% link _developers/setup-push-with-hellotext-js.md %}) +- [Notificaciones del navegador para Inbox]({% link _team/inbox-browser-notifications.md %}) diff --git a/_i18n/es/troubleshooting-deliverability/troubleshooting-overview.md b/_i18n/es/troubleshooting-deliverability/troubleshooting-overview.md index 40e97b91..3b975056 100644 --- a/_i18n/es/troubleshooting-deliverability/troubleshooting-overview.md +++ b/_i18n/es/troubleshooting-deliverability/troubleshooting-overview.md @@ -29,6 +29,8 @@ Si el problema es una plantilla de WhatsApp en revisión, rechazada, marcada o p Para contexto de configuración de canales, sigue leyendo: [Resumen de canales de mensajería]({% link _numbers/messaging-overview.md %}). +Si una notificación push no llega, aparece dos veces o no muestra una imagen o sus botones, sigue [Soluciona problemas con las notificaciones push]({% link _troubleshooting-deliverability/troubleshoot-push-notifications.md %}). + ## Campañas Si el resultado de una campaña parece menor a lo esperado, revisa audiencia, canal, contenido del mensaje, links, timing y métricas del reporte antes de comparar resultados. diff --git a/_integrations/setup-push-notifications.md b/_integrations/setup-push-notifications.md new file mode 100644 index 00000000..492af51b --- /dev/null +++ b/_integrations/setup-push-notifications.md @@ -0,0 +1,20 @@ +--- +navigation_group: catalog_channels +languages: ["en", "es"] + +en: + title: Set up Push notifications + description: Set up website Push notifications with automatic Shopify or VTEX installation, or connect a custom storefront. +es: + title: Configura las notificaciones push + description: Configura notificaciones push para tu sitio con instalación automática en Shopify o VTEX, o conecta una tienda personalizada. + +permalink: setup-push-notifications +permalink_es: configurar-notificaciones-push + +layout: guide +topic: integrations +popular: false +--- + +{% translate_file integrations/setup-push-notifications.md %} diff --git a/_troubleshooting-deliverability/troubleshoot-push-notifications.md b/_troubleshooting-deliverability/troubleshoot-push-notifications.md new file mode 100644 index 00000000..4de6f4eb --- /dev/null +++ b/_troubleshooting-deliverability/troubleshoot-push-notifications.md @@ -0,0 +1,19 @@ +--- +languages: ["en", "es"] + +en: + title: Troubleshoot Push notifications + description: Resolve missing or duplicate Push notifications, check browser settings, and understand why images or buttons may look different across devices. +es: + title: Soluciona problemas con las notificaciones push + description: Resuelve notificaciones push que no llegan o aparecen duplicadas, revisa la configuración del navegador y entiende las diferencias de imágenes y botones entre dispositivos. + +permalink: troubleshoot-push-notifications +permalink_es: solucionar-notificaciones-push + +layout: guide +topic: troubleshooting-deliverability +popular: false +--- + +{% translate_file troubleshooting-deliverability/troubleshoot-push-notifications.md %}