Widget

Overview

A Widget is a resizable component that can be dragged and dropped anywhere within a page. It can be added multiple times to a single website.

User experience
  • Users can see your app in the App Market and then add it to their website.
  • Users will have to grant permission for your app once they add it.
  • Users can add your Widget more than once to their website.
  • Users can adjust the size of a Widget component.
  • 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 consists of two parts:

  • The Widget iframe: The Widget’s content is provided as an iframe embedded in a Wix website by the user. It is displayed in both the Wix Editor and the published website.
  • The App Settings iframe: The App Settings iframe allows users to register, customize, and configure the Widget 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 in this specific site – the App Instance ID. Use the App Instance ID 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 in this site 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

Use the App Settings panel in our UI-lib starter template as a base to create your App Settings panel.

Updating 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 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). There are two ways to do this, depending on whether the user changed the color/font, or other values like numbers/text/booleans.
  3. 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.

Updating the Color & Font

 

For color and font settings, use our custom wix-param attribute in both the site component and in the App Settings panel.

When users change your app’s font or color, we’ll automatically update the app with these changes.   

Updating Numbers, Booleans, Text & Other Values

 

When users change your app’s settings (except the color & font), 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. Here’s what to do in the settings panel:

    • For Wix UI controls that use wix-param to save a number or boolean: listen for the STYLE_PARAMS_CHANGE event in the addEventListener method.
    • For Wix UI controls that don’t use wix-param: use the onChange or onClick function.

2. Update your database/backend server immediately. This is only relevant for UI controls that aren’t using wix-param. (If the UI control uses wix-param, the change is already saved in the Wix site – so there’s no need to update your server.)  

3. Show the changes in the app. For 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 these events:
      1. SETTINGS_UPDATED event – for UI controls that don’t use wix-param
      2. STYLE_PARAMS_CHANGE – for UI controls that use wix-param
    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. To distinguish between the widgets, use the compId parameter (a unique string that identifies the component, specified in the iframe query parameters).
  2. When a user copies the widget, make sure the copied widget has 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, so that 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.
Copy App Content in Duplicated Sites

Users can duplicate their site, which means that apps should be added to the duplicated site with their existing content and settings (not the default data).

Here’s what you should do:

  1. Check if the app is being copied from another site. When your app endpoint is called, check if the instance parameter has an originInstanceId property. If it does, this means that the app is being copied from another site. The value of originInstanceId is the instanceId of the app in the original site.
  2. Copy the content and settings of each Site component. Get the correct settings of the original app using its instanceId (the originInstanceId property) together with the compId query parameter (a unique string that identifies the component, specified in the endpoint URL). The compId has the same value in both the duplicated and original sites.
Note:
In some cases, there may be content that shouldn’t be copied over between sites. Not sure if something should be copied? Talk to your account manager.
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

Does your widget have text or other content that’s meaningful for SEO? Optimize your app for search engine crawlers, to improve SEO for your users.

There are two main steps to optimize your app:

  1. Optimize the app itself in the live site. Now that search engines like Google can crawl JavaScript, make sure the app itself is fully optimized for SEO.
  2. Develop an SEO endpoint. Since not all search engines crawl JavaScript, we’ll call your SEO endpoint when a search engine requests the SEO version of your app using the  _escaped_fragment_ parameter.

Here are a few examples of apps that should be optimized for search engines:

  • FAQ widgets
  • News ticker widgets
  • Testimonial widgets

If there’s no content in your widget that’s meaningful for SEO, don’t develop an SEO endpoint – we’ll render your widget as an iframe. For example, apps like chat widgets, form builders, and social media buttons don’t need an SEO endpoint.

Note:
Not sure if your widget should have an SEO endpoint? Just ask!

Optimize the App in the Live Site

Follow these do’s and don’ts to optimize your app for search engines.

Do:

  • Add alt text and src to images. That way, these attributes are easily readable in the DOM.

  • Use absolute, schemeless links and add the href attribute. This is the full URL without the protocol. For example:

  • Add rel=”noreferrer” for links to other site pages. Have links that go to other pages in the user’s site, like the homepage? Set the rel attribute value to “noreferrer” for links that go to these pages. (This ensures that users don’t see your app’s iframe URL as a referrer in Google Analytics.)

Don’t:

To ensure your app is crawled and indexed properly, here’s a list of what you should not do:

  • Don’t add a noindex meta tag. Google can crawl JavaScript, so don’t block search engines from crawling JavaScript in your app’s iframe.
  • In the robots.txt file, don’t block anything that’s needed for the page to load. Contact us if you think something should be blocked.

Develop an SEO Endpoint

Create a separate HTML file for the SEO endpoint. Your SEO endpoint should be an “HTML snapshot” – a  stripped down version of your app that has all the static HTML content visible on the user’s site, and none of the Javascript or dynamic functionality.

Here are the “do’s and don’ts” of creating your SEO endpoint:

  • From the widget’s HTML document, extract an HTML snippet of the <body> tag. Include visible content only – headings, lists, images, etc.
    Don’t include:

    1. <title> or <meta> tags in the <head> element. Leave this data for the user to define.
    2. <script> tags or other dynamic/interactive content.
  • Make sure the elements match the app itself. For example, the heading structure, alt text for images, etc.
  • 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 other “Black Hat SEO” strategies), and may remove suspect pages or the entire site from their index.

    For example, if your app doesn’t include marketing text like “powered by MyCompany” – then don’t include it in the SEO version.
  • Support SEO in other languages. After you render the HTML for your SEO view, include an additional header in your HTTP response: Content-Type: “text/html;charset=UTF-8”.
  • Make sure your endpoint is up, publicly 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.

Example of an SEO Endpoint

How to see 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. Here’s how:

Concatenate ?_escaped_fragment_= to the site URL.

Note: You can also just use a Chrome extension like Ajax crawl urls – it does the work for you.
Mobile Endpoint

Not using media queries to make your app responsive? Then you must have a dedicated mobile endpoint.

Here’s how:

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:

  • Design for mobile. Follow our mobile design guidelines.
  • Limit the width of the app to 320px, and the content to 280px. The height is unlimited, and you can 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.
Important:
Don’t create a new App Settings for the mobile view. When developing the mobile endpoint, make sure that the mobile settings for your app are exactly the same as your desktop settings.

When a Wix user customizes any of your App Settings in the Editor, these changes should affect both the desktop and mobile versions of your app in exactly the same way.

Iframe Query Parameters

Query parameters for the Widget iframe:

NameValueComments

Query parameters for the App Settings iframe:

NameValueComments

Was this page helpful?

What can we do to improve it?

What did you like about it?