Developer Support
Guide to Widget Components
10 min read
·
Last updated on Feb 14, 2023
Important:
Widget iframe components aren't available for all users right now. If you'd like to request access you can submit a proposal.
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.
Important:
Your widget must load the SDK in the component and App Settings endpoints, and both must support HTTPS.
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:
- 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.
- 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:
- In the App Settings panel, use triggerSettingsUpdatedEvent to send an update event to the component.
- In the component itself, use addEventListener and listen for the SETTINGS_UPDATED event.
- 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:
- Use the compId parameter to distinguish between the widgets: this is a unique string that identifies the component, specified in the endpoint URL.
- Make sure copied widgets have the same settings as the original widget: use the originCompId query parameter to retrieve the original widget’s settings.
- 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 in the Dev Center, 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18//App HTML page includes JS <html> <body> <h2>HEADING</h2> <p id="divid"></p> <script> var car_name = ["Mazda", "Volvo", "Nissan", "Ford", "Skoda", "Audi"]; var string = ""; var i; for (i = 0; i < car_name.length; i++) { string += car_name[i] + "<br>"; } document.getElementById("divid").innerHTML = string; </script> </body> </html>
SEO endpoint
1 2 3 4 5 6 7 8 9 10 11 12//Static HTML code that displays the visible content <body> <h2>HEADING</h2> <p id="divid"> Mazda<br> Volvo<br> Nissan<br> Ford<br> Skoda<br> Audi<br> </p> </body>
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
URL Requirements
- HTTPS: Wix uses HTTPS to maintain high security standards. All URLs, whether they are OAuth or iframe need to use HTTPS throughout the development process, otherwise they won't load on the Wix system.
- Localhost or ngrok: you can use both of these during development, but you'll need to change the URL before you submit your app for review. As localhost and ngrok run on your local machine, our team won't be able to check them when reviewing your app.
Widget request URL template:
1[endpoint]?instance=[signed-instance-data]&width=[width]&cacheKiller=[cacheKiller]&compId=[compId]&viewMode=[viewMode]&locale=[locale]&originCompId[originCompId]&deviceType=[device]
Name | Value | Comments |
|---|---|---|
endpoint | The Widget URL as supplied during the app registration in the Dev Center | |
app-state | The inner state of the widget component | The app-state part of the URL may include a query string, but must not include a # |
instance | The signed instance | |
section-url | The base URL of the widget component | |
target | Attribute that must be added to all href anchors within the widget iframe | |
width | The width of the iframe in pixels | Note that the frame height will auto-adjust depending on the frame content |
cacheKiller | The cacheKiller is there to ensure no caching of the iframe content by the host browser | |
compId | The ID of the component | While the instanceId remain constant within the scope of the site, each iframe will have a unique and persistent compId |
viewMode | Current view mode | "editor" or "site". "editor" is valid inside the Wix editor, while "site" is available only in a published website |
locale | Current locale value | |
deviceType | Current device type | "desktop" or "mobile" |
App Settings request URL template
1[endpoint]?instance=[signed-instance-data]&width=[width]&compId=tpaSettings&origCompId=[origCompId]&locale=[locale]
Name | Value | Comments |
|---|---|---|
endpoint | The App Settings URL as supplied during the app registration in the Dev Center | |
instance | The signed instance | |
width | The width of the iframe in pixels | |
compId | The compId value for the app settings is always tpaSettings | |
origCompId | The ID of the component which associated with the App Settings | The origCompId identifies the current component that the user is editing |
locale | Current locale value |
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.
Was this article helpful?
