Guide to Widget Extensions (iframe)

A widget component is a small element on a user’s site. Site visitors can see and interact with widget components.

In this article we'll tell you about all the things to keep in mind when developing a widget component to help you deliver the best possible experience for users.

Things to know before getting started

Here's some useful things to know about a widget component:

• Users can add your widget more than once to their website.
• Users can adjust the size of a widget component.
• If it makes sense for your app, you can show the widget on all pages and pin it to a specific location in the browser.
• A widget component is added and customized by the Wix user, but is used by the site visitors.
• Deleting the app will revoke the app permission only if there are no other components of the same app in the user’s website.

Architecture

A widget component is made up of two parts – the widget iframe and an App Settings panel. These components talk to our systems through our iframe SDK. 

• The widget iframe: the widget’s content is provided as an iframe embedded in a Wix website by the user, and is displayed in both the Wix Editor and the published website.
• The App Settings iframe: this allows users to register, customize, and configure the widget component for their website. The App Settings iframe is embedded in the Wix Editor and is used only by the user.

Link the app to a site

When a user adds your app, we’ll generate a unique ID for your app for this specific site – this is the App Instance ID. You should use this to link your app to this site. 

This ID is sent to you as part of the App Instance query parameter, which is a signed parameter that allows you to identify the website and the Wix user, and verify that the calling party is indeed Wix. 

All of your app’s endpoints will have the same App Instance ID, so each request sent to the widget endpoint and to the App Settings endpoint includes the same App Instance ID in the iframe URL.

App Settings panel

To build a widget component, you'll need to create an App Settings panel. Here's some things you should do to create an optimal App Settings experience:

Update the app with the user's changes

When users change a setting in your app, update the app right away in the Wix Editor – but don’t change the app on the live site until the user publishes the site. Here’s how:

1. Store two sets of data: store both the data that’s visible in the Wix Editor and App Settings panel, and the data in the live site.
2. Update the app in the Wix Editor immediately: show the app with these latest changes in the Wix Editor (including the App Settings panel). Read below on how to do this.

• If the user doesn’t save these changes, go back to the previous settings. Listen for the SITE_SAVED event in the addEventListener method. If the user doesn’t save the site, discard the latest changes and go back to the previous settings the next time we call your app endpoint.
• Wait for the user to publish the site before updating the app in the live site. Listen for the SITE_PUBLISHED event in the addEventListener method. When SITE_PUBLISHED is issued, update the app in the live site.

Update your app's settings

When users change your app’s settings, here’s how to update your app right away in the Wix Editor:

1. Detect changes that the user makes in the App Settings panel: Use the onChange or onClick function.

2. Update your database/backend server immediately.

3. Show the changes in your app: for a better user experience, don’t refresh your app – here’s what to do instead:

1. In the App Settings panel, use triggerSettingsUpdatedEvent to send an update event to the component.
2. In the component itself, use addEventListener and listen for the SETTINGS_UPDATED event.
3. Update the app with the new settings.

Support multiple copies of the widget

Users can copy the widget component as many times as they want on their website, and they can customize each widget differently. Here’s what you should do:

1. Use the compId parameter to distinguish between the widgets: this is a unique string that identifies the component, specified in the endpoint URL.
2. Make sure copied widgets have the same settings as the original widget: use the originCompId query parameter to retrieve the original widget’s settings.
3. Link each widget to its own settings: this makes sure when a user changes the settings of one widget, it doesn’t affect other copies of the widget in the site. Use the getOrigCompId method to identify the widget that opened the App Settings panel. The method returns the compId of the widget, so you can open the right settings panel.

Widget size

You’ll set an initial size for your app, but users can resize your app in the Wix Editor. Follow our UI/UX guidelines – we’ll show you how to decide your app’s initial size, and how to create the right user experience when users resize your app in the Wix Editor.

SEO

If your widget has text or other content that’s meaningful for your users’ SEO, develop a dedicated SEO endpoint for your widget component.

This will enhance your users’ SEO by allowing Wix to dynamically adjust app content displayed for search engines. Your SEO endpoint will be visible to search engine crawlers only.

Which apps need an SEO endpoint

You should only develop an SEO endpoint if your app’s content is meaningful for SEO. When we render a site’s SEO view, we use this endpoint to dynamically embed your app’s content into the SEO view.

Examples of apps that should have an SEO endpoint:

• FAQ widgets
• News ticker widgets
• Testimonial widgets

Examples of apps that shouldn’t have SEO endpoints:

• Chat widgets
• Form builders
• Social media button widgets

Not sure if your widget should have an SEO endpoint? Get in touch.

Develop your SEO endpoint

Your SEO endpoint should be a stripped down version of your app – it should have just the static HTML content that’s visible on the user’s site, and none of the Javascript or dynamic functionality.

Here are some important things to keep in mind when creating your SEO endpoint:

• From the widget’s HTML document, extract an HTML snippet of the <body> tag: include all HTML elements inside the body – like headings, lists, paragraphs, images, etc. 
• Don’t include <title> or <meta> tags in the <head> element: leave this data for the user to define.
• Just like the component itself, don’t add an <h1> element to the SEO endpoint: this can cause issues for users because they may end up with more than one h1 on the page.
• Don't include <script> tags or other dynamic/interactive content.
• Don’t display content in the SEO endpoint that isn’t visible in the app: search engines consider this to be bad practice, since it’s usually done to manipulate SEO ranking. Search engines detect this, and may remove suspect pages or the entire site from their index. E.g., if your app doesn’t include marketing text like “powered by MyCompany” – then don’t include it in the SEO version.
• Make sure your endpoint is up, accessible, up-to-date, and fast:
  • Define a publicly accessible URL (don't use a localhost hostname).
  • Keep the error rate low – otherwise, we’ll turn off your SEO endpoint.
  • Update the content dynamically so that it reflects the current content in the app.
  • Load the endpoint within 4 seconds.

SEO endpoint examples

App HTML

SEO endpoint

Check your app's SEO view

You can see what your app looks like to a search engine crawler – whether or not you developed a dedicated SEO endpoint by accessing the site / page with a Googlebot.

Here’s how to do it in Google Chrome:

• Right click anywhere on your page and click Inspect.
• Click Menu in the top right > More tools > Network conditions
• Under 'User agent' uncheck 'Use browser default'
• Select a Googlebot from the dropdown or paste one into the Custom field

For browsers like Edge, Firefox and Safari, check out this article.

Mobile endpoint

Create a mobile endpoint for your app so that it works well on mobile devices.  This endpoint should have the same functionality as your web app – except for these differences:

• The mobile endpoint should be created according to our mobile UI/UX guidelines.
• The app width will be automatically set to 280px. The height is unlimited, and you will be able to modify it using the setHeight method in our JavaScript SDK. However, we recommend keeping the mobile view short, and providing a link or pagination to additional data.

Endpoint URLs

Widget request URL template:

App Settings request URL template

Security and privacy

It's really important to make sure your app is secure and protects the user's privacy. We've got a dedicated guide to help you with this.