Skip to end of metadata
Go to start of metadata

 

Overview

The Javascript SDK exposes a set of functions that enables the app to communicate with the Wix platform - site or editor.

Including The Library

In order to use the SDK you must include the following script tag in your HTML document head:

SDK Script Tag

The // at the beginning of the src attribute denotes to the browser to use http or https according to the containing page. It's not a typo... (smile)

Once included, your window object will contain a new global Object named Wix from which you could call functions that are used to notify the host site of events in the app.

Version

The Javascript SDK is always version-ed. To load a specific version of the SDK you have to change the path appropriately by replacing the version part to the version number you need.

Structure/Scope

The Wix Object can be used in all the app's endpoints - widget, page, modal and settings. However, some of it's functions make sense only in certain endpoints. The most obvious distinction is the Settings endpoint. 

The Settings endpoint is different since it is the only endpoint that resides in the Wix Editor while the others reside in Wix site. For that reason we created a sub-object Wix.Settings that holds all the function that are valid in the Settings endpoint.

Another special sub-object is the Wix.Util. It provides utility functions that can be called by all endpoints.

 

The table below summaries the scope of the Wix functions and it's sub-objects in different endpoints: 

call \ endpointsettingswidgetpagemodalpopupfixed widgetdashboardworker
Wix.*-+++++--
Wix.PubSub.*-+++++--
Wix.Settings.*+-------
Wix.Utils.*+++++++-
Wix.Styles.*++++++--
Wix.Dashboard.*------+-
Wix.Activities.*-+++++--
Wix.Worker.*-------+
Wix.Contacts.*------+-

Although Wix.Utils.* is valid for all endpoints, if the called function doesn't have a meaningful value to return it will return null. E.g Wix.Utils.getOrigCompId() will return null in widget/page/modal and return the original component id in the settings endpoint.

Reference 

reportHeightChange (Deprecated - use Wix.setHeight)

Since 1.8.0

This method requests the hosting Wix platform to change the iframe height inside the site/editor.

Syntax
reportHeightChange
Arguments
 nametypedescription
1heightNumber
an integer that represents the desired height in pixels.

setHeight

Since 1.22.0

This method requests the hosting Wix platform to change the iframe height inside the site/editor.

Syntax
setHeight
Arguments
 nametypedescription
1heightNumber
an integer that represents the desired height in pixels.

 


pushState

Since 1.8.0

This method enable 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 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).

For a full explanation of how deep-linking works with AJAX style apps, see Deep Linking for AJAX Style Apps.

Syntax
pushState

Arguments

 nametypedescription
1stateString

new app's state to push into the editor history stack

 


getSiteInfo

Since 1.3.0

The getsiteInfo method is used to retrieve information about the host site in which the app is shown.

Syntax
getSiteInfo
Arguments
 nametypedescription
1callbackFunction

a callback function to receive the site pages. The function signature should be :
function onSuccess(siteInfo) {...}

Returns
  • This is an asynchronous function, the returned value is passed in the onSuccess callback function.

(Object) JSON containing the site info. It's properties are: 

 nametypedescription
1siteTitleStringthe title of the site that is used for SEO
2pageTitleStringthe site current page title that is used for SEO
3siteDescriptionStringthe description of the site that is used for SEO
4siteKeywordsStringthe keywords which were related to the site and are used for SEO
5referrerStringthe referrer header of the http request
6urlString

the full url taken from the location.href, include internal site state, for example: http://user.wix.com/site-name#!pageTitle/pageId, http://www.domain.com#!pageTitle/pageId

7baseUrlString

base url of the current site, for example: http://user.wix.com/site-name, http://www.domain.com

 


getSitePages

Since 1.17.0

The getSitePages method is used to retrieve the site structure from the hosting Wix Platform. The site structure includes visible and hidden pages as well as sub pages.

Syntax
getSitePages
Arguments
 nametypedescription
1callbackFunction

a callback function to receive the site info. The function signature should be :
function onSuccess(sitePages) {...}

Returns
  • This is an asynchronous function, the returned value is passed in the onSuccess callback function.

(Array) containing an ordered set of the site pages. A single page description contains the following properties: 

 nametypedescription
1idStringthe page id
2titleStringthe page title
3hideBooleana flag indicating if the page is hidden
4subPages(optional)ArrayAn ordered set of sub pages
Example
Site Pages

 


getStyleParams (Deprecated - use Wix.Styles.getStyleParams)

Since 1.22.0

The getStyleParams method is used to retrieve the style parameters from the hosting Wix Platform. The parameters includes colors numbers, booleans.

Syntax
getSitePages
Arguments
 nametypedescription
1callbackFunction

a callback function to receive the style parameters. The function signature should be :
function callback(styles) {...}

Returns
  • This is an asynchronous function, the returned value is passed in the onSuccess callback function.

 


navigateToPage

Since 1.17.0

The navigateToPage method is used to navigate to a specific page inside the editor/preview/site. The function accepts a single argument, page id, which is retrieved by using the method Wix.getSitePages()

Syntax
navigateToPage
Arguments
 nametypedescription
1pageIdString

a string representing the page id target

 


requestLogin

Since 1.6.0

This method is part of Wix Site Members feature. To use it a manual provisioning is required by the Wix team, contact apps@wix.com to enable it for your app.

 This method is relevant for live sites and not from the App Settings. The method requests the current site visitor of the Wix site to log-in or register. After a successful log-in, the Wix site will reload including the app iframe and the new signed-instance parameter will contain the details of the logged in user. 

The method has an affect only for a published site. If called in the Wix editor, the method has no affect. 

Syntax
requestLogin
Arguments
 nametypedescription
1callbackFunction

a call back function to receive the current member details. The function signature should be :
function onSuccess(memberDetails) {...}

Returns
  • This is an asynchronous function, the returned value is passed in the onSuccess callback function.

(Object) JSON containing the user's details. It's properties are: 

 nametypedescription
1nameStringthe current member's name
2emailString

the current member's email

3idStringthe current member's id
4ownerBooleanindicates if the user is the owner of the site

 


currentMember

Since 1.6.0

This method is part of Wix Site Members feature. To use it a manual provisioning is required by the Wix team, contact apps@wix.com to enable it for your app.

This method is relevant for live sites and not from the App Settings. This method returns the details of the current site visitor that is logged into the Wix site, using the Wix site member options 

Syntax
Arguments
 nametypedescription
1callbackFunction

a call back function to receive the current member details. The function signature should be :
function onSuccess(memberDetails) {...}

Returns
  • This is an asynchronous function, the returned value is passed in the onSuccess callback function.

(Object) JSON containing the user's details. It's properties are: 

 nametypevalue
1nameStringthe current member's name
2emailString

the current member's email

3idStringthe current member's id
4ownerBooleanindicates if the user is the owner of the site

 


addEventListener

Since 1.11.0 

The addEventListener method lets the App listen to events that happens inside the editor/site.

The events that you can currently listen to are:

EventEvent DataDescription
EDIT_MODE_CHANGE
{editMode: 'editor' or 'preview'}issued when a site owner toggles between preview and edit mode in the Wix Editor

PAGE_NAVIGATION_CHANGE(deprecated)

{}issued when a user navigates (in editor, preview or viewer) to the page where the TPA component (Widget/Page) is
PAGE_NAVIGATION
issued on any page navigation within the Wix site
PAGE_NAVIGATION_IN
issued on any page in navigation within the Wix site. This event is a utility event on top of the 
PAGE_NAVIGATION event
PAGE_NAVIGATION_OUT
issued on any page out navigation within the Wix site. This event is a utility event on top of the 
PAGE_NAVIGATION event
SCROLL

 Issued when scroll happens inside the site (not when it happen inside the app iframe). The event data contains multiple details that helps the app determine it's behaviour considering it's position in the site, the browser window dimensions, and the scrolling state:

nametypedescription
Numbersite's scroll position on the y axis
site's scroll position on the x axis
site's document height
site's document width
xapp offset within the site's page on the x axis (doesn't change) 
yapp offset within the site's page on the y axis (doesn't change)
app width
app height
leftapp top-left offset,within the viewport, from the left
bottomapp top-left, offset within the viewport, from the bottom
rightapp top-left, offset within the viewport, from the right
topapp top-left, offset within the viewport, from the top


COMPONENT_DELETED
{}issued when the site owner deletes (in editor) a TPA component (Widget/Page)
SITE_PUBLISHED
{}issued when the site owner publishes the site (in editor)
SETTINGS_UPDATED
Custom JSONissued by the Settings endpoint when new settings are applied by the site owner
STATE_CHANGED
{newState: 'state'}issued when the site state changed
Syntax
addEventListener
Arguments
 nametypedescription
1Event typeWix.Events
unique event identifier, see the full list below
2Event handler functionFunction a javascript callback function that will get called by the SDK once an event occur

About COMPONENT_DELETED

Note that even though that the user will see the widget deleted immediately, the deletion itself will be delayed so that the app iframe can respond to the delete event. Your code should make the minimum steps required to perform state preserving, if any - AJAX, cookie, local storage, etc - before the component is deleted.

Returns

(Number) an id that can be used to remove the event listening using Wix.removeEventListener(eventName, id)


removeEventListener

Since 1.25.0 

The removeEventListener method allows to remove previously assigned event listeners that were specified using Wix.addEventListener

Syntax
addEventListener
Arguments
 nametypedescription
1Event typeWix.Events
unique event identifier, see the above
2callbackOrIDFunction/Number

a javascript callback function that was used with addEventListener or an id returned by addEventListener

 


openModal

Since 1.16.0

The openModal method allows an app to open a modal window within the site or preview. A modal is a runtime Widget that is not part of the site structure. The modal window is a singleton (every new modal closes the previous one) and contains a lightbox. A modal can be dismissed by the user if it touches the lightbox, presses the closing button or by the app itself if it calls the Wix.closewindow() from within the modal iframe. The onClose argument can be used to detect modal close.

Syntax
openModal
Arguments
 nametypedescription
1urlString

the modal iframe url

2widthNumberthe modal window width
3heightNumberthe modal window height
4onClose (Optional)Functionon close callback function

 


openPopup

Since 1.17.0

The openPopup method allows an app to open a popup window within the site or preview. A popup is a runtime Widget that is not part of the site structure. Unlike the modal, a popup is not a singleton and doesn't present a lightbox. A popup can also be positioned by the caller. We currently support a predefined set of positions that can be used when opening a popup. A popup is dismissed by the user if he presses the close button or by the app itself if it calls the Wix.closewindow() from within the popup iframe. The onClose argument can be used to detect modal close.

Popup positioning

A popup position is determined by two properties, it's position origin and it's position placement.

A position origin determines the origin point (x,y) which will be used to apply the position placement. The position origin is defined under Wix.WindowOrigin and can have the following values 

namedescription
RELATIVERelative position. The popup will be placed relative to the opening widget (Not supported for Page)
FIXEDFixed position. The popup will be placed inside the browser viewport
ABSOLUTE (Since 1.28.0)Absolute position. The popup will be placed relative to a given x,y coordinates that their origin is the top-left corner of the widget

A position placement is a predefined set of locations when a popup will be placed. The placement values are valid for Wix.WindowOrigin.FIXEDWix.WindowOrigin.ABSOLUTE and Wix.WindowOrigin.RELATIVE origins but mapped to a different positions on the screen.

The position placement is defined under Wix.WindowPlacement and can have the following values:


namedescription
TOP_LEFTtop left placement
TOP_RIGHTtop right placement
BOTTOM_RIGHTbottom right placement
BOTTOM_LEFTbottom left placement
TOP_CENTERtop center placement
CENTER_RIGHTcenter right placement
BOTTOM_CENTERbottom center placement
CENTER_LEFTcenter left placement
CENTER(FIXED origin only) center of the screen
Syntax
openPopup
Arguments
 nametypedescription
1urlString

the popup iframe url

2widthNumberthe modal window width
3heightNumberthe modal window height
4positionObject
nametypedescription
origin
Wix.WindowOrigin
the popup window position origin, can be relative to the opening widget or fixed to the viewport. A Page app can use only
placement
Wix.WindowPlacement
popup window placement, see the
xNumber(Optional, use with Wix.WindowOrigin.ABSOLUTE only) where popup should be opened horizontally relative to the top-left corner of the widget, default is set to 0.
yNumber(Optional, use with Wix.WindowOrigin.ABSOLUTE only) where popup should be opened vertically relative to the top-left corner of the widget, defaults is set to 0.
5onClose (Optional)Functionon close callback function
6themeTheme enumthe popup window theme, one of Wix.Theme.* values. Wix.Theme.DEFAULT is used for regular popup look & feel - border, shadow, close button. Wix.Theme.BARE is used for no decorations at all
Examples
  1. Options for positioning a popup while the origin property is set to 'FIXED'

2. Options for positioning a popup while the origin property is set to 'RELATIVE'

3. Example for positioning a popup in an 'ABSOLUTE' position, with x=25, y=10 and 'BOTTOM_RIGHT'

 

In a RELATIVE or ABSOLUTE origin, there is a chance that the requested popup can not fit in the desired position since it's size exceeds the margin between the opening Widget and the screen size. A WIdget position is determined by site owners when they build their sites while the Widget is not aware to it's position in the site. When the Wix Platform render popups, it calculates if a popup in the requested size can fit the requested position. If not, the Wix Platform will default the position to {origin: Wix.WindowOrigin.FIXED, placement: Wix.WindowPlacement.CENTER}, A.K.A the center of the screen.

 


closeWindow

Since 1.16.0

The closeWindow method is available only under a modal/popup endpoints (will not have any effect for other endpoints). It allows the modal to close itself programmatically.

Syntax
closeWindow
Arguments
 nametypedescription
1message (Optional)Object

a custom message object to pass to the opener's onClose callback function

 


resizeWindow

Since 1.19.0

The resizeWindow method is valid only for fixed position widgets. It re-sizes the widget window.

Syntax
closeWindow
Arguments
 nametypedescription
1widthNumber

window width in pixels

2heightNumberwindow height in pixels
3onCompleteFunctionon resize complete callback function

scrollTo

Since 1.19.0

The scrollTo method will perform a scroll to a fixed position in the app's hosting site window exactly as the standard method do.

Syntax
closeWindow
Arguments
 nametypedescription
1xNumber

The coordinate to scroll to, along the x-axis

2yNumberThe coordinate to scroll to, along the y-axis

 


scrollBy

Since 1.19.0

The scrollBy method will perform a scroll by the specified number of pixels in the app's hosting site window exactly as the standard method do.

Syntax
closeWindow
Arguments
 nametypedescription
1xNumber

ow many pixels to scroll by, along the x-axis (horizontal)

2yNumberHow many pixels to scroll by, along the y-axis (vertical)

 


getBoundingRectAndOffsets

Since 1.26.0

The getBoundingRectAndOffsets method returns the app's component bounding rect and site's offset

Syntax
closeWindow
Arguments
 nametypedescription
1callbackFunction

a callback function to receive the app bounding rect and offsets. The function signature should be :
function callback(data) {...}

where data has the following format:

Returns
  • This is an asynchronous function, the returned value is passed in the callback function.

getCurrentPageId

Since 1.31.0

The getCurrentPageId method returns the page id of the app hosting page.

Syntax
getCurrentPageId

 


Styles.getStyleParams

Since 1.26.0

The getStyleParams method is used to retrieve the style parameters from the hosting Wix Platform. The parameters includes colors numbers, booleans.

Syntax
getSitePages
Arguments
 nametypedescription
1callbackFunction

a callback function to receive the style parameters. The function signature should be :
function callback(styles) {...}

Returns
  • This is an asynchronous function, the returned value is passed in the onSuccess callback function.

PubSub.publish

Since 1.25.0 

Broadcasts an event to other extensions of a multi-widget TPA. If the app extensions (Widget, Fixed Positioned Widget, Page) span multiple pages, they will be notified when they are rendered.

Syntax
closeWindow
Arguments
 
name
type
description
optional
1
eventName
String

the name of the event to publish

No
2dataObjectdata the object to send to subscribers for this event typeNo
3isPersistentbooleanIndicates whether this event is persisted for event subscribers who have not yet subscribedYes

PubSub.subscribe

Since 1.25.0 

Subscribes to events from other app parts of a multi-widget TPA.  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 widget will be notified immediately of any prior events of the type it is registered to receive.

Syntax
closeWindow
Arguments
 
name
type
description
optional
signature
1
eventName
String

the name of the event to subscribe to.

Yes 
2callBackFunctionfunction 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 eventNofunction(event, eventName, source)
3receivePastEventsbooleana flag to indicate that all past instances of the registered event should be sent to registered listener. This will happen immediately upon registrationYes 
Returns

(Number) a subscription id that can be used to remove the event subscription using PuSub.unsubscribe(eventName, id)


PubSub.unsubscribe

Since 1.25.0 

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

Syntax
closeWindow
 
Arguments
 
name
type
description
optional
signature
1
eventName
String

the name of the event to unsubscribe from. 

No 
2
callBackOrId
Function/Numberfunction 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 eventNofunction(event, eventName, source)

Utils.getCompId

Since 1.12.0 

This method returns a String which represents the Widget/Page/Settings iframe's component id.

Syntax
Utils.getCompId
Returns

(String) the Widget/Page/Settings iframe's component id.


Utils.getOrigCompId

Since 1.12.0 

This method returns for valid endpoints (Settings only), a String which represents the Widget/Page iframe's component id which opened the App Settings panel.

Syntax
Utils.getOrigCompId
Returns

(String) the Widget/Page iframe's component id which opened the App Settings panel, if not exist returns null.


Utils.getViewMode

Since 1.12.0 

This method returns a String which represents the current view mode.

Syntax
Utils.getViewMode
Returns

(String) the current view mode (editor/preview/site/standalone).


Utils.getDeviceType

Since 1.21.0 

This method returns a String which represents the current device type

Syntax
Utils.getViewMode
Returns

(String) the current device type (desktop/mobile).


Utils.getWidth

Since 1.12.0 

This method returns a Number which represents the Widget/Page/Settings iframe's width.

Syntax
Utils.getWidth
Returns

(Number) the Widget/Page/Settings iframe's width


Utils.getCacheKiller

Since 1.12.0 

This method for valid endpoints (Widget/Page) returns a String which is the cacheKiller query parameter.

Syntax
Utils.getCacheKiller
Returns

(String) the cacheKiller query parameter, if not exist returns null.


Utils.getTarget

Since 1.12.0 

This method for valid endpoints (Widget/Page) returns a String which is the target query parameter (for the section-url).

Syntax
Utils.getTarget
Returns

(String) the target query parameter, if not exist returns null.


Utils.getSectionUrl

Please note: The parameter "section-url" here refers to the Page app URL.

Since 1.12.0 

This method is valid for Page endpoint only. It returns a String which is the section-url query parameter.

Syntax
Utils.getSectionUrl
Returns

(String) the section-url query parameter, if not exist returns null.


Utils.getLocale

Since 1.16.0 

This method for valid endpoints (Widget/Page/Settings) returns a String which represents the current locale of the site/editor. A locale is an abbreviated language tag that defines the user's language, country and any special variant preference of the user interface (e.g. Number format, Date format, etc.).

Syntax
Utils.getLocal
Returns

(String ) a standard IETF language tag - en (English), es (Spanish), fr (Franch), it (Italian), etc.


Utils.getInstanceId

Since 1.12.0 

This method returns a String which represents the app instance Id.

Syntax
utils.getInstanceId
Returns

(String) an app instance id - a GUID like value (decoded property of the instance query parameter) 


Utils.getUid

Since 1.12.0 

This method returns a String which represents the user identifier.

Syntax
Util.getUid
Returns

(String) a user identifier (decoded property of the instance query parameter).


Utils.getPermissions

Since 1.12.0 

This method returns a String which represents the user's permissions (decoded property of the instance query parameter).

Syntax
Utils.getPermissions
Returns

(String) user's permissions (decoded property of the instance query parameter) - permissions can get the value of 'OWNER' for the site owner otherwise it will be null.


Utils.getIpAndPort

Since 1.12.0 

This method returns a String which represents the app IP and port.

Syntax
Utils.getIpAndPort
Returns

(String) an app IP and port (decoded property of the instance query parameter).


Utils.getDemoMode

Since 1.12.0 

This method returns a Boolean which represents the app instance demo mode state.

Syntax
Utils.getDemoMode
Returns

(Boolean)  an app instance demo mode state (decoded property of the instance query parameter).


Utils.getSignDate

Since 1.12.0 

This method returns a String which represents the app instance signDate.

Syntax
Utils.getSignDate
Returns

(String) an app instance signDate (property of the decoded instance query parameter).


Utils.navigateToSection

Since 1.33.0 

Navigates to the callers section page in the hosted site.

Syntax
Utils.navigateToSection

 

Arguments
 nametypedescription
1sectionIdentifierObject, optionalApp page id defined in dev.wix.com
1stateString, optional
new app's state to push into the editor history stack
2callbackFunctionthis will be called if the hosting site does not include the section app, or if the caller's application does not include a section
Returns

onFailure (Function) this will be called if the hosting site does not include the section app, or if the caller's application does not include a section.


Utils.Media.getImageUrl

Since 1.17.0 

This method constructs a URL for a media item of type image. 

Syntax
Arguments
 nametypedescription
1relativeUriString
image item uri (relative to Wix media gallery)
Returns

(String) a full URL pointing to the Wix static servers of an image with the default dimensions - width and height. 

 


Utils.Media.getResizedImageUrl

Since 1.17.0

This method constructs a URL for a media item of type image and let the developer change the image dimensions as well as it's sharpening properties (optional),  see sharpening explained here - http://en.wikipedia.org/wiki/Unsharp_masking.

Syntax
Arguments
 nametypedescription
1relativeUriString
image item uri (relative to Wix media gallery)
2widthNumberdesires image width
3heightNumberdesired image height
4sharpParams (optional)Object
nametypedescription
qualityNumberJPEG quality, leave as is (75) unless image size is important for your app
filterNumberresize filter
usm_rNumberunsharp mask radius
usm_aNumberunsharp mask amount (percentage)
usm_tNumberunsharp mask threshold
Returns

(String) a full URL pointing to the Wix static servers of an image with the custom dimension parameters.

 


Utils.Media.getAudioUrl

Since 1.17.0

 This method constructs a URL for a media item of type audio. 

 Syntax
 Arguments
 nametypedescription
1relativeUriString
audio item uri (relative to Wix media gallery)
Returns

(String) a full URL pointing to the Wix static servers of an audio file with the default dimensions.

 


Utils.Media.getDocumentUrl

Since 1.17.0

This method constructs a URL for a media item of type document. 

Syntax
Arguments
 nametypedescription
1relativeUriString
document item uri (relative to Wix media gallery)
Returns

(String) a full URL pointing to the Wix static servers of a document media file with the default dimensions.

 


Utils.Media.getSwfUrl

Since 1.17.0

This method constructs a URL for a media item of type swf

Syntax
Arguments
 nametypedescription
1relativeUriString
swf item uri (relative to Wix media gallery)
Returns

(String) a full URL pointing to the Wix static servers of a swf media file  with the default dimensions.


Settings.refreshApp

Since 1.12.0

Notifying the host site that the app requires reloading.

The refreshApp method is normally used when a user changes the app settings in the settings iframe, and as a result requires that the Widget or Page iframes should be reloaded such that the new settings will take affect.

The refreshApp method accepts a single optional argument, an object. Where each of the object's properties will translate into a query parameter in the iframe URL.

Syntax
Settings.refreshApp
Arguments 
 nametypedescription
1queryParamsObjectOptional - a map of custom query parameters that should be added to the iframe URL.

Settings.refreshAppByCompIds

Since 1.12.0

Notifying the host site that some specific components of the app requires reloading. It does the same as Settings.refreshApp but for specific components.

Syntax
Settings.refreshAppByCompIds
Arguments 
 nametypedescription

1

compIdsArrayMandatory -  an array of the app component ids that should be refreshed.
2queryParamsObjectOptional - a map of custom query parameters that should be added to the iframe URL.

Settings.openBillingPage

Since 1.16.0

The Setting.openBillingPage method allows the app to offer a premium package from within the app settings. When called will open the Wix billing system page in a new browser window.

Settings.openBillingPage

 


Settings.openMediaDialog

Since 1.17.0

This method opens the Wix media dialog inside the WIx Editor, and let's the site owner choose a an existing file from the Wix media galleries, or upload a new file instead. When completed a callback function returns the meta data of the selected item/s.

This method returns a meta data descriptor for a selected media item. To access the media item from your code you will need to construct a full URL using that descriptor. Since the media items URLs format is set by Wix and might changed in the future, we are requiring that the URL construction will be done using the SDK. Use one of the Wix.Utils.Media.get* methods to get the desired media item URL.

The following media type are currently supported - Wix.Settings.MediaType

 namedescription
1IMAGEImage media type
2BACKGROUNDBackground media type, images/textures for background and wallpaper
3AUDIOaudio media type
4DOCUMENTdocument media type
5SWFswf/flash media type


Syntax
Arguments
 nametypedescription
1media typeWix.Settings.MediaTypeMedia gallery to choose from - image, background, audio and swf
2multi selectBoolean
selection mode, single (false) or multiple (true) item to choose from
3onSuccessFunctioncallback function, passing the media item/s meta data
4onCancelFunctiononCancel function called when user cancels
Returns
  • This is an asynchronous function, the returned value is passed in the onSuccess callback function.

An object (single selection) or Array of objects (multiple selection). The object describes the meta data of the selected media item. It's properties are: 

 nametypevalue
1fileNameStringmedia item file name
2typeStringmedia item type 
3relativeUriStringmedia item uri (relative to Wix media gallery) use Wix.Utils.Media.get* to get a full url
4widthNumbermedia type width (for images only)
5heightNumbermedia type height (for images only)

Settings.triggerSettingsUpdatedEvent

Since 1.17.0

The triggerSettingsUpdatedEvent method is used from the Settings iframe to trigger a Wix.Events.SETTINGS_UPDATED event in a WIdget/Page iframe. It should be used in an editing session when a developer wants to reflect editing changes but avoid refresh/reload on the Widget/Page iframe. 

Syntax
Arguments
nametypedescription
1messageObjecta custom JSON which will be passed to the Widget/Page as the event data
2compIdStringa component id we want to trigger the event on, or '*' to trigger the event on all the app components. The most obvious compId is Wix.Utils.getOrigCompId()
Example 

Settings.getSiteInfo

Since 1.12.0

The getsiteInfo method is used to retrieve information about the host site in which the app is shown.

Syntax
getSiteInfo
Arguments
 nametypedescription
1callbackFunction

a callback function to receive the site pages. The function signature should be :
function onSuccess(siteInfo) {...}

Returns
  • This is an asynchronous function, the returned value is passed in the onSuccess callback function.

(Object) JSON containing the site info. It's properties are: 

 nametypedescription
1siteTitleStringthe title of the site that is used for SEO
2pageTitleStringthe site current page title that is used for SEO
3siteDescriptionStringthe description of the site that is used for SEO
4siteKeywordsStringthe keywords which were related to the site and are used for SEO
5referrerStringthe referrer header of the http request
6urlString

the full url taken from the location.href, include internal site state, for example: http://user.wix.com/site-name#!pageTitle/pageId, http://www.domain.com#!pageTitle/pageId

7baseUrlString

base url of the current site, for example: http://user.wix.com/site-name, http://www.domain.com


Settings.setWindowPlacement

Since 1.19.0

The setWindowPlacement method sets the placement for fixed position widgets in an editing session

Syntax
setWindowPlacement
Arguments
 nametypedescription
1compIdString

component id to change window placement to

2placementWix.WindowPlacementnew placement for the widget window
3verticalMargin (Optional)Number vertical offset from the window placement
4horizontalMargin (Optional)Number horizontal offset from the window placement

Settings.getSitePages

Since 1.17.0

The getSitePages method is used to retrieve the site structure from the hosting Wix Platform. The site structure includes visible and hidden pages as well as sub pages.

Syntax
getSitePages
Arguments
 nametypedescription
1callbackFunction

a callback function to receive the site info. The function signature should be :
function onSuccess(sitePages) {...}

Returns
  • This is an asynchronous function, the returned value is passed in the onSuccess callback function.

(Array) containing an ordered set of the site pages. A single page description contains the following properties: 

 nametypedescription
1idStringthe page id
2titleStringthe page title
3hideBooleana flag indicating if the page is hidden
4subPages(optional)ArrayAn ordered set of sub pages
Example
Site Pages

Settings.getStyleParams (Deprecated - use Wix.Styles.getStyleParams)

Since 1.22.0

The getStyleParams method is used to retrieve the style parameters from the hosting Wix Platform. The parameters includes colors numbers, booleans.

Syntax
getSitePages
Arguments
 nametypedescription
1callbackFunction

a callback function to receive the style parameters. The function signature should be :
function callback(styles) {...}

Returns
  • This is an asynchronous function, the returned value is passed to the callback function.

Settings.getDashboardAppUrl

Since 1.32.0

This method returns the URL leading to your BackOffice (AKA Business) application, in the Wix Dashboard. The URL is fully qualified and starts with "//" for using HTTPS if supported. If the site is not saved, save dialog will be prompted.

Syntax
getDashboardAppUrl
Arguments
 nametypedescription
1callbackFunction

a callback function to receive the URL of the app in the dashboard (AKA BackOffice/Business). The function signature should be :
function callback(url) {...}

Returns
  • This is an asynchronous function, the returned value is passed to the callback function.

Dashboard.setHeight

Since 1.24.0

This method requests the hosting Wix platform to change the iframe height inside the side dashboard (under the My Account tab in Wix.com).

Syntax
Dashboard.setHeight
Arguments
 nametypedescription
1heightNumber
an integer that represents the desired height in pixels.

Dashboard.openMediaDialog

Since 1.27.0

This method opens Wix media dialog inside WIx Dashboard, and let's the site owner choose a an existing file from the Wix media galleries, or upload a new file instead. When completed a callback function returns the meta data of the selected item/s.

This method returns a meta data descriptor for a selected media item. To access the media item from your code you will need to construct a full URL using that descriptor. Since the media items URLs format is set by Wix and might changed in the future, we are requiring that the URL construction will be done using the SDK. Use one of the Wix.Utils.Media.get* methods to get the desired media item URL.

The following media type are currently supported - Wix.Settings.MediaType

 namedescription
1IMAGEImage media type
2BACKGROUNDBackground media type, images/textures for background and wallpaper
3AUDIOaudio media type
4DOCUMENTdocument media type
5SWFswf/flash media type


Syntax
Arguments
 nametypedescription
1media typeWix.Settings.MediaTypeMedia gallery to choose from - image, background, audio and swf
2multi selectBoolean
selection mode, single (false) or multiple (true) item to choose from
3onSuccessFunctioncallback function, passing the media item/s meta data
4onCancelFunctiononCancel function called when user cancels
Returns
  • This is an asynchronous function, the returned value is passed in the onSuccess callback function.

An object (single selection) or Array of objects (multiple selection). The object describes the meta data of the selected media item. It's properties are: 

 nametypevalue
1fileNameStringmedia item file name
2typeStringmedia item type 
3relativeUriStringmedia item uri (relative to Wix media gallery) use Wix.Utils.Media.get* to get a full url
4widthNumbermedia type width (for images only)
5heightNumbermedia type height (for images only)

 


Dashboard.openModal

Since 1.27.0

The openModal method allows an app to open a modal window within the dashboard. A modal is a runtime Widget that is not part of the dashboard structure. The modal window is a singleton (every new modal closes the previous one) and contains a lightbox. A modal can be dismissed by the user if it touches the lightbox, presses the closing button or by the app itself if it calls the Wix.Dashboard.closeWindow() from within the modal iframe. The onClose argument can be used to detect modal close.

Syntax
openModal
Arguments
 nametypedescription
1urlString

the modal iframe url

2widthNumberthe modal window width
3heightNumberthe modal window height
4onClose (Optional)Functionon close callback function

 


Dashboard.closeWindow

Since 1.27.0

The closeWindow method is available only under a modal endpoint (will not have any effect for other endpoints). It allows the modal to close itself programmatically.

Syntax
closeWindow
Arguments
 nametypedescription
1message (Optional)Object

a custom message object to pass to the opener's onClose callback function

 


Dashboard.openBillingPage

Since 1.31.0

The Dashboard.openBillingPage method allows the app to offer a premium package from within the app. When called will open the Wix billing system page in a new browser window.

Dashboard.openBillingPage

 


Dashboard.scrollTo

Since 1.31.0

The Dashboard.scrollTo method allows the app to scroll to an absolute offset - vertical & horizontal

 
Dashboard.scrollTo
Arguments
 nametypedescription
1xNumber

The coordinate to scroll to, along the x-axis

2yNumberThe coordinate to scroll to, along the y-axis

 


Dashboard.getEditorUrl

Since 1.33.0

Returns the editor Url for the dashboard app.

 
Dashboard.scrollTo

 


Dashboard.pushState

Since 1.35.0

This method enable 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 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).

For a full explanation of how deep-linking works with AJAX style apps, see Deep Linking for AJAX Style Apps.

Syntax
pushState

Arguments

 nametypedescription
1stateString

new app's state to push into the editor history stack

 


Contacts.getContacts

Since 1.27.0

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

Syntax
getContacts

 

1
2
3
//The following call will get a list of all contacts that have interacted with the given site.  The results are returned through a callback that delivers a WixDataCursor object
 
Wix.Contacts.getContacts(function(WixDataCursor), function(errorType));

 

Arguments

 

 nametypedescription

1

onSuccessfunction

a function that receives a WixDataCursor object

2onFailurefunctiona function called when an error occurs that receives a Wix.Error

 

ErrorType

 

namedescription
Wix.Error.WIX_ERROR

Indicates an error happened on Wix 

 


 

Contacts.getContactById

Since 1.27.0

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

Syntax
getContactById

 

1
2
3
//The following call will get a contact with the given id that have interacted with the given site.  The results are returned through a callback that contains the data.
 
Wix.Contacts.getContactById(id, function(data), function(errorType));

 

Arguments

 

 nametypedescription
1idStringthe id of the Contact to look up
2onSuccessfunctiona function that receives data about the Contact
3onFailurefunctiona function called when an error occurs that receives a Wix.Error 

 

ErrorType

 

namedescription
Wix.Error.WIX_ERROR

Indicates an error happened on Wix 

 


Activities.postActivity

Since 1.25.0

This method posts an Activity to the current site.  An Activity is an action performed by a site viewer on the installed site.  By reporting Activities, your application better integrates with the Wix ecosystem. Each Activity conforms to a specific schema predefined by Wix. When the Activity is successfully created, the id of the activity will be returned. If schema validation fails, or other errors occur, an error will be returned

 

1
Wix.Activities.postActivity(activity, onSuccess, onFailure);

 

Arguments

 

 
name
type
description
signature
optional
1
activity
Object
nametypedescriptionoptional
typeStringThe Activity Type. See Wix.Activity.ActivityType 
infoObjectThe Activity information, specified by the Activity typeNo
detailsObject
nametypedescription
additionalInfoUrlStringURL for additional information about this Activity
summaryStringAdditional information about this Activity
No
contactUpdateObjectAdditional Contact information relevant to this ActivityYes
 No
2onSuccessFunctioncallback function fired when the activity was posted successfully.function(result)Yes
3
onFailure
Functioncallback function fired when the activity fails to post.function(errorResponse)Yes

 

Returns
  • This is an asynchronous function, the returned value is passed in the onSuccess callback function.

(Object) JSON containing the site info. It's properties are: 

 

 nametypedescription
1activityIdStringthe id of the created Activity

 


Wix.Activity.ActivityType

 

 namevalue
CONTACT_CONTACT_FORMcontact/contact-form
ECOMMERCE_PURCHASEecommerce/purchase
AUTH_STATUS_CHANGEauth/status-change
AUTH_REGISTERauth/register
AUTH_LOGINauth/login
CONVERSION_COMPLETEconversion/complete
ECOMMERCE_PURCHASEe_commerce/purchase
HOTELS_CANCELhotels/cancel
HOTELS_CONFIRMATIONhotels/confirmation
HOTELS_PURCHASEhotels/purchase
HOTELS_PURCHASE_FAILEDhotels/purchase-failed
SEND_MESSAGEmessaging/send
ALBUM_FANmusic/album-fan
ALBUM_SHAREmusic/album-share
TRACK_LYRICSmusic/track-lyrics
TRACK_PLAYmusic/track-play
TRACK_PLAYEDmusic/track-played
TRACK_SHAREmusic/track-share
TRACK_SKIPmusic/track-skip
SCHEDULER_APPOINTMENTscheduler/appointment
  

 


Activities.getUserSessionToken

Since 1.25.0

Returns a session token which can be used to make AJAX calls to Wix RESTful API

 

1
Wix.Activities.getUserSessionToken(callback);

 

Arguments

 

 nametypedescription
1callbackFunction

a callback function to receive the token. The function signature should be :
function onSuccess(userToken) {...}

 

Returns
  • This is an asynchronous function, the returned value is passed in the onSuccess callback function.

(String) representing the user session token

 


Activities.getActivities

Since 1.28.0

Gets a list of all activities that have been performed by users on the current site, optionally bound by date ranges, activity types and scope (app/site).  The results are returned through a callback that delivers a WixDataCursor object, with the results being in descending order by date.

Syntax

 

Wix.Activities.getAllActivities({ from: < ISO 8601 timestamp>, until: < ISO 8601 timestamp>, scope: <'app'/'scope'>, activityTypes: [ 'type1', 'type2', ...] }, function(WixDataCursor), function(errorType));

 

Arguments

 

 

name

type

description

optional

signature

1

query

Object

an Object containing params to restrict our results

Yes

 

2

onSuccess

function

a function that receives a a WixDataCursor object

No

function(

WixDataCursor

)

3

onFailure

function

a function that receives an error object in case of invalid input

No

function(

errorObj

)

 

Params structure

 

{

    "until" : WixDate,

    "from" : WixDate,

    "scope": String ('app' or 'site'),

    "activityTypes": Array[Wix.Activity.ActivityType]

}

 

Error Types

 

 name

description

Wix.Error.WIX_ERROR

Indicates an unknown error happened on Wix side which could not be recovered. When handling this error, you can try again or prompt the user with an error dialog.

Wix.Error.BAD_REQUEST

Indicates the dates you provided are in the wrong format or are not valid date ranges

 

Activity object

 

{

    "createdAt" : "datetime",

    "activityType" : "Wix.Activity.ActivityType",

    "activityLocationUrl" : "url",

    "activityInfo" : {},

    "activityDetails" : {

        "additionalInfoUrl",

        "summary"

    }

} 

 


Activities.getActivityById

Since 1.28.0

Gets a specific Activity that occurred on the current site.

Syntax

 

Wix.Activities.getActivityById(id, onSuccess, onFailure)

 

Arguments

 

name
type
description
optional
Signature
idStringThe id of the Activity to look upNo 
onSuccessfunctionCallback triggered when data about the Activity is returned from WixNofunction(data)
onFailurefunctionCallback triggered if the data could not be returned successfullyNo function(errorType)

 

Error Types

 

 name
description
Wix.Error.NOT_FOUND
Indicates the activity could not be found

 

Returns

 

type
description
optional
ActivityAn activityNo

 


Worker.getSiteInfo

Since 1.30.0

This method is used to retrieve information about the host site in which the app is run in.

Syntax
getSiteInfo
Arguments
 nametypedescription
1callbackFunction

a callback function to receive the site pages. The function signature should be :
function onSuccess(siteInfo) {...}

Returns
  • This is an asynchronous function, the returned value is passed in the onSuccess callback function.

(Object) JSON containing the site info. It's properties are: 

 nametypedescription
1siteTitleStringTitle of the site that is used for SEO
2pageTitleStringThe current page's title that is used for SEO
3siteDescriptionStringDescription of the site that is used for SEO
4siteKeywordsStringKeywords which are related to the site and are used for SEO
5referrerStringReferrer header of the HTTP request
6urlString

Full URL taken from location.href, includes the internal site state. For example: http://user.wix.com/site-name#!pageTitle/pageId, http://www.domain.com#!pageTitle/pageId

7baseUrlString

Base url of the current site, for example: http://user.wix.com/site-name, http://www.domain.com


Worker.getSitePages

Since 1.30.0

The getSitePages method is used to retrieve the site structure from the hosting Wix Platform. The site structure includes visible and hidden pages as well as sub pages.

Syntax
getSitePages
Arguments
 nametypedescription
1callbackFunction

a callback function to receive the site info. The function signature should be :
function onSuccess(sitePages) {...}

Returns
  • This is an asynchronous function, the returned value is passed in the onSuccess callback function.

(Array) containing an ordered set of the site pages. A single page description contains the following properties: 

 nametypedescription
1idStringthe page id
2titleStringthe page title
3hideBooleana flag indicating if the page is hidden
4subPages(optional)ArrayAn ordered set of sub pages
Example
Site Pages

Worker.addEventListener

Since 1.30.0

The addEventListener method lets the App listen for events that happen on the Editor/site.

The events you can listen to are as follows:

EventEvent DataDescription
EDIT_MODE_CHANGE
{editMode: 'editor' or 'preview'}called when a site owner toggles between preview and edit mode in the Wix Editor

PAGE_NAVIGATION_CHANGE(deprecated)

{}called when a user navigates (in Editor, preview or Viewer) to the page where the TPA component (Widget/Page) is
PAGE_NAVIGATION
called when a page navigation is made within the Wix site
PAGE_NAVIGATION_IN
issued on any page in navigation within the Wix site. This event is a utility event on top of the 
PAGE_NAVIGATION event
PAGE_NAVIGATION_OUT
issued on any page out navigation within the Wix site. This event is a utility event on top of the 
PAGE_NAVIGATION event
SCROLL

Called when scroll happens on the site (not when it happens inside the app iframe). The event data contains multiple details that help the app determine it's behaviour considering it's position in the site, the browser window dimensions, and the scrolling state:

nametypedescription
Numbersite's scroll position on the y axis
site's scroll position on the x axis
site's document height
site's document width
xapp offset within the site's page on the x axis (doesn't change) 
yapp offset within the site's page on the y axis (doesn't change)
app width
app height
leftapp top-left offset,within the viewport, from the left
bottomapp top-left, offset within the viewport, from the bottom
rightapp top-left, offset within the viewport, from the right
topapp top-left, offset within the viewport, from the top


COMPONENT_DELETED
{}Called when the site owner deletes (in the Editor) a TPA component (Widget/Page)
SITE_PUBLISHED
{}Called when the site owner publishes the site (in Editor)
SETTINGS_UPDATED
Custom JSONCalled by the Settings endpoint when new settings are applied by the site owner
STATE_CHANGED
{newState: 'state'}issued when the site state changed
Syntax
addEventListener
Arguments
 nametypedescription
1Event typeWix.Events
unique event identifier, see the full list below
2Event handler functionFunction a javascript callback function that will get called by the SDK when the event occurs

About COMPONENT_DELETED

Note that even though the user will see the widget deleted immediately, the deletion itself will be delayed so that the app iframe can respond to the delete event. Your code should make the minimum steps required to perform state preserving, if any - AJAX, cookie, local storage, etc - before the component is deleted.

Returns

(Number) an id that can be used to remove the event listening using Wix.removeEventListener(eventName, id)


Worker.currentMember

Since 1.30.0

This method is part of Wix Site Members feature. To use it a manual provisioning is required by the Wix team, contact apps@wix.com to enable it for your app.

This method is relevant for live sites and not from the App Settings. This method returns the details of the current site visitor that is logged into the Wix site, using the Wix site member options 

Syntax
Arguments
 nametypedescription
1callbackFunction

a call back function to receive the current member details. The function signature should be :
function onSuccess(memberDetails) {...}

Returns
  • This is an asynchronous function, the returned value is passed in the onSuccess callback function.

(Object) JSON containing the user's details. It's properties are: 

 nametypevalue
1nameStringthe current member's name
2emailString

the current member's email

3idStringthe current member's id
4ownerBooleanindicates if the user is the owner of the site

Worker.PubSub.publish

Since 1.30.0

Broadcasts an event to other extensions of a multi-widget TPA. If the app extensions (Widget, Fixed Positioned Widget, Page) span multiple pages, they will be notified when they are rendered.

Syntax
publish
Arguments
 
name
type
description
optional
1
eventName
String

the name of the event to publish

No
2dataObjectdata the object to send to subscribers for this event typeNo
3isPersistentbooleanIndicates whether this event is persisted for event subscribers who have not yet subscribedYes

Worker.PubSub.subscribe

Since 1.30.0

Subscribes to events from other app parts of a multi-widget TPA.  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 widget will be notified immediately of any prior events of the type it is registered to receive.

Syntax
subscribe
Arguments
 
name
type
description
optional
signature
1
eventName
String

the name of the event to subscribe to.

Yes 
2callBackFunctionfunction 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 eventNofunction(event, eventName, source)
3receivePastEventsbooleana flag to indicate that all past instances of the registered event should be sent to registered listener. This will happen immediately upon registrationYes 
Returns

(Number) a subscription id that can be used to remove the event subscription using PuSub.unsubscribe(eventName, id)


Worker.PubSub.unsubscribe

Since 1.30.0

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

Syntax
closeWindow
 
Arguments
 
name
type
description
optional
signature
1
eventName
String

the name of the event to unsubscribe from. 

No 
2
callBackOrId
Function/Numberfunction 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 eventNofunction(event, eventName, source)

Worker.Utils.getViewMode

Since 1.30.0

This method returns a String which represents the current view mode.

Syntax
Utils.getViewMode
Returns

(String) the current view mode. One of the following values:

  • editor 
  • preview
  • site
  • standalone

Worker.Utils.getDeviceType

Since 1.30.0

This method returns a String which represents the current device type

Syntax
Utils.getViewMode
Returns

(String) the current device type. One of the following:

  • desktop
  • mobile

Worker.Utils.getLocale

Since 1.30.0

This method for valid endpoints (Widget/Page/Settings) returns a String which represents the current locale of the site/editor. A locale is an abbreviated language tag that defines the user's language, country and any special variant preference of the user interface (e.g. Number format, Date format, etc.).

Syntax
Utils.getLocal
Returns

(String ) a standard IETF language tag - en (English), es (Spanish), fr (Franch), it (Italian), etc.


Worker.Utils.getInstanceId

Since 1.30.0

This method returns a String which represents the app instance Id.

Syntax
utils.getInstanceId
Returns

(String) an app instance id - a GUID like value (decoded property of the instance query parameter) 


Worker.Utils.getIpAndPort

Since 1.30.0

This method returns a String which represents the app IP and port.

Syntax
Utils.getIpAndPort
Returns

(String) an app IP and port (decoded property of the instance query parameter).

 


THE END

Labels
  • None