Search.../

SDK

Using the SDK

Our JavaScript SDK exposes methods that enable the app to communicate with the Wix platform – the Editor, Dashboard, live site, and preview.

Include the following script tag in your HTML document:

<script type="text/JavaScript" src="//static.parastorage.com/services/js-sdk/1.425.0/js/wix.min.js"></script>
HTML | Copy Code

Once included, your window object will contain a new global Object named Wix.

SDK Version

We release new versions of our JavaScript SDK regularly. Update your app to use the latest version by replacing the version number in the script tag.

Note the following:

  • We document the latest SDK version for each method. If a method is updated, we update its SDK version accordingly. For example: if a method is available since SDK 1.45.0 and updated in SDK 1.95, our documentation lists SDK 1.95 as the version. Update your app to the latest version so that you can use all parameters in the method.
  • When calling a method from the Editor, check the Editor version. Starting from SDK 1.45.0, methods are not supported in the old Editor. When using more recent methods in the Editor, provide a fallback option for users in the old Editor. Keep reading to learn more.

Editor Version

In 2015, we launched a new and improved version of the Wix Editor. We are gradually moving users over to the new Editor, so some users are still using the old Editor.

All methods that are available since SDK version 1.45.0 are not supported in the old Editor. To use these methods, you’ll need to detect the user’s Editor version and add a fallback option for the old Editor.

Here’s how:

  1. Call the Wix.Features.isSupported function and specify the feature you want to use. If the user is in the new Editor, you receive true via callback and you then need to call the relevant function.
  2. Make sure to include a fallback behavior for your app in case the user is in the old Editor (like an alternate function) – otherwise, an error will occur.

Structure

The Wix global object can be used in all components’ endpoints – Widget, Page, Fixed Position, Dashboard, Worker, and App Settings – as well as its controls – Modal and Popup. However, some of its functions make sense only in certain endpoints.

The most obvious distinction is the App Settings endpoint.

The App Settings endpoint is different since it is the only endpoint that resides in the Editor while the others reside in the user’s website or the My sites dashboard. For that reason we created a namespace Wix.Settings that holds all the functions that are valid in the App Settings endpoint.

Another special namespace is the Wix.Utils. It provides utility functions that can be called by all endpoints (except worker).

Note:
Although Wix.Utils is valid for all endpoints (except worker), if the called function doesn’t have a meaningful value to return, it returns null. For example, when Wix.Utils.getOrigCompId() is used in the App Settings endpoint, the function returns the component ID that called it – but for other endpoints, it returns null. {note}

Async Methods

If you see a method in our SDK has a callback function, this means that the method is asynchronous. The “return” value is passed as an argument in the callback function.

Was this helpful?

Wix

addEventListener

Allows the site component to listen to events that happen in the editor or website.

SDK Version: SDK 1.11.0 - 1.96.0+
Editor Version: New Editor, Old Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page

Important:
Check the specific SDK version for each event. Events that are available in SDK versions higher than 1.45.0 are not supported in the old Editor. Learn more

Make sure to register event listeners when the document loads, since previous listeners might be invalidated when we load your app.

Syntax:

addEventListener(eventName, callback)
JavaScript | Copy Code

Parameters:

NameTypeDescription
eventName (required)Wix.EventsUnique event identifier, listed in the table below
callback (required)FunctionA callback function that is called by the SDK once an event occurs

The events that you can currently listen to are:

EventEvent DataDescription
COMPONENT_DELETED{}Issued when the user deletes a site component. Note: This event is only sent to the component that was deleted, so use the Wix.PubSub.publish method to alert other site components in your app about this event. For worker components, use Wix.Worker.PubSub.publish. Availability: Since 1.13.0
DEVICE_TYPE_CHANGED{ deviceType: 'desktop' or 'mobile'}Issued when the user switches between the desktop editor and mobile editor. Availability: Since 1.45.0
EDIT_MODE_CHANGE{editMode: 'editor' or 'preview'}Issued when a user toggles between preview and edit mode in the editor. Availability: Since 1.11.0
INSTANCE_CHANGED{instance: instanceValue}Issued when a component in your app called Wix.revalidateSession in the live site.Availability: Since 1.96.0
KEY_DOWN{charCodeundefined39}Issued when the user presses one of these keys on the keyboard:left/right arrows, esc, enter, space bar. Availability: Since 1.76.0
KEY_UP{charCodeundefined39}Issued when the user presses one of these keys on the keyboard:left/right arrows, esc, enter, space bar. Availability: Since 1.76.0
MEMBER_DETAILS_UPDATEDFor example:"attributes": { "name": "John Doe", "firstName": "John", "lastName": "Doe", "imageUrl": "https://myImage.jpg", "nickname": "Johnny "}}Issued when a member changes their personal details. Availability: Since 1.89.0
PAGE_NAVIGATION{"toPage": "Page1", "fromPage": "Page2"}Issued on any page navigation in the website. Availability: Since 1.25.0
PAGE_NAVIGATION_IN{"toPage": "Page1", "fromPage": "Page2"}Issued on any page in navigation in the website. This event is a utility event on top of the PAGE_NAVIGATION event. Availability: Since 1.25.0
PAGE_NAVIGATION_OUT{"toPage": "Page1", "fromPage": "Page2"}Issued on any page out navigation in the website. This event is a utility event on top of the PAGE_NAVIGATION event. Availability: Since 1.25.0
PUBLIC_DATA_CHANGED{ key1: value1 }Issued when app data is changed using Wix.Data.Public methods. Note that all registered components will get this event. Availability: Since 1.74.0
SCROLL{"scrollTop": 4, "scrollLeft": 0, "documentHeight": 724, "documentWidth": 1227, "x": 124, "y": 131, "height": 682, "width": 978, "left": 124.5, "bottom": 809, "right": 1102.5, "top": 127}Issued when scroll happens inside the site. The event data contains multiple details that helps the app determine its behavior considering its position in the site, the browser window dimensions, and the scrolling state: ScrollTop - site's scroll position on the y axis, scrollLeft - site's scroll position on the x axis, documentHeight - site's document height, documentWidth - site's document width, x - app offset within the site's page on the x axis, y - app offset within the site's page on the y axis, height - app height, width - app width, left - app top-left offset from the left, bottom - app top-left offset from the bottom, right - app top-left offset from the right, top - app top-left offset from the top. Availability: Since 1.25.0
SETTINGS_UPDATEDCustom jsonIssued by the App Settings endpoint when new settings are applied by the user. Availability: Since 1.17.0
SITE_METADATA_CHANGED{ title: 'example title', description: 'example description' }Issued when the page metadata (title, description) changes. Availability: Since 1.75.0
SITE_PUBLISHED{}Issued when the user publishes the website. Availability: Since 1.13.0
SITE_SAVED{}Issued when the user saves the website. Availability: Since 1.62.0
STATE_CHANGED{newState: 'state'}Issued when the website state changed. Learn more about the component's state and deep linking. Availability: Since 1.29.0
STYLE_PARAMS_CHANGE{colors: Object, numbers: Object, booleans: Object, fonts: Object}Issued when the user changed a color, font, number, or boolean value in your app’s settings panel. Availability: Since 1.22.0
THEME_CHANGE{fonts: Object, siteTextPresets: Object, siteColors: Array (30 colors of palette), style: Object}Issued when the user changed the site’s color palette. Availability: Since 1.22.0
WINDOW_PLACEMENT_CHANGED"BOTTOM_RIGHT"Issued when the user changed the position of a fixed-position widget. Availability: Since 1.18.0

Example:

$(document).ready(function() {
Wix.addEventListener(Wix.Events.EDIT_MODE_CHANGE, function(event) {
console.log("Edit mode changed to " + event.editMode);
})
});
JavaScript | Copy Code

closeWindow

Closes the modal or popup endpoint.

SDK Version: SDK 1.16.0+
Display: Live Site, Preview
Components: Modal, Popup

Syntax:

closeWindow(\[message\])
JavaScript | Copy Code

Parameters:

NameTypeDescription
messageObjectA custom message to pass to the calling endpoint’s onClose callback function

Example:

var message = {"reason": "button-clicked"};
Wix.closeWindow(message);
JavaScript | Copy Code

currentMember

Retrieves the current Site Member, if one exists.

SDK Version: SDK 1.6.0+
Display: Live Site
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

currentMember(callback)
JavaScript | Copy Code

Parameters:

NameTypeDescription
callback (required)FunctionCallback function to receive member details

Value passed to callback:
An object containing the Site Member’s details:

NameTypeDescription
nameStringMember's name
emailStringMember's email
idStringMember's ID
ownerBooleanTrue if the member is either the site owner or one of the site's contributors

Example:

Wix.currentMember(function(memberDetails) {
// save memberDetails
})
JavaScript | Copy Code

getAdsOnPage

Retrieves the width and height of Wix ads in the live site.

SDK Version: SDK 1.77.0+
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page

You can use this data to position your site component correctly, so that there’s enough space between your app and the ad.

Syntax:

getAdsOnPage(callback)
JavaScript | Copy Code

Parameters:

NameTypeDescription
callback (required)FunctionCallback function to receive the width and height of Wix ads on the page

Value passed to callback:
An object with the width and height of each Wix ad on the page, in pixels. (If there are no ads, object is empty.)

Example:

Wix.getAdsOnPage(onSuccess);
//example response
{
top: {
height: 26,
width: 155
},
bottom: {
height: 40,
width: 684
}
}
JavaScript | Copy Code

getBoundingRectAndOffsets

Retrieves information about the bounding box (a rectangle) of the current component:

  • x, y coordinates of the bounding rectangle, and its offsets relative to the top-left of the viewport
  • size of the bounding rectangle

SDK Version: SDK 1.26.0+
Editor Version: New Editor, Old Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

getBoundingRectAndOffsets(callback)
JavaScript | Copy Code

Parameters:

NameTypeDescription
callback (required)FunctionA callback function that returns the size and coordinates of the bounding rectangle and its offsets (in pixels)

Value passed to callback:
An object that contains two objects – offsets and rect:

NameTypeDescription
offsetsObjectCoordinates of the top-left point of the bounding rectangle, relative to the top-left of the viewport
offsets.xNumberLeft (x) coordinate value of the bounding rectangle
offsets.yNumberTop (y) coordinate value of the bounding rectangle
rectObjectSize of the component and its x,y coordinates, relative to the top-left of the viewport
rect.widthNumberWidth of the bounding rectangle
rect.heightNumberHeight of the bounding rectangle
rect.topNumberTop (y) coordinate value of the bounding rectangle
rect.bottomNumberBottom (y) coordinate value of the bounding rectangle
rect.leftNumberLeft (x) coordinate value of the bounding rectangle
rect.rightNumberRight (x) coordinate value of the bounding rectangle

Example:

//This example expands a fixed-position widget component
//positioned at the bottom-right of the viewport
//to 100% of the screen size
Wix.getBoundingRectAndOffsets(function(data){
var height = data.offsets.y + data.rect.height;
var width = data.offsets.x + data.rect.width;
Wix.resizeWindow(width, height);
});
JavaScript | Copy Code

getComponentInfo

Retrieves information about the current component. For example, you’ll be able to know if a widget is shown on all pages.

SDK Version: SDK 1.64.0+
Editor Version: New Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page

Syntax:

getComponentInfo(callback)
JavaScript | Copy Code

Parameters:

NameTypeDescription
callback (required)FunctionA callback function to get information about the component

Value passed to callback:
An object containing the component info:

NameTypeDescription
compIdStringThe unique ID of this component in the Wix site
pageIdStringID of the page that contains the component. Returns null if the component is a widget that’s set to show on all pages.
showOnAllPagesBooleanTrue if the user set the widget to show on all pages. False if the component is a page, or if the widget is not set to show on all pages.
tpaWidgetIdStringID of the widget component, as specified in the Dev Center. Returns null if the component is a page, or if you’re using this method in the live site.
appPageIdStringID of the page component, as specified in the Dev Center. Returns null if the component is a widget, or if you’re using this method in the live site.

Example:

Wix.getComponentInfo( function(compInfo) {
//do something with the compInfo
});
JavaScript | Copy Code

getCurrentPageAnchors

Retrieves the anchors on the current page.

SDK Version: SDK 1.62.0+
Editor Version: New Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

getCurrentPageAnchors(callback)
JavaScript | Copy Code

Note:
In the settings endpoint, use Wix.Settings.getCurrentPageAnchors instead.

Parameters:

NameTypeDescription
callback (required)FunctionCallback function to receive an array of anchors (unordered)

Value passed to callback:
An array of unordered objects. If there are no anchors on the current page, method retrieves just one default anchor – the top of the page. Each object represents an anchor on the current page, and contains the following properties:

NameTypeDescription
idStringThe anchor ID
titleStringThe anchor title

Example:

Wix.getCurrentPageAnchors(function(anchors) {
// do something with anchors
});
JavaScript | Copy Code

getCurrentPageId

Retrieves the ID of the current page.

SDK Version: SDK 1.31.0+
Editor Version: New Editor, Old Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

getCurrentPageId(callback)
JavaScript | Copy Code

Warning:
Navigating to a page using its pageId? Don’t use this method to get the pageId – use Wix.getCurrentPageNavigationInfo instead.

Parameters:

NameTypeDescription
callback (required)FunctionCallback function to receive the pageId

Value passed to callback: A string representing the pageId.

Example:

Wix.getCurrentPageId(function(pageId) {
//store the pageId
});
JavaScript | Copy Code

getCurrentPageNavigationInfo

Retrieves navigation info for the current page in the site.

SDK Version: SDK 1.91.0+
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

This method supports both regular and dynamic pages (such as pages created with Wix Code or a data-binding app).

Syntax:

getCurrentPageNavigationInfo(callback)
JavaScript | Copy Code

Parameters:

NameTypeDescription
callback (required)FunctionCallback function to receive an object with details about this page.Use this object when navigating to the page - see Wix.navigateTo.

Value passed to callback: An object with the data needed to navigate to this page. Save the object in your database and navigate to the page using Wix.navigateTo.

Warning:
Save this object in your database as is – don’t change it in any way.

//Example object for a regular page
{
"type": "PageLink",
"pageId": "c1x1t"
}
JSON | Copy Code
//Example object for a dynamic page
{
"innerRoute": "name",
"type": "DynamicPageLink",
"routerId": "routers-jaaw0rlp"
}
JSON | Copy Code

Example:

Wix.getCurrentPageNavigationInfo(function(data) {
console.log(data);
});
JavaScript | Copy Code

getSiteInfo

Retrieves information about the site where your app is installed.

SDK Version: SDK 1.3.0+
Editor Version: New Editor, Old Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal,Popup

Syntax:

getSiteInfo(callback)
JavaScript | Copy Code

Parameters:

NameTypeDescription
callback (required)FunctionCallback function to receive the site info

Value passed to callback:
Object containing the site info:

NameTypeDescription
baseUrlStringBase url of the current site, for example: http://user.wix.com/site-name http://www.domain.com
pageTitleStringThe page title that is used for SEO. This title includes both the site and page title (e.g., “My Store / Animal Shirt”).
pageTitleOnlyStringThe name of the page - without the site title (e.g., “Animal Shirt”).
referrerStringThe referrer header of the HTTP request
siteDescriptionStringThe description of the site that is used for SEO
siteKeywordsStringThe keywords which are related to the site and are used for SEO
siteTitleStringThe title of the site that is used for SEO
urlStringThe URL (taken from the location.href property). The URL includes the internal site state, for example: http://user.wixsite.com/site-name/pageTitle http://www.domain.com/pageTitleReturns the site URL only when using getSiteInfo in the live site and preview mode. When using it in Editor mode, returns the Editor URL.

Example:

Wix.getSiteInfo( function(siteInfo) {
//do something with the siteInfo
});
JavaScript | Copy Code

getSiteMap

Retrieves all items in the site structure, including:

  • Items in the site’s menu – pages (including subpages), links, and menu headers.
  • Hidden pages – pages that are in the site, but not in the site menu. For example, a “Thank You” page that’s shown only after a site visitor makes a purchase.

SDK Version: SDK 1.81.0+
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

getSiteMap(callback)
JavaScript | Copy Code

Note:
Use this method instead of getSitePages, which is now deprecated.

Parameters:

NameTypeDescription
callback (required)FunctionCallback function to receive the site structure

Value passed to callback:
An array of objects, where each object represents an item in the site structure.

Warning: To use this object later (for example, if you want to navigate to a link onthe user’s site), save this object in your database as is – don’t change it in any way.

Each object contains data about the item. The data sent depends on the item – check out our examples below. |Name |Type |Description| |---|---|---| |type|String|Type of link the item represents - for example ‘PageLink’ or ‘AnchorLink’.The data returned depends on the item - for example, an ‘AnchorLink’ object will include the anchorName and anchorDataId properties. Check out our examples below.| |pageId|String|The page ID. Note: If the user added a page anchor to the site’s menu, then this method returns an object for the anchor - so there might be multiple objects with the same page ID.| |title|String|The item title| |hidden||Boolean|Returns true if this page is hidden| |isHomePage|Boolean|Returns true if this page is the site's home page| |url|String|URL of this item| |subPages|Array objects|(Page objects only) If the page has subpages, returns an ordered set of subpages. Each subpage object contains more information about the subpage (id, title, hide, isHomePage, url).|

Here’s an example of an array passed to the callback function:

[
{
"type": "PageLink",
"pageId": "#c1dmp",
"title": "HOME",
"hidden": false,
"isHomePage": true,
"url": "http://my.wixsite.com/1-dp"
},
{
"type": "PageLink",
"pageId": "#kyck4",
"title": "Page",
"hidden": false,
"isHomePage": false,
"url": "http://my.wixsite.com/1-dp/page"
},
{
"type": "AnchorLink",
"anchorName": "Anchor",
"anchorDataId": "#dataItem-iyk5xcst",
"pageId": "#c1dmp",
"title": "anchor link",
"hidden": false,
"isHomePage": true,
"url": "http://my.wixsite.com/1-dp"
},
{
"type": "ExternalLink",
"target": "_blank",
"url": "http://google.com",
"title": "external",
"hidden": false
},
{
"type": "EmailLink",
"recipient": "email@email.com",
"subject": "dffg",
"title": "email",
"hidden": false
},
{
"type": "PhoneLink",
"phoneNumber": "1234216142",
"title": "phone",
"hidden": false
},
{
"type": "DocumentLink",
"docId": "7a9325_da6cc4b5cb65468bafbd937a9133aed0.pdf",
"name": "file1.pdf",
"title": "document",
"hidden": false,
"url": "http://media.wix.com/ugd/7a9325_da6cc4b5cb65468bafbd937a9133aed0.pdf"
},
{
"type": "DynamicPageLink",
"routerId": "routers-iympnnog",
"innerRoute": "fgfg",
"title": "dynamic page",
"hidden": false
},
{
"type": "MenuHeader",
"title": "Menu Header",
"hidden": false,
"subPages": [
{
"type": "PageLink",
"pageId": "#rsdvc",
"title": "New Page",
"hidden": false,
"isHomePage": false,
"url": "http://my.wixsite.com/1-dp/new-page"
}
]
}
]
JSON | Copy Code

Example:

Wix.getSiteMap(function(siteMap) {
//do something with the site pages
});
JavaScript | Copy Code

getStateUrl

This method retrieves the full URL of one of your internal pages on the live site, including the app’s state. For example:
mysite.com/my-store-app/product1.

SDK Version: SDK 1.69.0+
Editor Version: New Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Use this method if you have a Page component and you need the URL of an internal page.   

Syntax:

getStateUrl(sectionId, state, callback)
JavaScript | Copy Code

Parameters:

NameTypeDescription
sectionId (required)StringID of the Page component, as specified in the Dev Center
state (required)StringState of the app’s internal page - for example, ‘product1’
callback (required)FunctionCallback function to receive the full URL of the page, including the app state

Example:

Wix.getStateUrl('myStoreApp', 'product1', function(data) {
/* Do something with the data.url*/
});
JavaScript | Copy Code

isApplicationInstalled

Allows you to check if another one of your apps is installed.

SDK Version: SDK 1.86.0+
Editor Version: New Editor
Display: Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

isApplicationInstalled(appDefinitionId, callback)
JavaScript | Copy Code

Parameters:

NameTypeDescription
appDefinitionId (required)StringApp ID, as specified in the Developers Center
callback (required)FunctionCallback function that receives a boolean indicating if the app is installed in the site: function(isInstalled) {}

Example:

Wix.isApplicationInstalled(
'1380b703-ce81-ff05-f115-39571d94dfcd',
function(isInstalled){console.log(isInstalled)}
);
JavaScript | Copy Code

isAppSectionInstalled

Allows you to check if the user added one of your app’s hidden or custom pages (like a thank you or checkout page).

SDK Version: SDK 1.89.0+
Editor Version: New Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

isAppSectionInstalled(sectionId, \[options\], callback)
JavaScript | Copy Code

Parameters:

NameTypeDescription
sectionId (required)StringID of the Page component, as specified in the Developers Center
optionsObjectOptions for this method
options.appDefinitionIdStringIf the Page component is in a different one of your apps, enter that app’s ID (specified in the Developers Center)
callback (required)FunctionCallback function that receives a boolean indicating if the Page component is installed in the site: function(isInstalled) {}

Example:

Wix.isAppSectionInstalled(
'page_component_id',
function(isInstalled) {console.log (isInstalled)}
);
JavaScript | Copy Code

isVisualFocusEnabled

Checks if the user enabled visual focus for the live site. If your account manager told you to manually inject visual focus into your app, use this method before displaying visual focus.

SDK Version: SDK 1.87.0+
Display: Live Site
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

isVisualFocusEnabled(callback)
JavaScript | Copy Code

Important:
In most cases, we take care of visual focus and all you need to do is make sure you’re using SDK 1.84.0 or later. During the app review, we’ll let you know if you need to manually inject visual focus properties.

Parameters:

NameTypeDescription
callback (required)FunctionFunction that receives a boolean indicating if visual focus is enabled: function(isEnabled) {}

Example:

Wix.isVisualFocusEnabled(
function(isEnabled){console.log(isEnabled)}
);
JavaScript | Copy Code

logOutCurrentMember

Logs out a site member from the Wix site, and then refreshes the iframe. This method is relevant for apps that require site visitors to log in as members of the site.

SDK Version: SDK 1.67.0+
Display: Live Site
Component: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

logOutCurrentMember(\[onError\])
JavaScript | Copy Code

Parameters:

NameTypeDescription
onErrorFunctionCallback function with error details. An error is thrown if there is no site member logged in.

Example:

Wix.logOutCurrentMember()
JavaScript | Copy Code

navigateTo

Navigates to a page or link object. This object is passed to the callback function in one of these methods: 

SDK Version: SDK 1.81.0+
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

navigateTo(linkData, \[onFailure\])
JavaScript | Copy Code

Parameters:

NameTypeDescription
linkData (required)ObjectObject with link data, received in the callback function of these methods: Wix.Settings.openLinkPanel, Wix.getCurrentPageNavigationInfo, getSiteMap (Wix.getSiteMap, Wix.Settings.getSiteMap, or Wix.Worker.getSiteMap)
onFailureFunctionCallback function to receive details about a navigation error

Example:

Wix.navigateTo(
{
"type": "PageLink",
"pageId": "#c1dmp"
},
function() {...}
);
JavaScript | Copy Code

Note:
In preview, this method can’t open the link in the current window (_self). In SDK versions 1.94.0 and later, we send the following error code and you can display a message for users (e.g., “This link will work on your Published site.”)

error: {
code: "FORBIDDEN\_ACTION\_IN\_PREVIEW\_MODE",
message: "This function cannot be called in preview mode with target = \_self",
}
Copy Code

navigateToAnchor

Navigates to an anchor on the current page.

SDK Version: SDK 1.62.0+
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

navigateToAnchor(anchorId, \[onFailure\])
JavaScript | Copy Code

Parameters:

NameTypeDescription
anchorId (required)StringID of the anchor to navigate to
onFailureFunctionCallback function to receive an object that specifies the error. An error is invoked when the anchor doesn’t exist on the current page.

Example:

//Navigates to anchor with id = anchor1
Wix.navigateToAnchor('anchor1', function(error) {console.log(error.error)});
JavaScript | Copy Code

navigateToComponent

Directs site visitors to another component of your app.

SDK Version: SDK 1.47.0+
Display: Live Site, Preview
Component: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

navigateToComponent(compId, \[options\], \[onFailure\])
JavaScript | Copy Code

Parameters:

NameTypeDescription
compId (required)StringThe component to send site visitors to
optionsObjectOptions for this function
options.pageIdStringYou can specify the pageId to navigate to. When pageId is not provided, the function navigates to a component with the given id on the current page.
onFailureFunctionCallback function to receive an object that specifies the error. An error is invoked when: The current page does not contain the given component (and pageId was not provided), The provided pageId is not valid, The pageId is given but the page does not contain a component with the provided component ID. Note: The function will first navigate to a page with the provided pageId as an effect of this API call.

Example:

//Scrolls to a component with id = comp1, on a page with id = page1
Wix.navigateToComponent('comp1', {pageId: 'page1'}, function(error) {console.log(error.error)} );
JavaScript | Copy Code

navigateToPage

Navigates to a specific page or anchor in the site.

SDK Version: SDK 1.68.0+
Editor Version: New Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

navigateToPage (pageId,\[options\],\[onFailure\])
JavaScript | Copy Code

Note:
In the Editor, you can use this method to navigates to pages only – not anchors.

Parameters:

NameTypeDescription
pageId (required)StringThe page ID of the target page. Retrieve this id using the Wix.getSiteMap method.
optionsObjectOptions for this method
options.anchorIdStringThe ID of the anchor on the page. Retrieve this id using the Wix.getCurrentPageAnchors method.If the anchorId is specified, the method first navigates to the page (according to the pageId parameter), and then scrolls to this anchor. Note that you can only navigate to an anchor in the live site/preview - not in the Editor.
onFailureFunctionCallback function to receive an object that specifies the error. An error is thrown when: The anchorId doesn’t exist on the specified page, or the pageId doesn’t exist.

Example:

//Finds the second page in the site and navigates to it
Wix.getSiteMap(function(siteMap) {
var page_id = siteMap[1].pageId.substr(1);
Wix.navigateToPage(page_id);
});
JavaScript | Copy Code

onReady

Runs the specified function once the DOM loads. The DOM here refers to the Wix Editor or a page in the live site.

SDK Version: SDK 1.102.0+
Editor Version: New Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page

Syntax:

onReady(callback)
JavaScript | Copy Code

Note:
By waiting to run your code until the DOM is ready, you can help improve user experience and loading times.

Parameters:

NameTypeDescription
callback (required)FunctionFunction to run when the DOM is loaded

Example:

Wix.onReady( () => { console.log('Wix site is fully rendered now') });
JavaScript | Copy Code

openModal

Opens a lightbox-style modal window over the Wix site.

SDK Version: SDK 1.16.0+
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Here’s how the modal works:

  • The modal is a runtime widget, so it’s not part of the site structure.
  • The modal is a singleton – every new modal closes the previous one.
  • Users can close the modal by clicking the lightbox or pressing the close button. You can close the modal by calling Wix.closeWindow from within the modal iframe.

Syntax:

openModal(url, width, height, \[onClose\], \[theme\])
JavaScript | Copy Code

Parameters:

NameTypeDescription
url (required)StringURL of the modal iframe
width (required)NumberWidth of the modal, in pixels (for example, 400)
height (required)NumberHeight of the modal, in pixels (for example, 400)
onCloseFunctionOnClose callback function
themeWix.ThemeThe style of the modal: Wix.Theme.DEFAULT - has the regular modal look & feel - border, shadow, close button. Wix.Theme.BARE - a simple modal with no border, close button, shadow, etc.

Example:

var onClose = function(message) { console.log("modal closed", message); };
Wix.openModal("https://static.wixstatic.com/media/3cd1de924697419088c1e033bb3384ef.jpg", 400, 400, onClose);
JavaScript | Copy Code

openPopup

Opens a popup window in the live site or the preview mode of the Wix editor.

SDK Version: SDK 1.17.0+
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page

Here’s how the popup works:

  • It’s a runtime widget, so it’s not part of the site structure.
  • Users can close the popup by clicking the close button. You can close the popup by calling Wix.closeWindow from within the popup iframe.
  • You can open a few instances of the popup at the same time (it’s not a singleton).

Syntax:

openPopup(url, width, height, position, \[onClose\], \[theme\])
JavaScript | Copy Code

Parameters:

NameTypeDescription
url (required)StringURL of the popup iframe
width (required)Number/ StringWidth of the popup. In pixels: Enter a number (for example, 400), In percent: Enter a string (for example,‘70%’)
height (required)Number/ StringHeight of the popup. In pixels: Enter a number (for example, 400). In percent: Enter a string (for example,‘70%’)
position (required)ObjectThe position of the popup in the viewport
position.origin (required)Wix.WindowOriginWhere to open the popup from: Wix.WindowOrigin.FIXED - Positions the popup relative to the browser viewport. The popup stays fixed to this position, even if the user scrolls. Wix.WindowOrigin.RELATIVE - Positions the popup relative to the component that opened it (i.e, your site component). The popup stays fixed to the component, even if the user scrolls. Wix.WindowOrigin.ABSOLUTE - Positions the popup at specific coordinates (x,y). These coordinates are relative to the top-left corner of the component that opened it, and not the viewport. (The coordinates of the component’s top-left corner are 0,0.)
position.placementWix.WindowPlacementWhere to position the popup, relative to the origin you set above. The possible values are: Wix.WindowPlacement.TOP_LEFT, Wix.WindowPlacement.TOP_CENTER, Wix.WindowPlacement.TOP_RIGHT, Wix.WindowPlacement.CENTER_LEFT, Wix.WindowPlacement.CENTER, Wix.WindowPlacement.CENTER_RIGHT, Wix.WindowPlacement.BOTTOM_LEFT, Wix.WindowPlacement.BOTTOM_CENTER, Wix.WindowPlacement.BOTTOM_RIGHT. The default value is Wix.WindowPlacement.CENTER.
onCloseFunctionOnClose callback function
ThemeWix.ThemeThe style of the popup window. Wix.Theme.DEFAULT - has the regular popup look & feel, with a border, shadow, close button. Wix.Theme.BARE - a simple popup with no border, close button, shadow, etc.

Note:
When we render the popup, we’ll calculate if the popup will fit in the requested position with the specified size. If not, we’ll set the position to the center of the viewport: {origin: Wix.WindowOrigin.FIXED, placement: Wix.WindowPlacement.CENTER} This can happen when you set the origin to RELATIVE or ABSOLUTE, because the popup might be bigger than the margin between the site component and the viewport.

Examples:
Open a popup window positioned in the center of the screen (size is in pixels):

var position = {origin: Wix.WindowOrigin.FIXED, placement: Wix.WindowPlacement.CENTER};
var onClose = function(message) { console.log("popup closed", message) };
Wix.openPopup("https://static.wixstatic.com/media/3cd1de924697419088c1e033bb3384ef.jpg", 400, 400, position, onClose);
JavaScript | Copy Code

Open a popup window positioned relative to the center of the component (size is in %):

var position = {origin: Wix.WindowOrigin.RELATIVE, placement: Wix.WindowPlacement.CENTER};
var onClose = function(message) { console.log("popup closed", message) };
Wix.openPopup("https://static.wixstatic.com/media/3cd1de924697419088c1e033bb3384ef.jpg", '70%', '70%', position, onClose);
JavaScript | Copy Code

Open a popup window positioned to the bottom right of a specific point (x,y).
Calculate the x and y coordinates relative to the top-left corner of the site component that’s opening the popup – the coordinates of this corner are 0,0.

var position = {origin: Wix.WindowOrigin.ABSOLUTE, placement: Wix.WindowPlacement.BOTTOM_RIGHT, x: 20, y: 100};
var onClose = function(message) { console.log("popup closed", message) };
Wix.openPopup("https://static.wixstatic.com/media/3cd1de924697419088c1e033bb3384ef.jpg", 400, 400, position, onClose);
JavaScript | Copy Code

pushState

Enables AJAX style page apps to inform the Wix platform about a change in the app’s internal state. The new state will be reflected in the site/page URL. Once you call the pushState method, the browser’s top window URL will change the ‘app-state’ path part to the new state you provide with the pushState method (similar to the browser history API ). Read more about deep linking for a full explanation.

SDK Version: SDK 1.08.0+
Display: Live Site
Components: Page

Syntax:

pushState(state)
JavaScript | Copy Code

Parameters:

NameTypeDescription
state (required)StringThe new app's state to push into the editor history stack

Example:

Wix.pushState("app-state");
JavaScript | Copy Code

removeEventListener

Allows to remove previously assigned event listeners that were specified using Wix.addEventListener.

SDK Version: SDK 1.25.0+
Editor Version: New Editor, Old Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page

Syntax:

removeEventListener (eventName, callBackOrId)
JavaScript | Copy Code

Parameters:

NameTypeDescription
eventName (required)Wix.EventsUnique event identifier
CallBackOrId (required)FunctionA callback function that was used with addEventListener, or an ID returned by addEventListener

Example:

var callback = function(){};
var id = Wix.addEventListener(Wix.Events.EDIT_MODE_CHANGE, function(data) {
//do something
});
Wix.addEventListener(Wix.Events.PAGE_NAVIGATION, callback);
// remove listener as a callback function
Wix.removeEventListener(Wix.Events.PAGE_NAVIGATION, callback);
// remove listener as an id
Wix.removeEventListener(Wix.Events.EDIT_MODE_CHANGE, id);
JavaScript | Copy Code

replaceSectionState

This method is like the pushState method, except that this method replaces the URL in the browser’s history.

SDK Version: SDK 1.106.0+
Display: Live Site
Components: Page

Syntax:

replaceSectionState(state)
JavaScript | Copy Code

Parameters:

NameTypeDescription
state (required)StringNew state to push to the URL
optionsObjectOptions for this method
options.queryParamsStringParameters to push to the URL

Example:

Wix.replaceSectionState("app-state");
JavaScript | Copy Code

requestLogin

Prompts the site visitor to log in or register to the site. After a successful login, the site (and app iframe) will reload. The signed-instance parameter is added, with details about the site visitor.

SDK Version: SDK 1.69.0+
Display: Live Site
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

requestLogin(\[dialogOptions\],callback,\[onFailure\])
JavaScript | Copy Code

This method is relevant for apps that require site visitors to log in as members of the site.

Parameters:

NameTypeDescription
dialogOptionsObjectOptions for opening the login dialog box
dialogOptions.mode'login' or 'signup'Defines which dialog box should open by default: login or signup
dialogOptions.languageStringLanguage to use for the dialog box, as an ISO 639-1 language code. For example, ‘en’ or ‘es’.
callback (required)FunctionCallback function to receive the member's details
onFailureFunctionCallback function to use when the site visitor doesn’t log in successfully

Example:

Wix.requestLogin({mode:'login'}, function (data) {
//do something with the data
});
JavaScript | Copy Code

resizeComponent

Sets the width and/or height of a component, displaying it over other components in the page.

SDK Version: SDK 1.50.0+
Editor Version: New Editor
Components: Widget, Page

Syntax:

resizeComponent(options, onSuccess, \[onFailure\])
JavaScript | Copy Code

Note:
For fixed-position widgets, use resizeWindow instead.

Parameters:

NameTypeDescription
options (required)ObjectSpecify width and/or height (you must specify at least one)
options.widthNumberSize in pixels, for example: 450.If you don’t provide a value, the width remains the same.
options.heightNumberSize in pixels, for example: 450. If you don’t provide a value, the height remains the same.
onSuccess (required)FunctionReturns the new component size
onFailureFunctionError message invoked when no value is provided for width and height (you must give a value for at least one)

Example:

Wix.resizeComponent({
width: 400,
height: 600
});
JavaScript | Copy Code

resizeWindow

Sets the width and/or height of a fixed-position widget. For widgets and pages, use resizeComponent instead.

SDK Version: SDK 1.19.0+
Editor Version: New Editor, Old Editor
Display: Live Site, Preview
Components: Pinned (aka Fixed-Position) Widget

Syntax:

resizeWindow (width, height, onComplete)
JavaScript | Copy Code

Parameters:

NameTypeDescription
width (required)NumberThe new window's width
height (required)NumberThe new window's height
onComplete (required)FunctionOn resize complete callback function

Example:

// The following call will resize the widget's window
Wix.resizeWindow(300,300);
JavaScript | Copy Code

revalidateSession

Verifies that the session is secure. If the session is secure, this method returns a newly-signed app instance.

SDK Version: SDK 1.96.0+
Editor Version: New Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page

Use this method before displaying sensitive information or performing an action that requires a secure session.

Syntax:

revalidateSession(onSuccess, \[onFailure\])
JavaScript | Copy Code

Important:
Using this method in the live site? We don’t refresh the iframe with the new instance, so make sure to also listen for the INSTANCE_CHANGED event. This notifies any other components of your app in the site that the instance was updated, as well as components of your app that the user copied multiple times.

Parameters:

NameTypeDescription
onSuccess (required)FunctionReceives a newly-signed and encoded app instance
onFailureFunctionCallback function in case the session isn't secure

Example:

Wix.revalidateSession(
function(instanceData) {
//handle success use-case
},
function(error) {
//Handle error use-case
}
);
JavaScript | Copy Code

scrollBy

Performs a scroll by the specified number of pixels in the app’s hosting site window exactly as the standard method does.

SDK Version: SDK 1.19.0+
Display: Live Site, Preview
Component: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

scrollBy(x, y)
JavaScript | Copy Code

Parameters:

NameTypeDescription
x (required)Number How many pixels to scroll by, along the x-axis (horizontal)
y (required)NumberHow many pixels to scroll by, along the y-axis (vertical)

Example:

Wix.scrollBy(0,0);
JavaScript | Copy Code

Note:
In SDK versions 1.45.0 and earlier, this method was also available in the Editor. Since SDK v1.46.0, it is available only in the live site and preview.

scrollTo

Performs a scroll to a fixed position in the app’s hosting site window exactly as the standard method does.

SDK Version: SDK 1.89.0+
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

scrollTo(x, y,\[options\])
JavaScript | Copy Code

Parameters:

NameTypeDescription
x (required)NumberThe coordinate to scroll to, along the x-axis
y (required)NumberThe coordinate to scroll to, along the y-axis
optionsObjectOptions for this method
options.scrollAnimationBooleanIndicates whether to scroll with an animation. true - scrolls with an animation, false - scrolls directly to the target, with no animation

Example:

Wix.scrollTo(0, 0, {scrollAnimation: true});
JavaScript | Copy Code

setHeight

Requests the hosting Wix platform to change the iframe height inside the site/editor.

SDK Version: SDK 1.50.0+
Editor Version: New Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

You can do one of the following:

  • Display your app over other components in the page
  • Push other components further down the page (default behavior)

Syntax:

setHeight(height, \[options\])
JavaScript | Copy Code

Parameters:

NameTypeDescription
height (required)NumberAn integer that represents the desired height in pixels. Important: The max height is 10,000px. When exceeded, the app frame is cut in the live site.
optionsObjectOptions for this method
options.overflowBooleanTells the platform how to display the component. true to display and resize this component over other components on the page, false to push other components further down the page (the default behavior).

Example:

Wix.setHeight(1000, {overflow:true})
JavaScript | Copy Code

setPageMetadata

Sets metadata for the page. Search engines display this metadata – the page’s title and/or description – in search results.

SDK Version: SDK 1.67.0+
Display: Live Site
Components: Page

Syntax:

setPageMetadata(\[options\])
JavaScript | Copy Code

Important:
Make sure the title and description you add here match your app’s SEO endpoint.

Parameters:

NameTypeDescription
optionsObjectPage metadata
options.titleStringThe name of this page (for example, the product name). We’ll insert this name into the page title.
options.descriptionStringThe page description

Example:

Wix.setPageMetadata({
title: 'Page Name',
description: 'new description'
});
JavaScript | Copy Code

Deprecated

getSitePages

Retrieves all pages in this site. A page can be:

  • An item in the site’s menu – a page, subpage, external link, link to a page anchor, or menu header.
  • A hidden page/subpage – these pages are part of the site, but they’re not part of the site menu. For example, a “Thank You” page that’s shown only after a site visitor makes a purchase.

SDK Version: Deprecated

Warning:
Now that this method is deprecated, use getSiteMap instead.

Parameters:

NameTypeDescription
optionsObjectOptions for this method
callback (required)FunctionA callback function to receive the site structure

Returns: An array of objects, where each object represents a page in the site. 

The objects are ordered according to the site’s structure shown in the Pages menu of the Wix Editor. If a page has subpages, they are returned as an array of objects nested inside the page object.

Each page/subpage object contains the following properties:

NameTypeDescription
idStringThe page/subpage ID. If the user added a page anchor to the site’s menu, then this method returns an object for the anchor - so there might be multiple objects with the same page ID
titleStringThe title of the page/subpage
hideBooleanReturns true if this page/subpage is hidden
isHomePageBooleanReturns true if this page/subpage is the site's home page
subPagesArray objects(Page objects only) If the page has subPages, returns an ordered set of subpages. Each subpage object contains more information about the subpage (id, title, hide, isHomePage, url).

reportHeightChange

Requests the hosting Wix platform to change the iframe’s height inside the website or the editor.

SDK Version: Deprecated

Warning:
Now that this method is deprecated, use setHeight instead.

Parameters:

NameTypeDescription
height (required)NumberAn integer that represents the desired height in pixels

Was this helpful?

Wix.Activities

getActivityById

Gets a specific Activity that occurred on the current site.

SDK Version: SDK 1.28.0+
Components: Dashboard

Syntax:

getActivityById(id, onSuccess, onFailure)
JavaScript | Copy Code

Parameters:

NameTypeDescription
id (required)StringThe ID of the activity to look up
onSuccess (required)FunctionCallback function to receive an object with data about the activity
onFailure (required)FunctionCallback triggered if the data could not be returned successfully

Example:

Wix.Activities.getActivityById(id, onSuccess, onFailure)
JavaScript | Copy Code

postActivity

This method posts an activity to the current site. When the Activity is successfully created, the id of the activity will be returned. If schema validation fails, or other errors occur, an error is returned.

SDK Version: SDK 1.25.0 – 1.77.0+
Display: Live Site
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

postActivity(activity, onSuccess, \[onFailure\])
JavaScript | Copy Code

Parameters:

NameTypeDescription
**activity (required)ObjectAn activity descriptor (must follow specific type/schema pattern)
activity.type (required)Wix.Activities.TypeThe activity type as detailed in the table below
activity.info (required)ObjectDetailed information about this activity, according to the activity type schema
activity.details (required)ObjectMore information about the activity
activity.details.additionalInfoUrl (required)StringThe URL to open when the user clicks on the activity notification in the site’s dashboard. Apps with a dashboard component: link to this specific activity within your app’s Dashboard component:HTTP://www.wix.com/my-account/app/<appID>/<appInstanceID>/<appState>. For example, if a site visitor makes a purchase, direct users to a page where they can see details about this purchase. Apps without a dashboard component: Enter “null” or direct the user to a page with information about this activity. For example, if a site visitor liked a photo, direct the user to this photo on the live site.
activity.contactUpdate (required)ObjectInformation about the site visitor who performed this activity. If you have any information about the site visitor, use contactUpdate to link the activity to a site Contact. Make sure to include at least the email or phone number in your request - we need it to create/update the contact. If not, use 'null'. However, note that we won't display the activity in the site's dashboard until we can link the activity to a contact.
activity.contactUpdate.nameObjectContact's name
activity.contactUpdate.name.prefixStringName prefix (limited to 100 characters)
activity.contactUpdate.name.firstStringFirst name (limited to 100 characters)
activity.contactUpdate.name.middleStringMiddle name (limited to 100 characters)
activity.contactUpdate.name.lastStringLast name (limited to 100 characters)
activity.contactUpdate.name.suffixStringName suffix (limited to 100 characters
activity.contactUpdate.pictureStringURL to the contact's photo
activity.contactUpdate.companyObjectContact's company details
activity.contactUpdate.company.roleStringContact's role at the company (limited to 100 characters)
activity.contactUpdate.company.nameStringContact's company name (limited to 100 characters)
activity.contactUpdate.emailsArrayobjectContact's emails
activity.contactUpdate.emails.idNumberID of this email within the array
activity.contactUpdate.emails.tag (required)StringTag for this email - home, work, etc. (limited to 100 characters)
activity.contactUpdate.emails.email (required)StringContact's email address (limited to 250 characters)
activity.contactUpdate.emails.emailStatus"optOut", "transactional", or "recurring"The subscription status for this email. optOut: Contact unsubscribed from all emails. transactional: Contact subscribed to non-promotional emails. recurring: Contact subscribed to all emails.
activity.contactUpdate.emails.deliveryStatus‘valid’, ‘spam’, ‘complaint’, ‘rejected’, ‘deferral’, ‘bounce’Email delivery status. valid: When emails are delivered successfully. spam: When emails are marked as spam by the recipient. complaint: When the recipient of the email has made a complaint to the email provider. rejected: When the email is rejected by email provider. deferral: When your email provider refuses to send emails. bounce: When the mailbox is full, email address doesn't exist, etc.
activity.contactUpdate.phonesArrayobjectContact's phone
activity.contactUpdate.phones.IdNumberID of this phone number within the array
activity.contactUpdate.phones.tag (required)StringTag for this phone number - home, work, etc (limited to 100 characters)
activity.contactUpdate.phones.phone (required)StringContact's phone number (limited to 30 characters)
activity.contactUpdate.phones.normalizedPhoneStringContact's normalized phone number
activity.contactUpdate.addressesArrayobjectContact's address
activity.contactUpdate.addresses.idNumberID of this address within the array
activity.contactUpdate.addresses.tag (required)StringTag for this address - home, work, etc (limited to 100 characters)
activity.contactUpdate.addresses.addressStringContact's street address (limited to 250 characters)
activity.contactUpdate.addresses.neighborhoodStringContact's neighborhood (limited to 100 characters)
activity.contactUpdate.addresses.cityStringContact's city (limited to 100 characters)
activity.contactUpdate.addresses.regionStringContact's region, such as a U.S. state or Canadian province (limited to 100 characters)
activity.contactUpdate.addresses.countryStringContact's country (limited to 100 characters)
activity.contactUpdate.addresses.postalCodeStringContact's postal code (limited to 20 characters)
activity.contactUpdate.urlsArrayobjectURLs associated with the contact, like Facebook or LinkedIn
activity.contactUpdate.urls.idNumberID of this URL within the array
activity.contactUpdate.urls.tag (required)StringTag for this URL - personal, work, etc (limited to 100 characters)
activity.contactUpdate.urls.url (required)StringThe URL
activity.contactUpdate.datesArrayobjectImportant dates for this contact, like birthday
activity.contactUpdate.dates.idNumberID of this date within the array
activity.contactUpdate.dates.tag (required)StringTag for this date - birthday, anniversary, etc (limited to 100 characters)
activity.contactUpdate.dates.date (required)StringThe date, as an ISO 8601 timestamp
onSuccess (required)FunctionSuccess callback function
onFailureFunctionFailure callback function

The activity types that you can currently post:

TypeActivityDescription
FORM_CONTACT_FORMform/contact-formWhen your app submits a contact form
FORM_SUBSCRIPTION_FORMform/subscription-formWhen your app submits a subscription form
FORM_FORMform/formWhen your app submits another type of form
SCHEDULER_APPOINTMENTscheduler/appointmentWhen an appointment is made
SCHEDULER_CONFIRMATIONscheduler/confirmationWhen an appointment is confirmed. Availability: Since 1.45.0
SCHEDULER_CANCELscheduler/cancelWhen an appointment is cancelled. Availability: Since 1.45.0
SOCIAL_COMMENTsocial/commentWhen a site visitor posts a comment on the site. Availability: Since 1.61.0
SOCIAL_SHARE_URLsocial/share-urlWhen a site visitor shares an item (like a blog post or photo) on social media. Availability: Since 1.61.0
SOCIAL_TRACKsocial/trackWhen a site visitor takes one of these social media actions on the user’s channel: like, follow, subscribe, pin. Availability: Since 1.61.0
HOTELS_PURCHASEhotels/purchaseWhen a hotel service is purchased
HOTELS_PURCHASE_FAILEDhotels/purchase-failedWhen a purchase (of the hotel service) could not be completed
HOTELS_RESERVATIONhotels/reservationWhen a reservation is made
HOTELS_CONFIRMATIONhotels/confirmationWhen a reservation is confirmed
HOTELS_CANCELhotel/cancelWhen a reservation is cancelled
TRACK_PLAYmusic/track-playWhen a request to start playing a song is made
TRACK_SKIPmusic/track-skipWhen a track was skipped
TRACK_PLAYEDmusic/track-playedWhen a song finished playing
TRACK_LYRICSmusic/track-lyricsWhen the track lyrics are requested
TRACK_SHAREmusic/track-shareWhen a track is shared using your app
ALBUM_SHAREmusic/album-shareWhen an album is shared using your app
ALBUM_FANmusic/album-fanWhen a visitor becomes a fan of an album
ALBUM_PLAYEDmusic/album-playedWhen an album finished playing
ECOMMERCE_CART_ADDecommerce/cart-addWhen an item is added to a cart. Availability: Since 1.45.0
ECOMMERCE_CART_REMOVEecommerce/cart-removeWhen an item is removed from a cart. Availability: Since 1.45.0
ECOMMERCE_CART_CHECKOUTecommerce/cart-checkoutWhen a checkout process has begun with this cart. Availability: Since 1.45.0
ECOMMERCE_CART_ABANDONecommerce/cart-abandonWhen a cart is abandoned. Availability: Since 1.45.0
ECOMMERCE_PURCHASEecommerce/purchaseWhen the checkout process has completed
MESSAGE_IMmessaging/imWhen a chat/sms message is sent between a Wix user and a site visitor/contact
EVENTS_RSVPevents/rsvpWhen a guest RSVPs to an event. Availability: Since 1.77.0
RESTAURANTS_ORDERrestaurants/orderWhen an order is placed in a restaurant. Availability: Since 1.77.0.

Example:

var activity = {
type: Wix.Activities.Type.FORM_CONTACT_FORM,
info: {
subject: "My Subject",
content: { message: "My Message"}
},
details: {
additionalInfoUrl:'http://www.wix.com/my-account/app/{app-def-id}/{instance-id}/{app-related-deep-link}',
summary: ""
},
contactUpdate:{
name: {first:"Kanye"},
emails: [ {tag: "main", email: "email@email.com"} ]
}
};
var onSuccess = function(d){console.log("Activity ID: " + d.activityId + ", Contact ID: " + d.contactId)};
var onFailure = function(d){console.log("Failure message:" + d)};
Wix.Activities.postActivity(activity, onSuccess, onFailure);
JavaScript | Copy Code

Was this helpful?

Wix.Analytics

trackEvent

Reports an event in the live site to the user’s analytics tool, like Facebook Pixel or Google Analytics.

SDK Version: SDK 1.93.0+
Display: Live Site
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Worker

Syntax:

trackEvent(eventName, params)
JavaScript | Copy Code

Parameters:

NameTypeDescription
eventName (required)StringName of the event, as specified in the list below.You can also define a custom event.
params (required)ObjectObject with key/value pairs required to report this event

Example:

Wix.Analytics.trackEvent('ViewContent', {
sku: 'P12345',
name: 'Really Fast Running Shoes',
category: 'Apparel/Shoes',
price: 150,
currency: 'USD',
brand: 'New Balance',
variant: 'Blue',
list: 'Search Results',
position: 1
});
JavaScript | Copy Code

Events

You can report the following events with trackEvent:

  • AddProductImpression – When a visitor views a product
  • ClickProduct – When a visitor clicks on a product
  • ViewContent – When a key page is viewed (such as a product page)
  • AddToCart – When a visitor adds a product to the shopping cart
  • RemoveFromCart – When a visitor removes a product from shopping cart
  • InitiateCheckout – When a visitor starts the checkout process
  • AddPaymentInfo – When the visitor saves payment information
  • Purchase – When the checkout process is complete
  • Lead – When a visitor subscribes to a newsletter or submits a contact form
  • CustomEvent – When a visitor performs an event not listed above

Important:
In these events we refer to “products”, but a product can be any important item the user is tracking, like a service, event, music track or album, etc.

AddProductImpression

Report this event when a visitor views a product or item.

Syntax:

origin, **contents**\[{id, sku, **name**, price, currency, category, brand, variant, list, position}\]
JavaScript | Copy Code

Parameters:

NameTypeDescription
originStringOrigin of the event (e.g. Music Player, Contact Form)
contents (required)ArrayObjectsKey/value pairs with more details about the product
contents.idStringProduct ID
contents.skuStringSKU number for the product
contents.name (required)StringName of the product
contents.priceNumberPrice of the product
contents.currencyStringCurrency code (e.g., EUR, USD, CAD)
contents.categoryStringCategory the product is listed under (e.g., ‘Accessories/Watches’)
contents.brandStringBrand name of the product (e.g., ‘Nike’)
contents.variantStringVariant of the product (like a specific color or size)
contents.listStringList or collection the item is in (e.g., ‘Product Gallery’ or ‘Search Results’)
contents.positionNumberPosition of this item within a list or collection (e.g., 1)

Example:

Wix.Analytics.trackEvent('AddProductImpression', {
origin: My Shoe Store',
contents: [{
sku: 'P12345',
name: 'Really Fast Running Shoes',
category: 'Apparel/Shoes',
price: 100,
currency: 'USD',
brand: 'Nike',
variant: 'Black',
list: 'Search Results',
position: 1
}]
});
JavaScript | Copy Code

ClickProduct

Report this event when a visitor clicks on a product or item.

Syntax:

{origin, id, sku, **name**, price, currency, category, brand, variant, list, position}
JavaScript | Copy Code

Parameters:

NameTypeDescription
originStringOrigin of the event (e.g. Music Player, Contact Form)
idStringProduct ID
skuStringSKU number for this product
name (required)StringName of the product
priceNumberPrice of the product
currencyStringCurrency code (e.g., EUR, USD, CAD)
categoryStringCategory this product is listed under (e.g., ‘Accessories/Watches’)
brandStringBrand name of the product (e.g., ‘Nike’)
variantStringVariant of this product (like a specific color or size)
listStringList or collection the item is in (e.g., ‘Product Gallery’ or ‘Search Results’)
positionNumberPosition of this item within a list or collection (e.g., 1)

Example:

Wix.Analytics.trackEvent('ClickProduct', {
origin: 'My Shoe Store',
id: 'P12345',
name: 'Really Fast Running Shoes',
category: 'Apparel/Shoes',
price: 120,
currency: 'USD',
brand: 'Adidas',
variant: 'Black',
position: 1
});
JavaScript | Copy Code

ViewContent

Report this event when a visitor views a key page, like the product page.

Syntax:

{origin, id, sku, **name**, price, currency, category, brand, variant, list, position}
JavaScript | Copy Code

Parameters:

NameTypeDescription
originStringOrigin of the event (e.g. Music Player, Contact Form)
idStringProduct ID
skuStringSKU number for this product
name (required)StringName of the product
priceNumberPrice of the product
currencyStringCurrency code (e.g., EUR, USD, CAD)
categoryStringCategory this product is listed under (e.g., ‘Accessories/Watches’)
brandStringBrand name of the product (e.g., ‘Nike’)
variantStringVariant of this product (like a specific color or size)
listStringList or collection the item is in (e.g., ‘Product Gallery’ or ‘Search Results’)
positionNumberPosition of this item within a list or collection (e.g., 1)

Example:

Wix.Analytics.trackEvent('ViewContent', {
origin: 'My Shoe Store',
sku: 'P12345',
name: 'Really Fast Running Shoes',
category: 'Apparel/Shoes',
price: 150,
currency: 'USD',
brand: 'New Balance',
variant: 'Blue',
list: 'Search Results',
position: 1
});
JavaScript | Copy Code

AddToCart

Report this event when a visitor clicks a button to add a product to the shopping cart (e.g., when the Add to Cart button is clicked).

Syntax:

{origin, id, sku, **name**, price, currency, category, brand, variant, list, position, quantity}
JavaScript | Copy Code

Parameters:

NameTypeDescription
originStringOrigin of the event (e.g. Music Player, Contact Form)
idStringProduct ID
skuStringSKU number for this product
name (required)StringName of the product
priceNumberPrice of the product
currencyStringCurrency code (e.g., EUR, USD, CAD)
categoryStringCategory this product is listed under (e.g., ‘Accessories/Watches’)
brandStringBrand name of the product (e.g., ‘Nike’)
variantStringVariant of this product (like a specific color or size)
positionNumberPosition of this item within a list or collection (e.g., 1)
quantityNumberProduct quantity

Example:

Wix.Analytics.trackEvent('AddToCart', {
origin: 'My Shoe Store',
id: 'P12345',
name: 'Really Fast Running Shoes',
category: 'Apparel/Shoes',
price: 120.5,
currency: 'USD',
brand: 'Saucony',
variant: 'Silver',
position: 2,
quantity: 1
});
JavaScript | Copy Code

RemoveFromCart

Report this event when a visitor clicks a button to remove a product from the shopping cart.

Syntax:

{origin, id, **name**, price, currency, category, brand, variant, position, quantity}
JavaScript | Copy Code

Parameters:

NameTypeDescription
originStringOrigin of the event (e.g. Music Player, Contact Form)
idStringProduct ID
name (required)StringName of the product
priceNumberPrice of the product
currencyStringCurrency code (e.g., EUR, USD, CAD)
categoryStringCategory this product is listed under (e.g., ‘Accessories/Watches’)
brandStringBrand name of the product (e.g., ‘Nike’)
variantStringVariant of this product (like a specific color or size)
positionNumberPosition of this item within a list or collection (e.g., 1)
quantityNumberProduct quantity

Example:

Wix.Analytics.trackEvent('RemoveFromCart', {
origin: 'My Shoe Store',
id: 'P12346',
name: 'Really Fast Running Shoes',
price: 125.95,
currency: 'USD',
category: 'Apparel/Shoes',
brand: 'Adidas',
variant: 'Black',
position: 1,
quantity: 1
});
JavaScript | Copy Code

InitiateCheckout

Report this event when a visitor clicks a button to begin the checkout process.

Syntax:

origin, **contents**\[{id, sku, **name**, price, currency, category, brand, variant, quantity}\]
JavaScript | Copy Code

Parameters:

NameTypeDescription
originStringOrigin of the event (e.g. Music Player, Contact Form)
contents (required)ArrayObjectsKey/value pairs with more details about the product
contents.idStringProduct ID
contents.skuStringSKU number for the product
contents.name (required)StringName of the product
contents.priceNumberPrice of the product
contents.currencyStringCurrency code (e.g., EUR, USD, CAD)
contents.categoryStringCategory the product is listed under (e.g., ‘Accessories/Watches’)
contents.brandStringBrand name of the product (e.g., ‘Nike’)
contents.variantStringVariant of the product (like a specific color or size)
contents.quantityNumberQuantity of this specific product a visitor is purchasing

Example:

Wix.Analytics.trackEvent('InitiateCheckout', {
origin: 'My Shoe Store',
contents: [ {
sku: 'P12345',
name: 'Really Fast Running Shoes',
category: 'Apparel/Shoes',
price: 100,
currency: 'USD',
brand: 'Nike',
variant: 'Black',
quantity: 2
},
{
sku: 'P67890',
name: 'Running Shirt',
category: 'Apparel/Shirts',
price: 50,
currency: 'USD',
brand: 'Nike',
variant: 'Blue',
quantity: 3
}]
});
JavaScript | Copy Code

StartPayment

Report this event when a visitor reaches a payment form, before making a purchase.

Syntax:

{origin, option}
JavaScript | Copy Code

Parameters:

NameTypeDescription
originStringOrigin of the event (e.g. Music Player, Contact Form)
optionStringPayment type (e.g., 'Fast Checkout')

Example:

Wix.Analytics.trackEvent('StartPayment', {
origin: 'My Shoe Store',
option: 'Fast Checkout'
});
JavaScript | Copy Code

AddPaymentInfo

Report this event when a visitor clicks a button to save payment info for a purchase.

Syntax:

{origin, option}
JavaScript | Copy Code

Parameters:

NameTypeDescription
originStringOrigin of the event (e.g. Music Player, Contact Form)
optionStringPayment type (e.g., ‘Visa’ or ‘PayPal’)

Example:

Wix.Analytics.trackEvent('AddPaymentInfo', {
origin: 'My Shoe Store',
option: 'Visa'
});
JavaScript | Copy Code

CheckoutStep

Report this event for any custom checkout interaction that a visitor completes between initiating a checkout and completing a purchase.

Syntax:

{origin, step, action, option}
JavaScript | Copy Code

Parameters:

NameTypeDescription
originStringOrigin of the event (e.g. ‘Music Player’, or ‘Contact Form’)
stepStringCheckout flow step number. Make sure to report consistent step values (e.g. ‘3’ when step follows StartPayment and addPaymentInfo events)
actionStringThe action the visitor is taking in this step (e.g. ‘Select Shipping’)
optionStringPayment type (e.g., ‘Express Shipping’)

Example:

Wix.Analytics.trackEvent('CheckoutStep', {
origin: 'My Shoe Store',
step: '3',
action: 'Select Shipping',
option: 'Fast Checkout'
});
JavaScript | Copy Code

Purchase

Report this event when a purchase is completed successfully.

Syntax:

{origin, **id**, affiliation, revenue, tax, shipping, coupon, **contents**}
JavaScript | Copy Code

Parameters:

NameTypeDescription
originStringOrigin of the event (e.g. Music Player, Contact Form)
id (required)StringTransaction ID or order number
affiliationStringName of the store
revenueStringTotal amount for this purchase, including taxes, shipping, etc. (e.g., ‘5.99’)
taxStringTotal amount charged in taxes (e.g., ‘5.99’)
shippingStringTotal amount charged for shipping (e.g., ‘5.99’)
couponStringCoupon code applied to this purchase
contents (required)ArrayObjectsArray of all product objects related to this purchase
contents.idStringProduct ID
contents.name (required)StringName of the product
contents.priceNumberPrice of the product
contents.currencyStringCurrency code (e.g., EUR, USD, CAD)
contents.categoryStringCategory the product is listed under (e.g., ‘Accessories/Watches’)
contents.brandStringBrand name of the product (e.g., ‘Nike’)
contents.variantStringVariant of the product (like a specific color or size)
contents.quantityNumberQuantity of this specific product a visitor is purchasing

Example:

Wix.Analytics.trackEvent('Purchase', {
origin: 'My Shoe Store',
id: 'T12345',
affiliation: 'My Store',
revenue: '22.16',
tax: '2.85',
shipping: '5.34',
coupon: 'SUMMER2013',
contents: [ {
id: 'ABC123',
quantity: 2,
price: 1.99,
currency: 'USD',
},
{
id: 'XYZ789',
quantity: 1,
price: 9.99,
currency: 'USD',
} ]
});
JavaScript | Copy Code

Lead

Report this event when a visitor subscribes to a newsletter or submits a contact form.

Example:

Wix.Analytics.trackEvent('Lead');
JavaScript | Copy Code

CustomEvent

Report a custom event that doesn’t fit any of the standard events listed above.

Syntax:

{event, \*}
JavaScript | Copy Code

Parameters:

NameTypeDescription
event (required)StringName of the event
paramCustomName of the parameter

Example:

Wix.Analytics.trackEvent('CustomEvent', {
event: 'FrequentShopper',
num_purchases: 8,
average_order: 245.24,
favorite_category: 'Sporting Goods'
});
JavaScript | Copy Code

Deprecated

reportCampaignEvent

SDK Version: Deprecated

Important:
Now that this method is deprecated, use trackEvent instead.

Reports an event that happened in your app on the live site. The event is sent to all registered pixels on the site – even pixels used in other apps.

Parameters:

NameTypeDescription
PixelEventType (required)Wix.Analytics.PixelEventType.EVENT.eventNameThe event you are reporting. You can see the event descriptions in Facebook’s Pixel API. To make sure that the event matches Facebook’s API, enter the event name in this format: Wix.Analytics.PixelEventType.EVENT.eventName, where EVENT is one of the following: VIEW_CONTENT, SEARCH, ADD_TO_CART, ADD_TO_WISHLIST, INITIATE_CHECKOUT, ADD_PAYMENT_INFO, PURCHASE, LEAD, COMPLETE_REGISTRATION, CUSTOM_EVENT. For example, Wix.Analytics.PixelEventType.PURCHASE.eventName returns the correct event name - ‘Purchase’.
dataObjectEnter the event parameters. To get a list of required and optional parameters for an event, use this method: Wix.Analytics.PixelEventType.EVENT. For more information, see Facebook’s Pixel API.

Example:

Wix.Analytics.reportCampaignEvent(Wix.Analytics.PixelEventType.PURCHASE.eventName, {value: 50, currency: 'USD'});
JavaScript | Copy Code

registerCampaignPixel

SDK Version: Deprecated

Registers and initializes the Facebook pixel on the live site. The pixel registration is saved for this session only, so call this method every time your app loads in the live site.

Parameters:

NameTypeDescription
pixelType (required)PixelTypeEnter Wix.Analytics.PixelType.FACEBOOK here
pixelId (required)StringA unique pixel identifier that was predefined by Facebook and is associated with a Facebook Ad account

Example:

Wix.Analytics.registerCampaignPixel(Wix.Analytics.PixelType.FACEBOOK, '1234567890');
JavaScript | Copy Code

Was this helpful?

Wix.Billing

getProducts

Note:
Have a dashboard app? Use Wix.Dashboard.getProducts instead.

Returns a json with pricing information for all of your app’s packages – premium plans and in-app purchase packages. 

SDK Version: SDK 1.76.0+
Display: New Editor
Components: Settings Panel, Settings Modal

Syntax:

getProducts([options], onSuccess, [onFailure]).
JavaScript | Copy Code

Parameters:

NameTypeDescription
optionsObjectOptions for this method
options.currencyStringCurrency for your app’s in-app purchase package. Use this parameter to limit your package to a specific currency. If left blank, we’ll display the currency according to the user’s region (locale).
onSuccess (required)FunctionA callback function to receive the pricing information
onFailureFunctionA callback function for when an error occurs

Example:

Wix.Billing.getProducts(OnSuccess, OnError);
//Here is an example of the response
"packages": [ {
"id": "Premium1",
"name": "Comments Premium Package",
"price": "4.95",
"is_active": true,
"freeMonth": true,
"currencyCode": "USD",
"currencySymbol": "US$"
"monthly": {
"price": "4.95",
“Link”: "https://premium.wix.com/wix/api/tpaStartPurchase?appInstanceId=aaa-bbb&appDefinitionId=a1a2a-b3b4b&paymentCycle=MONTHLY&vendorProductId=package1"
},
"yearly": {
"price": "3.97",
“Link”: "https://premium.wix.com/wix/api/tpaStartPurchase?appInstanceId=aaa-bbb&appDefinitionId=a1a2a-b3b4b&paymentCycle=YEARLY&vendorProductId=package2"
},
"oneTime": {
"price": "5.99",
“Link”: "https://premium.wix.com/wix/api/tpaStartPurchase?appInstanceId=aaa-bbb&appDefinitionId=a1a2a-b3b4b&paymentCycle=ONE_TIME&vendorProductId=package3"
},
"bestSellingFeature": "",
"discountPercent": 20
}]
JavaScript | Copy Code

Was this helpful?

Wix.Contacts

Important:
Wix.Contacts methods are only available from the Dashboard endpoint.

getContactById

Gets a specific Contact that has interacted with the current site by its ID.

SDK Version: SDK 1.32.0+
Display: Dashboard

Syntax:

getContactById(id, onSuccess, onFailure)
JavaScript | Copy Code

Parameters:

NameTypeDescription
id (required)StringThe ID of the contact to look up
onSuccess (required)FunctionCallback function to receive an object with data about the contact
onFailure (required)FunctionCallback function that's triA function called when an error occurs that receives a Wix.Error

Example:

Wix.Contacts.getContactById(id, function(data), function(errorType));
JavaScript | Copy Code

getContacts

Gets a list of all contacts that have interacted with a given site.

SDK Version: SDK 1.31.0+
Display: Dashboard

Syntax:

getContacts(options, onSuccess, onFailure) 
JavaScript | Copy Code

Parameters:

NameTypeDescription
options (required)ObjectOptions for this function
options.labelString or Array[string1, string2,...]Filter the list of contacts to return by specifying one or more labels that were defined by the user.

For example: customers or [customers, colleagues]
options.pageSizeInteger (1-500)Number of contacts to display per page.

Default is 25.
onSuccess (required)FunctionCallback function to receive the WixDataCursor object
onFailure (required)FunctionAn on failure callback

Value passed to onSuccess callback:

A WixDataCursor object, with the results presented in descending order by date. The following methods are supported by the WixDataCursor:

  • getData() → {Contacts[]} – A list of all the Contacts in the current website.
  • getPageSize() → {Number} – The number of the cursor page size.
  • getTotal() → {Number} – The total number of object in the cursor.
  • hasNext() → {boolean} – If WixDataCursor has more data.
  • hasPrevious() → {boolean} – If WixDataCursor has previous data.
  • next(onSuccess, onFailure) → {boolean} – The next WixDataCursor object.
  • previous(onSuccess, onFailure) → {boolean} – The previous WixDataCursor object.

Example:

var options = {label: "label", pageSize: 50};
Wix.Contacts.getContacts(options, onSuccess, onFailure)
JavaScript | Copy Code

reconcileContact

Use this method to share contact information with the WixHive.

SDK Version: SDK 1.46.0+
Display: Dashboard

Syntax:

reconcileContact(contactInfo, onSuccess, \[onFailure\])
JavaScript | Copy Code

Parameters:

NameTypeDescription
contactInfo (required)ObjectContact information collected by your app. Make sure to include at least the email or phone number in your request - we need it to create/update the contact.
contactInfo.NameObjectContact's Name
contactInfo.Name.prefixStringName prefix (limited to 100 characters)
contactInfo.Name.firstStringFirst name (limited to 100 characters)
contactInfo.Name.middleStringMiddle name (limited to 100 characters)
contactInfo.Name.lastStringLast name (limited to 100 characters)
contactInfo.Name.suffixStringName suffix (limited to 100 characters)
contactInfo.pictureStringURL to the Contact's photo
contactInfo.companyObjectContact's company details
contactInfo.company.roleStringContact's position or role (limited to 100 characters)
contactInfo.company.nameStringCompany name (limited to 100 characters)
contactInfo.emailsArray[object]Contact's email addresses
contactInfo.emails.idNumberID of this email within the array
contactInfo.emails.tag (required)String]Tag for this email - home, work, etc (limited to 100 characters)
contactInfo.emails.email (required)StringEmail address (limited to 250 characters)
contactInfo.emails.emailStatus"optOut", "transactional" or "recurring"The subscription status of the current email
contactInfo.emails.deliveryStatus"VALID", "SPAM", "COMPLAINT", "REJECTED",  "DEFERRAL" or "BOUNCE"Email delivery status:
  • VALID: When emails are delivered successfully.
  • SPAM: When emails are marked as spam by the recipient.
  • COMPLAINT: When the recipient of the email has made a complaint to the email provider.
  • REJECTED: When the email is rejected by email provider.
  • DEFERRAL: When your email provider refuses to send emails.
  • BOUNCE: When the mailbox is full, email address doesn't exist, etc.
contactInfo.phonesArray[object]Contact's phone number
contactInfo.phones.idNumberID of this phone number within the array
contactInfo.phones.tag (required)StringTag for this phone number - home, work, etc (limited to 100 characters)
contactInfo.phones.phone (required)StringPhone number (limited to 30 characters)
contactInfo.phones.normalizedPhone (required)StringNormalized phone number
contactInfo.addressesArray[object]Contact's address
contactInfo.addresses.idNumberID of this address within the array
contactInfo.addresses.tag (required)StringTag for this address - home, work, etc (limited to 100 characters)
contactInfo.addresses.addressStringStreet address (limited to 250 characters)
contactInfo.addresses.neighborhoodStringNeighborhood (limited to 100 characters)
contactInfo.addresses.cityStringCity (limited to 100 characters)
contactInfo.addresses.regionStringRegion, such as a U.S. state or Canadian province (limited to 100 characters)
contactInfo.addresses.countryStringCountry (limited to 100 characters)
contactInfo.addresses.postalCodeStringPostal code (limited to 20 characters)
contactInfo.urlsArray[object]URLs associated with the contact, like Facebook or LinkedIn
contactInfo.urls.idNumberID of this URL within the array
contactInfo.urls.tag (required)StringTag for this URL - personal, Facebook, LinkedIn, etc (limited to 100 characters)
contactInfo.urls.url (required)StringThe URL
contactInfo.datesArray[object]Important dates for this Contact, like birthday
contactInfo.dates.idNumberID of this date within the array
contactInfo.dates.tag (required)StringTag for this date - birthday, anniversary, etc (limited to 100 characters)
contactInfo.dates.date (required)dateTimeThe date, as an ISO 8601 timestamp
contactInfo.onSuccess (required)FunctionAn on success callback that returns an object with this information:
{
Contact: the reconciled Contact,
isNew: boolean
details: {
rejectedData: [ DTO1, DTO2,... ]
existingData: [ DTO1, DTO2, ... ]
}
}
contactInfo.onFailureFunctionAn on failure callback

Value passed to callback:

An object containing the contact information and the rejected data:

NameTypeDescription
ContactObjectContains all the information we have for this contact, including the data your app sent. 
isNewBooleanIndicates if the contact was just created
detailsObjectContains more information about this contact, including any data that was rejected
details.rejectedDataArrayLists information sent by your app that was rejected (if any).
details.existingDataArrayLists the data we already had for this contact, before your app sent additional information.

Example:

var contactInfo = {
name: {first: "firstName", middle: "middleName", last: "lastName"},
emails: [{tag: "main", email: "email@gmail.com"}]
};
Wix.Contacts.reconcileContact(contactInfo,
function(ContactData) {
console.log(ContactData)
},
function(errorType) {
console.log(errorType)
}
);
JavaScript | Copy Code

Was this helpful?

Wix.Dashboard

closeWindow

Closes the modal endpoint.

SDK Version: SDK 1.27.0+
Display: Dashboard, Modal

Syntax:

closeWindow(\[message\])
JavaScript | Copy Code

Parameters:

NameTypeDescription
messageObjectA custom message to pass to the calling endpoint’s onClose callback function

Example:

var message = {"reason": "button-clicked"};
Wix.Dashboard.closeWindow(message);
JavaScript | Copy Code

getEditorUrl

Retrieves a URL for the app in the Editor. If your app is installed on more than one page, the first page that contains your app will be opened. If the user didn’t install the Site component yet, this will return a URL to the Wix Editor that will open the App Market with your app in pending.

SDK Version: SDK 1.33.0+
Display: Dashboard

Syntax:

getEditorUrl(callback)
JavaScript | Copy Code

Note:
This is only relevant for apps that have both a site component and a dashboard component.

Parameters:

NameTypeDescription
callback (required)FunctionCallback function to receive the URL that directs users to the app in the Wix Editor

Value passed to callback: The URL that directs users to the app in the Wix Editor. Note that:

  • If your app is installed on more than one page, the URL directs to the first page that contains your app.
  • If the user didn’t install the Site component yet, the URL directs to the App Market in the Wix Editor, with your app in pending.

Example:

Wix.Dashboard.getEditorUrl(function(url) {
//Editor url as a callback parameter
});
JavaScript | Copy Code

getProducts

Returns a json with pricing information for all of your app’s packages – premium plans and in-app purchase packages.

SDK Version: SDK 1.72.0+
Display: Dashboard

Syntax:

getProducts(onSuccess, \[onError\])
JavaScript | Copy Code

Parameters:

NameTypeDescription
onSuccess (required)FunctionA callback function to receive the pricing information
onErrorFunctionA callback function for when an error occurs

Example:

Wix.Dashboard.getProducts(OnSuccess, OnError);
//Here is an example of the response
"packages": [
{
"id": "Premium1",
"name": "Comments Premium Package",
"price": "4.95",
"is_active": true,
"freeMonth": true,
"currencyCode": "USD",
"currencySymbol": "US$"
"monthly": {
"price": "4.95",
“Link”: "https://premium.wix.com/wix/api/tpaStartPurchase?appInstanceId=aaa-bbb&appDefinitionId=a1a2a-b3b4b&paymentCycle=MONTHLY&vendorProductId=package1"
},
"yearly": {
"price": "3.97",
“Link”: "https://premium.wix.com/wix/api/tpaStartPurchase?appInstanceId=aaa-bbb&appDefinitionId=a1a2a-b3b4b&paymentCycle=YEARLY&vendorProductId=package2"
},
"oneTime": {
"price": "5.99",
“Link”: "https://premium.wix.com/wix/api/tpaStartPurchase?appInstanceId=aaa-bbb&appDefinitionId=a1a2a-b3b4b&paymentCycle=ONE_TIME&vendorProductId=package3"
},
"bestSellingFeature": "",
"discountPercent": 20
}
]
JavaScript | Copy Code

getSiteViewUrl

Retrieves the live site’s base URL.

SDK Version: SDK 1.74.0+
Display: Dashboard

Syntax:

getSiteViewUrl(onSuccess)
JavaScript | Copy Code

Parameters:

NameTypeDescription
onSuccess (required)FunctionA callback function to receive the base url object

Value passed to callback:

An object with the base URL of the live site. For example: {base : “http://www.wix.com”}

Example:

var onSuccess = function(data) {
// do something with base url
};
Wix.Dashboard.getSiteViewUrl(onSuccess);
JavaScript | Copy Code

openBillingPage

Allows the app to open the Wix billing page.

SDK Version: SDK 1.27.0+
Display: Dashboard

Syntax:

openBillingPage( )
JavaScript | Copy Code

Example:

Wix.Dashboard.openBillingPage();
JavaScript | Copy Code

openMediaDialog

This method opens the Wix Media Manager, which allows users to choose an existing item from the Wix media galleries or upload a new file.

SDK Version: SDK 1.27.0+
Display: Dashboard

Once the user selects a media item, a callback function returns a metadata descriptor with details about it.

To access the media item, use one of the Wix.Utils.Media.get* methods to construct the item’s full URL. You’ll need the item’s relativeUri, which is returned in the callback function.

Warning:
Use the Wix.Utils.Media.get* methods each time you access the media item, to prevent broken links.

Syntax:

openMediaDialog(mediaType, multiSelect, onSuccess, \[onCancel\])
JavaScript | Copy Code

Parameters:

NameTypeDescription
mediaType (required)Wix.Settings.MediaType.IMAGE,Wix.Settings.MediaType.BACKGROUND,Wix.Settings.MediaType.AUDIO,Wix.Settings.MediaType.SECURE_MUSIC, Wix.Settings.MediaType.DOCUMENT,Wix.Settings.MediaType.SWFType of media item the user is selecting: IMAGE (photo/image), BACKGROUND (background image), AUDIO (mp3 file up to 50MB), SECURE_MUSIC (high quality audio up to 360MB), DOCUMENT, SWF
multiSelect (required)Booleantrue if the user selected more than one item. false if the user selected only one item.
onSuccess (required)FunctionCallback function to pass metadata about this media item
onCancelFunctionCallback function called when the user cancels

Value passed to onSuccess callback:

An object or an array of objects (for multiple media items).

Each object contains metadata about a specific media item.

Example:

Wix.Dashboard.openMediaDialog(Wix.Settings.MediaType.IMAGE, false,
function(data) {
let imageurl = Wix.Utils.Media.getImageUrl(data.relativeUri);
}
);
JavaScript | Copy Code

openModal

Opens a lightbox-style modal window over your app in the Wix Dashboard. You can only open this modal from the Wix Dashboard.

SDK Version: SDK 1.27.0+
Display: Dashboard

Here’s how the modal works:

  • The modal is a singleton – every new modal closes the previous one.
  • Users can close the modal by clicking the lightbox or pressing the close button. You can close the modal by calling Wix.closeWindow from within the modal iframe.

Syntax:

openModal(url, width, height, \[onClose\], \[theme\])
JavaScript | Copy Code

Parameters:

NameTypeDescription
url (required)StringURL of the modal iframe
width (required)NumberWidth of the modal, in pixels (for example, 400)
height (required)NumberHeight of the modal, in pixels (for example, 400)
onCloseFunctionOnClose callback function
themeWix.ThemeThe style of the modal: Wix.Theme.DEFAULT - has the regular modal look & feel - border, shadow, close button. Wix.Theme.BARE - a simple modal with no border, close button, shadow, etc.

Example:

var onClose = function(message) { console.log("modal closed", message); }
Wix.Dashboard.openModal("https://static.parastorage.com/services/js-sdk/1.90.0/HTML/modal.HTML", 400, 400, onClose);
JavaScript | Copy Code

pushState

Enables AJAX style Page apps to inform the Wix platform about a change in the app internal state. The new state will be reflected in the site/page URL. Once you call the pushState method, the browser’s top window URL will change the ‘app-state’ path part to the new state you provide with the pushState method (similar to the browser history API). Read more about deep linking for a full explanation.

SDK Version: SDK 1.35.0+ Display: Dashboard

Syntax:

pushState(state)
JavaScript | Copy Code

Parameters:

NameTypeDescription
state (required)StringThe new app's state to push into the dashboard history stack

Example:

Wix.Dashboard.pushState("app-state");
JavaScript | Copy Code

revalidateSession

Verifies that the session is secure. If the session is secure, this method returns a newly-signed app instance.

SDK Version: SDK 1.52.0+
Display: Dashboard

Use this method before displaying sensitive information or performing an action that requires a secure session.

Syntax:

revalidateSession(onSuccess, \[onFailure\])
JavaScript | Copy Code

Parameters:

NameTypeDescription
onSuccess (required)FunctionReceives a newly-signed and encoded app instance
onFailureFunctionCallback function in case the session isn't secure

Example:

Wix.Dashboard.revalidateSession(
function(instanceData){
//handle success use-case
},
function(error){
//Handle error use-case
}
);
JavaScript | Copy Code

Deprecated

setHeight (height)

SDK Version: Deprecated

Requests the hosting Wix platform to change the iframe’s height inside the side dashboard

Parameters:

NameTypeDescription
height (required)NumberThe window's new height

Example:

Wix.Dashboard.setHeight(height);
JavaScript | Copy Code

Was this helpful?

Wix.Data.Public

Using Wix.Data.Public methods, you can store public data in the site’s HTML document. This means that you may not need an external database for your app.

How do you know if our solution is sufficient? Use these methods if:

  • Your app doesn’t need to store any sensitive information. Since the HTML document is public, make sure to only store information that’s displayed on the site.
  • Your app doesn’t need to store a lot of data (see the storage limitations below)

Wix.Data.Public methods are available in the Wix Editor and Viewer only – not in the Dashboard.

Storing data

Each data entry is stored as a pair – a key and its value. Keys must be strings, and values can be strings, json objects, numbers, integers, and booleans.

Let’s use Wix Hit Counter as an example. This app is a small widget that counts the number of site visitors.

So what kind of data would you store for this app?

  • Strings – the layout/design used for the counter
  • json objects – animation settings or another group of related settings (you can store them as an object instead of storing each string separately)
  • Integers & numbers – starting number for the hit counter
  • Booleans – whether to count all visits to the site, or only new visitors

Setting the data’s scope

When you store data, you also define its scope as “app” or “component” – this determines where your data is available. By default, data is only available for the component that called the method, as well as that component’s settings. To make the data available globally for all app components, set the scope to app.

Storage limits

You can store a certain amount of data in each scope:

  • Component scope (per compId): 400 characters in total, for all data in this scope – including spaces
  • App scope (per app instance ID): 1,000 characters in total, for all data in this scope – including spaces

set

Stores a key with a value. If the key already exists, the previous value is overwritten with the new value. If the key doesn’t exist yet, it’s created now.

SDK Version: SDK 1.61.0+
Display: New Editor
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Settings Panel, Modal, Popup, Worker (app scope only)

For example: In the Wix Hit Counter app, the counter starts at 1234 by default. When a user adds the app, you would store “startCounter” as the key, and “1234” as the key’s value. If a user changes it to 0, you would use the set method again to replace the value with “0”.

Syntax:

set(key, value, \[options\], onSuccess, \[onFailure\])
JavaScript | Copy Code

Parameters:

NameTypeDescription
key(required)StringKey to set. Each key must be unique within the given scope (see options, below).
value (required)Object/ String/ Boolean/ Integer/ NumberKey’s value.
optionsObjectOptions for this method
options.scope“APP” or “COMPONENT”Where the data is available: APP: All of the app’s components, COMPONENT (default): Only within this component and its settings
onSuccess (required)Function(result)Returns a json object with the key and value you set { key1: value1}
onFailureFunction(error)Errors thrown when: Your app exceeded the provided storage (1,000 characters for app scope, 400 for component scope), Invalid json

Example:

// Default setting for the startCounter field
Wix.Data.Public.set("startCounter", 1234, { scope: 'COMPONENT' },
function(d){ console.log(d) }, function(f) { console.log(f) }
);
// Once the user changes it to zero, set a new value for this key
Wix.Data.Public.set("startCounter", 0, { scope: 'COMPONENT' },
function(d) { console.log(d) }, function(f) { console.log(f) }
);
JavaScript | Copy Code

remove

Deletes the key. Future attempts to access this key will raise an exception until something is stored again for this key using the set method.

SDK Version: SDK 1.61.0+
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Settings Panel, Modal, Popup, Worker (app scope only)

For example: Let’s say that Wix Hit Counter shows text after the number (“2,000 visitors”). Users can choose whether or not to show text (a boolean), and define the text to display. If the user chooses to just show the number, without any text after it, you can use remove to delete the “text” key.

Syntax:

remove(key, \[options\], onSuccess, \[onFailure\])
JavaScript | Copy Code

Parameters:

NameTypeDescription
key (required)StringKey to remove
optionsObjectOptions for this method
options.scope“APP” or “COMPONENT”The data's scope: APP: All of the app’s components, COMPONENT (default): Only within this component and its settings
onSuccess (required)Function(data)Returns a json object of the removed data: { key1: value1}
onFailureFunction(error)Error is thrown when the key doesn’t exist

Example:

Wix.Data.Public.remove('text', {scope:'COMPONENT'}, function(d) {console.log(d)}, function(f){console.log(f)});
JavaScript | Copy Code

get

Returns the value for a given key.

SDK Version: SDK 1.61.0+
Editor Version: New Editor
Components: Live Site, Widget, Pinned (aka Fixed-Position) Widget, Page, Settings Panel, Modal, Popup, Worker (app scope only)

For example, call this method when the iframe loads to display the app with the settings the user chose.

Syntax:

get(key, \[options\], onSuccess, \[onFailure\]) 
JavaScript | Copy Code

Parameters:

NameTypeDescription
key (required)StringKey to get
optionsObjectOptions for this method
options.scope“APP” or “COMPONENT”Where the data is available: APP: All of the app’s components, COMPONENT (default): Only within this component and its settings
onSuccess (required)Function(data)Returns a json object { key1:value1}
onFailureFunction(error)Error is thrown when the key doesn’t exist

Example:

Wix.Data.Public.get("startCounter", { scope: 'COMPONENT' }, function(d){console.log(d)}, function(f){console.log(f)});
JavaScript | Copy Code

Deprecated

Wix.Data.Public.getMulti – deprecated in SDK version 1.62.0

Was this helpful?

Wix.Features

isSupported

Checks if a feature is available for use. The feature name must be one of Wix.Features.Types listed below.

SDK Version: SDK 1.45.0+
Editor Version: New Editor
Display: Preview
Components: Wix Dashboard, Dashboard, Widget, Pinned (aka Fixed-Position) Widget, Page, Settings Panel, Settings Modal

Syntax:

isSupported(feature, callback)
JavaScript | Copy Code

Parameters:

NameTypeDescription
feature (required)Wix.Features.TypesSpecify one of the following features: PREVIEW_TO_SETTINGS (see openSettingsDialog), ADD_COMPONENT (see addComponent), RESIZE_COMPONENT (see resizeComponent)
callback (required)FunctionReturns true via callback if the feature is available for use.

Example:

Wix.Features.isSupported(Wix.Features.Types.RESIZE_COMPONENT, function(data) {console.log(data)})
JavaScript | Copy Code

Was this helpful?

Wix.Preview

openSettingsDialog

Ends Preview mode and sends Wix users directly from their site’s preview to the App Settings panel in the Editor.

SDK Version: SDK 1.45.0+
Display: Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page

When called with no options, uses the Widget or Page that called the method.

Syntax:

openSettingsDialog(\[options\], \[onFailure\])
JavaScript | Copy Code

Parameters:

NameTypeDescription
options ObjectSpecify the component to open the settings panel for. 
options.compIdStringThe component to open the settings panel for. 
onFailureFunctionCallback is invoked when the he user cancels opening the settings panel or the specified component information is incorrect.

Example:

Wix.Preview.openSettingsDialog();
JavaScript | Copy Code

Was this helpful?

Wix.PubSub

publish

Broadcasts an event to other Site components of a multicomponent app. If the app’s Site components span multiple pages, they will be notified when they are rendered.

SDK Version: SDK 1.25.0+
Editor Version: New Editor, Old Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Note:
For the Worker component, use the Worker.PubSub.publish method instead.

Syntax:

publish(eventName, data, isPersistent)
JavaScript | Copy Code

Parameters:

NameTypeDescription
eventName (required)StringThe name of the event to publish
data (required)ObjectThe object to send to subscribers for this event type
isPersistent (required)BooleanIndicates whether this event is persisted for event subscribers who have not yet subscribed

Example:

// The following call publishes an app event.
// Apps components that are subscribed to this event will receive it when they are rendered.
Wix.PubSub.publish("my_event_name", {value: "this is my message"}, true);
JavaScript | Copy Code

subscribe

Subscribes to events from other site components of a multicomponent app. If the components span multiple pages, they will be notified once they are rendered. It is also possible to receive all notifications prior to rendering by specifying a flag when subscribing to events. If the flag is set, the component will be notified immediately of any prior events of the type it is registered to receive.

SDK Version: SDK 1.25.0+
Editor Version: New Editor, Old Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Note:
For the Worker component, use the Worker.PubSub.subscribe method instead.

Syntax:

subscribe(eventName, callBack, \[receivePastEvents\])
JavaScript | Copy Code

Parameters:

NameTypeDescription
eventName (required)String The name of the event to subscribe to
callBack (required)FunctionFunction that will respond to events sent from other components of the broadcasting app. It will be given the event object itself and the source of the event
receivePastEventsBooleanA flag to indicate that all past instances of the registered event should be sent to registered listener. This will happen immediately upon registration.

Example:

//subscribe and then unsubscribe to "my_event_name" event
Wix.PubSub.subscribe("my_event_name", function(event) {
// process the event which has the following format:
// {
// name: eventName,
//     data: eventData,
//     origin: compId
// }
});
// subscribe to "my_event_name" event, events which also happened before this component was rendered will send
Wix.PubSub.subscribe("my_event_name", function(event) { }, true);
JavaScript | Copy Code

unsubscribe

Unsubscribes from receiving further events. The id from the initial subscribe call is used to unsubscribe from further notifications.

SDK Version: SDK 1.25.0+
Editor Version: New Editor, Old Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

unsubscribe(eventName, function)
JavaScript | Copy Code

Parameters:

NameTypeDescription
eventName (required)String The name of the event to unsubscribe from
function (required)Function The function that will respond to events sent from other extensions of the broadcasting app. It will be given the event object itself and the source of the event.

Example:

//subscribe and then unsubscribe to "my_event_name" event
var id = Wix.PubSub.subscribe("my_event_name", function(event) { });
Wix.PubSub.unsubscribe("my_event_name", id);
JavaScript | Copy Code

Was this helpful?

Wix.Settings

addComponent

Allows users to install add-ons in your app, directly from the App Settings panel. Users are then directed to the page where the component was added.

SDK Version: SDK 1.92.0+
Editor Version: New Editor
Components: Settings Panel, Settings Modal

Use this method for add-ons that aren’t added automatically when users install your app, or to allow users to add a page component again. Note that for page components, you need to first allow users to add your page component more than once.

Syntax:

addComponent(options, onSuccess, \[onFailure\])
JavaScript | Copy Code

Parameters:

NameTypeDescription
options (required)ObjectOptions for this method
options.copyStyleBooleanTo copy the style from another component in your app, set true. You can copy the style as follows: To copy the style of the calling component, leave styleId empty. To copy the style of another component in your app, enter its styleId below.
options.styleIdStringID of the style to copy. Make sure copyStyle is set to true. If the styleId is invalid, no style will be copied.
options.componentType (required)"WIDGET" or "PAGE"Type of component to add
options.widgetObjectDetails about the widget and where to add it
options.widget.widgetId (required)StringID of the widget, as specified in the Dev Center
options.widget.allPagesBooleanTrue if the user is adding the widget to all pages. Default is False. If the value is True and you also specify the wixPageId (below), then allPages takes precedence and the component is added to all pages.
options.widget.wixPageIdStringID of the page where the user is adding the widget. If a value is given and the value of allPages (above) is True, then allPages takes precedence and the component is added to all pages. The user is directed to this page once the widget is added.
options.pageObjectDetails about the page component. Make sure that you allow users to add your page component more than once.
options.page.titleStringThe title of the page. If undefined, uses the component name defined in the Developers Center. Title is limited to 40 characters, and cannot include ‘<’ or ’>’ characters.
options.page.pageId (required)StringID of the page component, as specified in the Developers Center
options.page.isHiddenBooleantrue if this is a hidden page. Default is false.
onSuccess (required)FunctionReceives the widget's compId
onFailureFunctionReceives the error if the operation failed. WIDGET](#1470038924639-675076e3-d3bd), PAGE

WIDGET EXAMPLE

Wix.Settings.addComponent(
{
componentType: 'WIDGET',
copyStyle: true,
widget: {widgetId: 'minicart'}
},
function(x) {
console.info(x)
},
function(x) {
console.error(x)
}
)
JavaScript | Copy Code

PAGE EXAMPLE

Wix.Settings.addComponent(
{
componentType: 'PAGE',
page: {pageId:'menu'}
},
function(x) {
console.info(x)
},
function(x) {
console.error(x)
}
)
JavaScript | Copy Code

closeWindow

Closes the settings/modal endpoint.

SDK Version: SDK 1.83.0+
Editor Version: New Editor
Components: Settings Panel, Settings Modal

Syntax:

closeWindow(\[options\])
JavaScript | Copy Code

Parameters:

NameTypeDescription
optionsObjectOptions for this method. Note: The options object is only passed to the opener's onClose callback function if you're closing the modal (target: 'MODAL') - refer to Wix.Settings.openModal.
options.target‘SETTINGS’, ‘MODAL’, ‘ALL’Specifies the endpoint to close: ‘SETTINGS’ - closes the settings endpoint. ‘MODAL’ (default) - closes the settings modal and passes the options object to the opener's onClose callback function (refer to Wix.Settings.openModal). ‘ALL’ - closes both the settings and the settings modal.
options.customObject/ String/ Boolean/ NumberA custom parameter

Example:

var custom = {"reason": "button-clicked"};
Wix.Settings.closeWindow({target: 'ALL', custom});
JavaScript | Copy Code

getCurrentPageAnchors

Retrieves the anchors on the current page.

SDK Version: SDK 1.62.0+
Editor Version: New Editor

Syntax:

getCurrentPageAnchors(callback)
JavaScript | Copy Code

Parameters:

NameTypeDescription
callback (required)FunctionCallback function to receive an array of anchors (unordered)

Value passed to callback:

An array of unordered objects. 

Each object represents an anchor on the current page, and contains the following properties:

NameTypeDescription
idStringThe anchor ID
titleStringThe anchor title.

Note: If there are no anchors on the current page, returns just one default anchor – the top of the page.

Example:

Wix.Settings.getCurrentPageAnchors(function(anchors) {
// do something with anchors
});
JavaScript | Copy Code

getCurrentPageId

Returns the page ID of the current page.

SDK Version: SDK 1.86.0+
Editor Version: New Editor
Components: Settings Panel, Settings Modal

Syntax:

getCurrentPageId(callback)
JavaScript | Copy Code

Parameters:

NameTypeDescription
callback (required)FunctionCallback function to receive the pageId

Example:

Wix.Settings.getCurrentPageId(function(pageId) {
//store the site pageId
});
JavaScript | Copy Code

getDashboardAppUrl

Retrieves the URL of your app’s Dashboard component within the user’s site (the URL is fully qualified). Use this URL to direct the user from the App Settings to your app’s Dashboard component.

SDK Version: SDK 1.32.0+
Editor Version: New Editor, Old Editor
Components: Multicomponent Apps

To open your Dashboard as a modal in the Wix Editor, use Wix.Settings.openModal.

Important:
To open your Dashboard component, add an href attribute with the Dashboard URL. Don’t use window.open – if you use window.open in a callback of an asynchronistic call, the browser blocks the window from opening.

Syntax:

getDashboardAppUrl(callback)
JavaScript | Copy Code

Parameters:

NameTypeDescription
callback (required)FunctionA callback function to receive the URL of the app in the dashboard

Example:

Wix.Settings.getDashboardAppUrl(function(url) {
// do something with the URL
});
JavaScript | Copy Code

getSiteInfo

Retrieves information about the host site in which the app is shown.

SDK Version: SDK 1.12.0+
Editor Version: New Editor, Old Editor

Syntax:

getSiteInfo(callback) 
JavaScript | Copy Code

Parameters:

NameTypeDescription
callback (required)FunctionCallback function to receive the site info 

Value passed to callback:

json Object containing the site info:

NameTypeDescription
baseUrl String Base url of the current site, for example: http://user.wix.com/site-name, http://www.domain.com
pageTitle String The page title that is used for SEO. This title includes both the site and page title (e.g., “My Store - Animal Shirt”).
pageTitleOnlyStringThe name of the page - without the site title (e.g., “Animal Shirt”).
referrer String The referrer header of the HTTP request 
siteDescriptionString The description of the site that is used for SEO 
siteKeywordsString The keywords which are related to the site and are used for SEO 
siteTitle String The title of the site that is used for SEO 
url String The URL (taken from the location.href property). The URL includes the internal site state, for example: http://user.wixsite.com/site-name/pageTitle http://www.domain.com/pageTitle . Returns the site URL only when using getSiteInfo in the live site and preview mode. When using it in Editor mode, returns the Editor URL.

Example:

Wix.Settings.getSiteInfo(function(siteInfo) {
// do something with the siteInfo
});
JavaScript | Copy Code

getSiteMap

Returns all items in the site structure, including:

  • Items in the site’s menu – pages (including subpages), links, and menu headers.
  • Hidden pages – pages that are in the site, but not in the site menu. For example, a “Thank You” page that’s shown only after a site visitor makes a purchase.

SDK Version: SDK 1.81.0+
Editor Version: New Editor
Components: Settings Panel

Note:
Use this method instead of getSitePages, which is now deprecated.

Syntax:

getSiteMap(callback)
JavaScript | Copy Code

Parameters:

NameTypeDescription
callback (required)FunctionCallback function to receive the site structure

Value passed to callback:

An array of objects, where each object represents an item in the site structure.

Warning:
To use this object later (for example, if you want to navigate to a link on the user’s site), save this object in your database as is – don’t change it in any way.

Each object contains data about the item. The data sent depends on the item – check out our examples below.

NameTypeDescription
typeStringType of link the item represents - for example ‘PageLink’ or ‘AnchorLink’. The data returned depends on the item - for example, an ‘AnchorLink’ object will include the anchorName and anchorDataId properties. Check out our examples below.
pageIdStringThe page ID. Note: If the user added a page anchor to the site’s menu, then this method returns an object for the anchor - so there might be multiple objects with the same page ID.
titleStringThe item title
hiddenBooleanReturns true if this page is hidden
isHomePageBooleanReturns true if this page is the site's home page
urlStringURL of this item
subPagesArray [objects](Page objects only) If the page has subpages, returns an ordered set of subpages. Each subpage object contains more information about the subpage (id, title, hide, isHomePage, url).

Here’s an example of an array passed to the callback:

[
{
"type": "PageLink",
"pageId": "#c1dmp",
"title": "HOME",
"hidden": false,
"isHomePage": true,
"url": "http://site.wixsite.com/name-dp"
},
{
"type": "PageLink",
"pageId": "#kyck4",
"title": "Page",
"hidden": false,
"isHomePage": false,
"url": "http://site.wixsite.com/name-dp/page"
},
{
"type": "AnchorLink",
"anchorName": "Anchor",
"anchorDataId": "#dataItem-iyk5xcst",
"pageId": "#c1dmp",
"title": "anchor link",
"hidden": false,
"isHomePage": true,
"url": "http://site.wixsite.com/name-dp"
},
{
"type": "ExternalLink",
"target": "_blank",
"url": "http://google.com",
title": "external",
"hidden": false
},
{
"type": "EmailLink",
"recipient": "site@a.com",
"subject": "dffg",
"title": "email",
"hidden": false
},
{
"type": "PhoneLink",
"phoneNumber": "123544216142",
"title": "phone",
"hidden": false
},
{
"type": "DocumentLink",
"docId": "7a9325_da6cc4b5cb65468bafbd937a9133aed0.pdf",
"name": "file.pdf",
"title": "document",
"hidden": false,
"url": "http://media.wix.com/ugd/7a9325_da6cc4b5cb65468bafbd937a9133aed0.pdf"
},
{
"type": "DynamicPageLink",
"routerId": "routers-iympnnog",
"innerRoute": "fgfg",
"title": "dynamic page",
"hidden": false
},
{
"type": "MenuHeader",
"title": "Menu Header",
"hidden": false,
"subPages": [
{
"type": "PageLink",
"pageId": "#rsdvc",
"title": "New Page",
"hidden": false,
"isHomePage": false,
"url": "http://site.wixsite.com/name-dp/new-page"
}
]
}
]
JSON | Copy Code

Example:

Wix.Settings.getSiteMap(function(siteMap) {
// do something with the site pages
});
JavaScript | Copy Code

getStateUrl

This method returns the full URL of one of your inte