WonderPush JavaScript SDK Namespace: WonderPush

The entry point to WonderPush.

Methods

<static> init(options)

Initialize the SDK.

Parameters:

Name	Type	Description
`options`	WonderPush.InitOptions	Initialization options.

<static> push(item)

Places calls against the WonderPush SDK, when it is ready.

Parameters:

Name	Type	Description
`item`	WonderPush.ReadyCallback \| WonderPush.ReadyArrayItem	This function will be called with the WonderPushSDK instance as first argument, after the SDK has successfully initialized.

<static> ready(item)

Places calls against the WonderPush SDK, when it is ready.

Parameters:

Name	Type	Description
`item`	WonderPush.ReadyCallback \| WonderPush.ReadyArrayItem	This function will be called with the WonderPushSDK instance as first argument, after the SDK has successfully initialized.

<static> registerPlugin(pluginName, constructor)

This function is only available to plugins. It is only exposed when loading the declared plugins.

Parameters:

Name Type Description

pluginName

string

The plugin's name

constructor

WonderPush.PluginEntryPoint | Object

The plugin window constructor or constructors object.

Properties

Name	Type	Description
`window`	WonderPush.PluginEntryPoint	The plugin constructor when used in the context of the website window. This is the field you'll define if you give a function directly instead of an object. Leave unset to not be loaded in the context of the website window.
`serviceWorker`	WonderPush.PluginEntryPoint	The plugin constructor when used in the context of the service worker. Leave unset to not be loaded in the context of the service worker.

addPageView()

Call this function whenever new page content is loaded.

Single Page Applications that load content using React and similar or AJAX will benefit from this to "fix" page views counting.

This increments the page views counter and may trigger automatic subscription, if configured this way.

Calling this function also helps the SDK to monitor the user activity.

If a hashchange event is equivalent to a new page, then you'll want to bind a listener on this event and call this function.

Returns:

Type: Promise

addProperty(field, value)

Adds the value to a given installation property.

The stored value is made an array if not already one. If the given value is an array, all its values are added. If a value is already present in the stored value, it won't be added.

Parameters:

Name	Type	Description
`field`	string	The name of the property to add values to
`value`	* \| Array.<> \|	The value(s) to be added, can be an array or multiple arguments

Returns:

Type: Promise

addTag(tag)

Adds one or more tags to the installation.

Parameters:

Name	Type	Description
`tag`	Array.<string> \| string	The tags to add to the installation. You can use either a single string argument, multiple string arguments or an array of strings.

Returns:

Type: Promise

areSponsoredNotificationsEnabled()

Returns whether the user is subscribed to sponsored push notifications.

Returns:

enabled

Type: Promise.<(boolean|undefined)>

clearAllData()

Remove any local storage and ask the WonderPush servers to delete any data associated with the all local installations and related users.

Returns:

Type: Promise

clearEventsHistory()

Ask the WonderPush servers to delete any event associated with the all local installations.

Returns:

Promise

clearPreferences()

Ask the WonderPush servers to delete any custom data associated with the all local installations and related users.

Returns:

Type: Promise

disableSponsoredNotifications()

Unsubscribes from push sponsored notifications.

Returns:

Type: Promise

downloadAllData()

Initiates the download of all user remote and local data.

Returns:

Type: Promise

enableSponsoredNotifications()

Subscribes to push sponsored notifications.

Returns:

Type: Promise

getCountry()

Returns the user's country, undefined by default.

Returns:

Type: Promise.<string>

getCurrency()

Returns the user's currency, undefined by default.

Returns:

Type: Promise.<string>

getDisplayedInAppMessage()

Returns the in-app message currently displayed or null if none is being displayed. If you provided a display callback using WonderPush#setInAppMessagingDisplayCallback, this will always return null.

Returns:

Type: InAppMessage.<*>

getLocale()

Returns the user's locale.

Returns:

Type: Promise.<string>

getProperties()

Retrieves the installation properties.

Returns:

Type: Promise.<Object.<string, *>>

getPropertyValue(field)

Returns the value of a given installation property.

If the property stores an array, only the first value is returned. This way you don't have to deal with potential arrays if that property is not supposed to hold one. Returns null if the property is absent or has an empty array value.

Parameters:

Name	Type	Description
`field`	string	The name of the property to read values from

Returns:

null or a single value stored in the property, never a array nor undefined

Type: Promise.<?string>

getPropertyValues(field)

Returns an array of the values of a given installation property.

If the property does not store an array, an array is returned nevertheless. This way you don't have to deal with potential scalar values if that property is supposed to hold an array. Returns an empty array instead of null if the property is absent. Returns an array wrapping any scalar value held by the property.

Parameters:

Name	Type	Description
`field`	string	The name of the property to read values from

Returns:

A possibly empty array of the values stored in the property, but never null nor undefined

Type: Promise.<Array.<string>>

getTags()

Returns all the tags of the installation.

Returns:

Type: Promise.<Array.<string>>

getTimeZone()

Returns the user's timezone.

Returns:

Type: Promise.<string>

getUserId()

Returns a promise that resolves to a string or null. See https://docs.wonderpush.com/docs/user-ids

Returns:

Type: Promise

hasTag(tag)

Tests whether the installation has the given tag attached to it.

Parameters:

Name	Type	Description
`tag`	string	The tag to test.

Returns:

A promise that resolves to true if the given tag is attached to the installation, false otherwise.

Type: Promise.<boolean>

isAllowedSubscriptionDomain(origin)

Whether the current or given domain is allowed to take subscriptions.

Parameters:

Name	Type	Argument	Description
`origin`	string	<nullable>	An origin (`http[s]://hostname`) to test. Defaults to `location.origin`

Returns:

Whether the given origin is allowed to call WonderPush#subscribeToNotifications.

Type: Promise.<boolean>

isSubscribedToNotifications()

Returns whether the user is subscribed to push notifications.

Returns:

enabled

Type: Promise.<boolean>

putProperties(customData)

Updates the installation properties.

Parameters:

Name	Type	Description
`customData`	object

Returns:

Type: Promise

removeAllTags()

Removes all tags from the installation.

Returns:

Type: Promise

removeProperty(field, value)

Removes the value from a given installation property.

The stored value is made an array if not already one. If the given value is an array, all its values are removed. If a value is present multiple times in the stored value, they will all be removed.

Parameters:

Name	Type	Description
`field`	string	The name of the property to read values from
`value`	* \| Array.<> \|	The value(s) to be removed, can be an array or multiple arguments

Returns:

Type: Promise

removeTag(tag)

Removes one or more tags from the installation.

Parameters:

Name	Type	Description
`tag`	Array.<string> \| string	The tags to remove from the installation. You can use either a single string argument, multiple string arguments or an array of strings.

Returns:

Type: Promise

sendSelfNotification( [options])

Send a notification to the currently subscribed user.

Parameters:

Name Type Argument Description

options

object

The options of the delivery to trigger. If absent, a test notification will be displayed, to help with easy troubleshooting.

Properties

Name	Type	Argument	Description
`campaignId`	string	<optional>	The campaign identifier of the notification to trigger. Find it in your project's WonderPush dashboard. If `notification` is not given, the notification composed inside that campaign will be used. Otherwise, the given notification is used, but the statistics will still be attached to the given campaign.
`notificationId`	string	<optional>	The notification identifier within the given campaign. Used to choose among multiple A/B variants.
`notification`	object	<optional>	The notification to deliver. If campaignId is given, this parameter is optional. If given, this parameter will replace the notification composed in the campaign. If you want to control which message to send from the client side, then this is the parameter you are looking for. See https://docs.wonderpush.com/reference/notification for more information on accepted values.
`notificationOverride`	object	<optional>	Applies partial modifications to the notification taken from the campaign. This contrasts from the `notification` parameter that replaces the notification altogether.
`notificationParams`	object \| Array.<object>	<optional>	Fills any notification parameter with the given values. If using the array syntax, it must hold a single object as value.

Returns:

Type: Promise

setCountry()

Sets the user's country.

Returns:

Type: Promise.<void>

setCurrency()

Sets the user's currency.

Returns:

Type: Promise.<void>

setInAppMessagesSuppressed(messagesSuppressed)

Suppresses or enables in-app messages display.

Parameters:

Name	Type	Description
`messagesSuppressed`		whether in-app messages should be suppressed

setInAppMessagesSuppressed()

Returns whether in-app messages display is suppressed.

Returns:

Type: boolean

setInAppMessagingDisplayCallback(displayCallback)

Sets the in-app messaging display callback. Setting the display callback allows you to handle the display of in-app messages yourself. Set to null / undefined to hand the display to WonderPush again.

The display callback accepts 2 arguments:

the in-app message
the reporting callback

Parameters:

Name	Type	Description
`displayCallback`		a function taking 2 arguments: the in-app message and the reporting callback object.

See:

Example

WonderPush.push(function() {
  WonderPush.setInAppMessagingDisplayCallback(function(inAppMessage, reportingCallback) {
    // Display inAppMessage, then
    // When viewed:
    reportingCallback.logImpression(inAppMessage);
    // When dismissed:
    reportingCallback.logDismiss(inAppMessage, 'tap');
    // When clicked:
    reportingCallback.logClick(inAppMessage);
    // Report that we handled the message.
    return true;
  });
})

setLocale()

Sets the user's locale.

Returns:

Type: Promise.<void>

setProperty(field, value)

Sets the value to a given installation property.

The previous value is replaced entirely. Setting undefined or null has the same effect as WonderPush#unsetProperty.

Parameters:

Name	Type	Description
`field`	string	The name of the property to set
`value`	mixed	The value to be set, can be an array

Returns:

Type: Promise

setTimeZone()

Sets the user's timezone.

Returns:

Type: Promise.<void>

setUserConsent()

Reads user consent state. Returns undefined if no explicit consent was set.

Returns:

Type: Promise.<(boolean|undefined)>

setUserConsent(consent)

Provides or withdraws user consent. If the requiresUserConsent initialization option is true, the whole SDK is paused and no data is sent to WonderPush, until consent is provided.

Parameters:

Name	Type	Description
`consent`	boolean

Returns:

Type: Promise

setUserId()

Call this function whenever user logs in or out. Call with null or undefined when user logs out. See https://docs.wonderpush.com/docs/user-ids

Returns:

Type: Promise

showSubscriptionBell(show)

Show or hide the subscription bell

Parameters:

Name	Type	Description
`show`	Boolean	Whether to show or hide the bell.

showSubscriptionDialog()

Show the subscription dialog

showSubscriptionSwitch(parentNode, options)

Show a subscription switch.

Parameters:

Name	Type	Description
`parentNode`	HTMLElement	The node where we'll put the subscription switch using `appendChild`.
`options`	Object	Options passed to the switch element via `data-` attributes.

showTagSwitches(parentNode, options[)

Show a collection of tag switches.

Parameters:

Name	Type	Description
`parentNode`	HTMLElement	The node where we'll put the tag switches using `appendChild`.
`options[`	Array.<Object>	An array of Options passed to the tag-switch element via `data-` attributes.

subscribeToNotifications( [event])

Subscribes to push notifications.

Parameters:

Name	Type	Argument	Description
`event`	Event	<optional>	If you call this function in response to a user event, give that event here. It will permit bypassing popup blockers to open any necessary popup to finalize the registration process, without requiring the user to click once again on a modal box.

Returns:

Type: Promise

unsetProperty(field)

Removes the value of a given installation property.

The previous value is replaced with null.

Parameters:

Name	Type	Description
`field`	string	The name of the property to set

Returns:

Type: Promise

unsetUserId()

Call this function whenever user logs out. Equivalent to calling setUserId(null). See https://docs.wonderpush.com/docs/user-ids

Returns:

Type: Promise

unsubscribeFromNotifications()

Unsubscribes from push notifications.

Returns:

Type: Promise

useGeolocation(enable)

Dynamically enables or disables the use of the Geolocation API. You can automatically enable it using {"geolocation": true} in the options given to WonderPush.init function

Parameters:

Name	Type	Description
`enable`	boolean \| string	`true`/`false`, or `"auto"` to detect existing permission.

Type Definitions

InitOptions

Type:

Object

Properties:

Name	Type	Argument	Default	Description
`webKey`	string			The Web key of your application.
`userId`	string	<optional> <nullable>	null	The unique id of the user browsing the page.
`requiresUserConsent`	boolean	<optional> <nullable>	false	Whether the user consent is required for WonderPush to operate. When `true`, the SDK is paused and no data will be recorder nor sent to WonderPush until the WonderPushSDK.setUserConsent() function is called with `true`.
`applicationName`	string	<nullable>		The name of your website. Defaults to your website hostname. This will be displayed during the registration process. This option can be controlled from your dashboard.
`applicationVersion`	string			The version of the browsed website.
`geolocation`	boolean \| string	<optional>	"auto"	Whether to use the Geolocation API. This setting applies on startup and will prompt the user for permission the first time. You can use the WonderPushSDK.Geo.useGeolocation() function at the most appropriate time. if desired. WonderPush remembers if the permission has been previously granted and, if so, enables it automatically.
`notificationIcon`	string	<optional> <nullable>		The absolute, preferably HTTPS, URL to the notification icon. It is displayed in the registration process and along displayed notifications. This option can be controlled from your dashboard.
`notificationDefaultUrl`	string	<optional>		The absolute URL to your website front page. This is the URL that will be opened if no page is already opened and no custom URL is present in the notification. This option can be controlled from your dashboard.
`customDomain`	string	<optional>		The unique domain that controls the whole notification process. This is the domain that will be displayed in the Notification permission popup and at the bottom of each notification. The Notification permission is bond to this domain, changing this value will require users to subscribe again, although previous registrations will still continue to work for some unspecified time. You can use either a simple string with no dots: `mybrand`, or equivalently `mybrand.by.wonderpush.com`. If your current plan permits it, you can customise it: `www.mybrand.com` or equivalently `https://www.mybrand.com/`. Using this second variant, you would need to host a few more files and enable HTTPS on your website. Contact us for more information. This option is overridden by the configuration the SDK dynamically fetches and is controlled from your dashboard.
`plugins`	Object			The plugins configuration to load. See WonderPushSDK.Plugins. One key per plugin, the plugin's option object as value, or `null` or `false` to prevent it from loading. The key is composed of a plugin name followed by an optional colon and version, such as: `plugin-name`, `plugin-name:1`, `plugin-name:1.2` or `plugin-name:1.2.3`. The version is composed of 1 to 3 dot separated digits. If any digit group is omitted, the SDK will load the latest version that matches the mentioned digits. The plugins must follow semantic versioning. Hence it is not recommended to use `plugin-name` as this will load version the latest available version, be it 1.2.3 or 2.0.0, which, according to semantic versioning, will make you embrace potential incompatible API changes automatically. A safer alternative is to use `plugin-name:2` which will load the latest 2.x.x version, be it 2.0.0 or 2.17.28, but no 3.x.x or higher versions, putting you on the safe side with regards to backward incompatible changes. Similarly, using `plugin-name:2.17` will load the latest 2.17.x version, but no 2.18.x or 3.x.x version, upgrading only automatically across bugfix releases within the given minor version. The key can otherwise be an HTTPS URL to a plugin, such as: `https://server.net/path/to/plugin-name.js`. Note: Non-HTTPS URLs are not supported. Using a URL gives no update guarantee, not even that dependencies are not served from a stale cache, but it permits loading non officially registered plugins. This is especially useful for plugin development. The filename of the last component will be extracted and taken as the plugin name. It is forbidden to declare a given plugin name multiple times, such as with different versions or a URL. Doing so will result in a WonderPushSDK.Errors.PluginError being thrown.
`optInOptions`	Object			The default opt-in options to use. See WonderPushSDK.Notification.setOptInOptions(). Type: WonderPushSDK.Notification.OptInOptions.
`subscriptionOptions`	Object			The automatic subscription options to use. Type: WonderPush.SubscriptionOptions.

PluginEntryPoint(WonderPushSDK, options)

Parameters:

Name	Type	Description
`WonderPushSDK`	WonderPushPluginSDK	The initialized and pre-ready SDK instance with a few added plugin related functions.
`options`	Object	The plugin's options.

ReadyArrayItem

A function call to perform on the SDK, with name, arguments and optional callback. The first element must be the function name. The following elements are any arguments to be passed to the called function. An optional last argument can be a WonderPush.ReadyArrayItemCallback used as a callback.

This syntax permits calling a few functions before the SDK is ready, like init or setUserConsent.

Type:

Array.<*>

ReadyArrayItemCallback(error, value)

Parameters:

Name	Type	Argument	Description
`error`	Error	<nullable>	An error that was encountered and that you should check, or `null`.
`value`	*		The returned value. If an error happened this will be `undefined`.

ReadyCallback(WonderPushSDK)

This function will be called with the WonderPushSDK instance as first argument, after the SDK has successfully initialized.

Parameters:

Name	Type	Description
`WonderPushSDK`	WonderPushSDK	The initialized SDK instance.

SubscriptionOptions

Type:

Object

Properties:

Name	Type	Argument	Default	Description
`mode`	"visits" \| "pages" \| "direct" \| "manual"	<optional>	"visits"	How automatic subscription should be performed. `visits` triggers at the `minVisits`-th visit of the user. `pages` triggers at the `minPages`-th page view of the user. `direct` triggers at the very first page load. `manual` never triggers automatically. Instead you must use either the subscription switch, or call WonderPushSDK.setNotificationEnabled() manually whenever you see fit, for instance after measuring some user interest and after asking for willingness.
`minVisits`	number	<optional>	2	How many visits should the user have performed before triggering automatic subscription. Visits are reported with the `@APP_OPEN` and `@APP_CLOSE` events in the user timeline on your dashboard. Requires the `mode` option to be set to `visits`.
`minPages`	number	<optional>	3	How many page should the user have viewed before triggering automatic subscription. Depending on your website type, you may increase this number. An alternative is to use the `visits` mode, that will count browsing sessions. The SDK can only count the pages it is included in. Requires the `mode` option to be set to `pages`.
`delay`	number	<optional>	0	How long in milliseconds to delay the automatic user subscription prompt. This way the user can be prompted 10 seconds after landing on the page.
`snooze`	number \| false	<optional>	604800000	How long to wait before automatically prompting the user for subscription again, in milliseconds. Or `false` to never try again.
`switchElementId`	string	<optional>	"wonderpush-subscription-switch"	The id of the placeholder element this the SDK will use to flesh out a subscription switch. The use of a subscription switch is optional, but highly recommended for best user experience. If no element is found when the SDK initializes, nothing will happen. You can always resort to automatic subscription modes. When using a subscription switch, you may want to set the subscription `mode` to `manual`, or raise the `minVisits` or `minPages` thresholds, depending on your chosen `mode`. You should include the following placeholder anywhere you see fit in your pages: `<div id="wonderpush-subscription-switch"/>` For maximum control, you here is the list of all attributes available to customize your switch: `id` - Mandatory, must correspond to the `switchElementId` option above! `data-class-prefix` - defaults to `"wp-"`. The prefix to prepend to all the CSS classes names used. If the default style does not suit you, you can either override some rules, or use a whole new ruleset by changing this prefix. `data-prepend` - defaults to `""`. Optional HTML code to inject before the actual switch element. Escape your double quotes properly using `"`, and pay extra attention not to create syntax errors or malformed HTML! `data-append` - defaults to `""`. Optional HTML code to inject after the actual switch element. `data-sentence` - defaults to `""`. HTML snippet to inject in a SPAN tag right before the switch. You likely want to include a final space character for proper display. `data-class` - defaults to `""`. CSS class to add to the switch element. `data-color-off` - defaults to `""`, which is grey. Name of a predefined color to use for the OFF state. See below for a list of available colors. `data-color-on` - defaults to `""`, which is blue. Name of a predefined color to use for the ON state. See below for a list of available colors. `data-off` - defaults to `"OFF"`. Label of the switch in the OFF state. `data-on` - defaults to `"ON"`. Label of the switch in the ON state. Here is an example: `<div id="wonderpush-subscription-switch" data-prepend="<div class=&quot;some-wrapper&quot;>" data-append="</div>" data-sentence="Receive the latest news by push notifications: " data-class="some-stylish-class" data-color-off="red" data-color-on="green" data-off="NO" data-on="YES" > <!-- Any content will be replaced with the switch, if push notifications are supported. --> Sorry, push notifications are not supported by your browser. </div>` Available switch colors for OFF state: `grey` or `gray` - the default. `red` Available switch colors for ON state: `blue` - the default. `green`