Note: The terms popup and lightbox refer to the same element. While the editor and dashboard now refer to it as a popup, the API methods continue to use the term lightbox for backward compatibility. The documentation uses both terms accordingly.
In this article we demonstrate how to create a popup that appears the first time a visitor visits your site. We use a popup to create the experience and we use the wix-storage-frontend API to determine if the current visitor has already seen the popup.
We begin by adding a popup to the site. When you add a popup, it appears in the Popups section of your site pages.
We don't want the popup to show for site visitors unless we specifically open it using code. To make sure the popup doesn't open automatically, select the popup and click the Set Triggers button. Set the popup so that it doesn't automatically display on pages.
While the popup is still selected, click Set Triggers to set the Popup Settings. Here you can give your popup a meaningful name. In this example, we name our popup Announcement. The name will be used later in the code to open the popup using the Lightbox API.
Now you can design the popup to fit your needs. You can add, delete, and modify any of the elements that are contained in the popup. You can also change the layout and design of the popup.
The code works using the following model. Each time a visitor visits your site we check the visitor's browser storage for a flag that we set the first time a visitor visits your site. If we don't find the flag, we know this is the visitor's first time visiting the site. So we show the popup and set the flag for the next time the visitor visits the site. If we find the flag, we know the visitor has visited the site already and we don't show the popup.
The following code is added to the Global Code section of the Code sidebar (Wix Studio), or to the masterPage.js file located in the Page Code section of the Code sidebar (Wix Editor). Because the code is shared across all of your pages, it doesn't make a difference which page you are viewing when you add the code.
In this example we use the wix-storage-frontend API to store a value that tells us whether a visitor has seen the popup already. The wix-storage-frontend API uses the storage of a visitor's browser. We also use the wix-window-frontend API to open the popup.
So our importing code looks like this:
In the onReady() event handler, we check to see if the firstTimePopupShown key exists in the user's browser storage. The name of the key we check and set doesn't really matter. We just need to be consistent and make sure we check the same key that we set.
If the key doesn't exist, we open the popup using the popup's name. We also set a value for the firstTimePopupShown key so the key will be found the next time the user visits any of the site's pages.
So our onReady code looks like this:
Note: If you've named your popup anything other than Announcement, you need to edit the code above to reflect your popup's name.
In this example, we've created a popup that appears the first time a visitor visits any page in your site during a single browsing session. With some minor adjustments, you can customize the example to behave in a different manner as described below.
In this example, we used session storage to hold the flag that tells us if a visitor has seen the popup already. Session storage persists as long as the visitor's web session is active. The session ends when the visitor closes the browser tab or window. That means, using session storage, we show the popup the first time the visitor views the site for each individual session. If the visitor closes the browser tab and then visits the site again in a different tab, the popup will be shown again.
If you want to show the popup only once, regardless of whether a visitor is in the same browser tab or a new one, you can use local storage. Local storage never expires, even if a visitor closes your page. That means, using local storage, we show the popup the first time a visitor views the site. If a visitor closes the browser tab and then visits the site again in a different tab, the popup will not be shown again.
To change the code above so that it uses local storage instead of session storage, change all the instances of session to local.
That means the code should look like this:
In this example, we placed our code in the Global Code section of the Code sidebar (Wix Studio), or the masterPage.js file in the Page code section of the Code sidebar (Wix Editor). Code in masterPage.js runs on all the pages in a site. That means the popup will appear on the first page a visitor visits, regardless of which page it is.
If you want the popup to appear the first time a visitor visits a specific page, instead of any page on a site, move the code above into the page code for the page you want the popup to appear on.
The following APIs are used in the code in this article. To learn more, see the API Reference.