Aviso: Não existe documentação legada disponível para este item, pelo que está a ver a documentação atual.
iOS users can only receive web push notifications when a website has been added to their home screen and opened as a web app. Visitors who browse your site directly in Safari or any other browser on their iPhone or iPad will not see a push notification opt-in prompt and cannot subscribe.
The Add to Home Screen widget solves this. When an iOS visitor lands on your site in a browser, PushEngage detects that the site is not running in home screen mode and shows a popup that walks them through the process: tap the Share button, choose Add to Home Screen, then open the site from the icon on their home screen. Once they do, the standard push notification opt-in prompt appears and they can subscribe like any other visitor.
This is a feature PushEngage added based on direct customer requests, and enabling it is the most important step you can take to grow your iOS push subscriber base.
Requirements
Before enabling the widget, make sure your setup meets the following:
- iOS 16.4 or later. The widget only shows on iOS 16.4 and above. Visitors on older iOS versions will not see it, and web push is not supported on those versions regardless.
- Web app manifest. For iOS versions below 26, your site must include a web app manifest linked in the page
<head>(<link rel="manifest" href="/manifest.json">). Without it, iOS will not display the correct icon and site name when the visitor adds it to their home screen. On iOS 26 and above, a manifest is recommended but not required.
If you are using a WordPress plugin or a hosted website builder, your theme may already include a manifest. You can confirm by viewing your page source and searching for rel="manifest".
Finding the Widget
In your PushEngage dashboard, go to Design » Widgets. Scroll to the bottom of the page to find the Add to Home Screen section.
Click the toggle to enable the widget. Once enabled, it will automatically appear to qualifying iOS visitors who open your site in a browser rather than from a home screen icon.
To customize the text and appearance, click Edit Popup.
Editing the Widget
The Edit Add to Home Screen page is divided into four sections: Basic Details, UI Customization, Display Behavior, and URL Targeting. A live preview panel on the right updates as you make changes so you can see exactly how the popup will look before saving.
Basic Details
This section controls the text content of the popup.
Título
The headline of the popup. The default is “Add Us to Your Home Screen.” The character limit is 124. Keep this short and direct — one clear instruction works better than multiple ideas.
The character limit is 305. The {{share_icon}} placeholder renders as the iOS Share button icon inline within the instruction text, making it easy for visitors to identify the correct button without any guesswork. You can place {{share_icon}} anywhere in your instruction copy and PushEngage will substitute the icon image when the popup renders.
Button Text
The label on the confirmation button. The default is “I’ve Added It.” The character limit is 47. This is what visitors tap after completing the steps — tapping it tells PushEngage they have added the site to their home screen and dismisses the popup.
UI Customization
Five color settings control the appearance of the popup:
- Background Color : the background of the popup card (default: white,
#ffffff) - Text Color : the color of the title and instruction text (default: near-black,
#0d0d0d) - Button Color : the background of the confirm button (default: PushEngage purple,
#4642E5) - Button Text Color : the text color on the confirm button (default: white,
#ffffff) - Close Button Color : the color of the X button in the top-right corner of the card (default: near-black,
#0d0d0d)
Click any color swatch to open the color picker and enter a hex value or select a color. The live preview updates in real time.
Display Behavior
Show widget on controls how often the popup appears to the same visitor. The default is “Once per session,” meaning the popup shows once per browser session and may reappear on the next visit if the visitor has not yet added the site to their home screen.
Trigger Delay (seconds) sets how many seconds to wait after the page loads before showing the popup. The default is 0. Adding a short delay of 3 to 5 seconds can reduce friction for visitors who just arrived on the page.
URL Targeting
By default, the widget appears on every page of your site. You can use URL targeting to restrict it to specific pages or suppress it on others.
Include URLs : when enabled, the popup shows only on pages whose URL matches the rules you define. This is useful if you want the prompt to appear only on high-intent pages such as a product page, a landing page, or the homepage.
Exclude URLs : when enabled, the popup is suppressed on pages whose URL matches your rules. Use this to prevent the popup from appearing on pages where it would be disruptive, such as checkout or account management pages.
Toggle either option on to reveal the URL input field, select a matching rule (Contains, Starts With, or Exact), enter part of a URL, and click Add URL.
Once all settings are configured, click Save Changes at the top of the page.
How the Widget Works for iOS Visitors
When a qualifying iOS visitor opens your site in a browser and the site is not yet running in home screen mode, the widget popup appears after the configured delay. The visitor reads the instruction, taps the Share button on their browser, selects Add to Home Screen, and adds the site icon to their home screen.
The next time the visitor opens your site by tapping the home screen icon, the site loads as a web app. PushEngage detects this and shows the standard push notification opt-in prompt. The visitor can then tap Allow and subscribe.
Tapping the confirm button (“I’ve Added It”) on the widget dismisses the popup but does not subscribe the visitor. The subscription happens when they open the site from their home screen and respond to the opt-in prompt.
Perguntas Frequentes
Will the widget show to Android or desktop visitors? No. The Add to Home Screen widget is shown only to iOS users on iOS 16.4 and above who are visiting the site in a browser rather than from a home screen icon. Android and desktop visitors are not affected.
What if a visitor taps the confirm button without actually adding the site to their home screen? The button dismisses the popup and PushEngage records the interaction as complete. Depending on your “Show widget on” setting, the popup may reappear in a future session if the visitor returns via a browser and still has not added the site to their home screen.
Does the widget work on all browsers on iPhone? Yes. On iOS, all browsers including Safari, Chrome, Firefox, and Edge use the same WebKit engine and share the same limitation around web push. The widget appears regardless of which browser the visitor is using, as long as they are on iOS 16.4 or later and the site is not open in home screen mode.
Why is a web app manifest required for iOS below 26? When a user adds a site to their home screen, iOS reads the web app manifest to determine the name to display under the icon and which icon image to use. Without a manifest, iOS falls back to the page title and a screenshot, which may look inconsistent or confusing. On iOS 26 and above, this information can also be inferred from other page signals, which is why a manifest is recommended but no longer strictly required on that version.
My site already has push notifications working for other platforms. Do I need to do anything else to support iOS? The only additional steps for iOS are enabling the Add to Home Screen widget and ensuring your site includes a web app manifest. PushEngage handles notification delivery once subscribers opt in. No separate iOS-specific configuration is needed beyond what is covered in this article.
If you have questions about the Add to Home Screen widget or need help with your iOS web push setup, please feel free to contact us. Our support team will be happy to help.
