Deep Linking for iframe Page Extensions

A page extension 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.

AJAX rendering

For AJAX apps, deep linking enables your app to update the content of your iframe without refreshing the whole iframe. Your Page extension changes its state using JavaScript and AJAX methods. After the Page extension 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 won't 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 extension, 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 extension 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 extension to render different pages depending on the App-state path of your iframe.

A page extension supports deep linking using this flow:

1. Render links in your page extension 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 extension on a published website, Wix will pass the section-url as the URL of the page extension 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 extension, 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 extension at the intended internal page state.

Example

Assume that there's a Wix website with the domain www.domain.com, which has a page extension 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.)

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: