Page

Overview

A Page component is added to the website as a whole page. It appears in the main menu and acts just like any other page in the user’s website. It can contain internal pages, each with its own URL, as well as separate content for SEO.

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 Page component only once to their website. If needed, you can allow users to add the component a few times – here’s how.
  • Users can adjust the size of a Page component.
  • A Page component is added and customized by the Wix user, but is used by the site visitors.
  • Deleting the Page will revoke the app permission.
Architecture

A Page consists of two parts:

  • The Page iframe: The Page’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: The App Settings iframe allows users to register, customize, and configure the Page 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 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 Page 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 your 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.
Supporting Multiple Pages

Users can only add a Page app once from the App Market. If it makes sense for users to add the Page component more than once, you can allow them to add it again from your App Settings panel. For example, an eCommerce app may want to allow users to set up a few stores on their site.

How to support multiple page components in a site:

  1. Set up your app to allow this option:
    1. In the Dev Center, go to your app’s page and click Edit App.
    2. In the Register Your App tab, go to the App Components section and click Edit next to your page component.
    3. Under Page Endpoint Content, select Allow adding this page multiple times.
  2. Allow users to add your Page component again – use the addComponent method in your App Settings panel.
  3. To distinguish between the page components, use the compId parameter – this parameter is a unique string that identifies the component, specified in the endpoint URL.  
  4. Link each page component to its own settings – this allows users to customize each page differently, so that a change to the settings in one component won’t affect the other page components in the site:
    Use the getOrigCompId method to identify the page component that opened the App Settings panel. The method returns the compId of the page, 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.
Page Size

Follow our UI/UX guidelines for your page component’s size.

  • Width: The default width of the page component is 980px, just like every other page in the site. When we call your widget endpoint, we’ll include the page’s width in the endpoint URL.
  • Height: You’ll need to adjust the height according to the content on the page. Use the setHeight SDK method and don’t add scroll bars.
Deep Linking

A Page component supports deep linking for its internal pages. There are two supported forms of deep linking you can use: server-side rendering and AJAX rendering. You can also combine the two methods.

Note: The section-url parameter referenced in this document refers to the Page iframe URL.

AJAX Rendering

For AJAX apps, deep linking enables your app to update the content of your iframe without refreshing the whole iframe.

Your Page component changes its state using JavaScript and AJAX methods. After the Page component changes its state, it notifies the host website using the Wix.pushState() JavaScript method. This call will not reload your iframe. Wix will update the top window App-state part of the page URL, allowing it to be shared or copied and pasted to other locations.

Example: 
If the browser is showing this URL: http://site.domain.com/page-title/App-state-1
when you call the method: pushState(“App-state-2”)
the browser URL will change to http://site.domain.com/page-title/App-state-2,
but your Page iframe will not reload.

When a user shares or copies and pastes a link, and there’s a resultant request to render a page with a deep-linked URL state of your Page component, Wix will call your Page with the internal state as part of the iframe’s URL in the App-state path variable. You should load your Page component at the intended internal page state.

Example:
When a user clicks on a link with a URL such as:
http://site.domain.com/page-title/App-state
Wix will reload the Page iframe using the URL:
http://your-section-endpoint-url/App-state?rest-of-the-parameters

Server-Side Rendering

Deep linking for server-side apps enables your Page component to render different pages depending on the App-state path of your iframe.

A Page component supports deep linking using this flow:

  1. Render links in your Page component using the section-url and target parameters (both parameters are passed to your app as part of the Page iframe URL). section-url should be the base URL for your internal pages, and the target parameter should be used as the target attribute of anchor tags.
  2. When viewing a Page component on a published website, Wix will pass the section-url as the URL of the Page component website page, and the target as _top.
  3. When a user clicks on such a link, the top window URL changes to the new URL. Full-page reload will not occur. The new URL can be shared or copied and pasted to other locations.
  4. Wix will catch the history-changed event and will update the Page iframe URL, setting the App-state path parameter to the value “Appended by the App” to the section-url parameter.
  5. When a user shares or copies and pastes a link, and there’s a resultant request to render a page with a deep-linked URL state of your Page component, Wix will call your Page with the internal state as part of the iframe’s URL in the App-state path variable. You should load your Page component at the intended internal page state.

Example
Assume that there is a Wix website with the domain www.domain.com, which has a Page component on the page www.domain.com/page-title. Also assume that the Page endpoint is www.App.com.

  1. The following URL will open the Page iframe:

The section-url parameter will be URL encoded. This example is not encoded for readability purposes.

2. When you render a link to an internal page, such as my-internal-page, you should render:

3. When a user clicks on this link, the browser top window URL changes:

4. Wix catches the change in the top browser window URL and updates the Page iframe URL:

Using this flow, your Page component will reload in the iframe with the new URL.
SEO

Page apps must be fully optimized 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.

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 – excluding links to your app’s internal pages. (This ensures that users don’t see your app’s iframe URL as a referrer in Google Analytics.)

  • Manage internal pages in your app the right way:
    1. Use deep linking to link to internal pages.
    2. Return a 404 error for deleted internal pages.
    3. Set a title and description for internal pages using the setPageMetaData SDK method. These values must match what’s in your SEO endpoint.
      • Title – insert the name of the internal page into the page title. For example, the page name in an eCommerce app would be the name of the product, e.g., ‘Green Hoodie’.
      • Description – we recommend using the first 160 characters from the page content, or allowing users to customize the description.
  • Use <h1> only for internal pages. For the app’s main page, don’t use <h1>. Use <h2>, <h3>, and so on, according to your app’s hierarchy.

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:

  • For your app’s main page, only include the <body> tag. Include visible content only – headings, lists, images, etc.
    Don’t include:

    • <title> or <meta> tags in the <head> element. Leave this data for the user to define.
    • <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.
  • Link to your app’s internal pages. Deep link to internal pages, and use absolute, schemeless links. For example:

  • For internal pages, include both the <head> and <body>. Unlike the app’s main page, you should include <meta> tags in the <head> element for internal pages:
    1. Add the title and description you already set in the app via the setPageMetaData SDK method.
    2. Add Open Graph tags for social media (title, type, URL and image).

  • 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

Main page component:

Internal page:

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 Page 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?