Website SDK Reference

Initialization

Loading SDK Asynchronously

WonderPush recommends loading wonderpush-loader.min.js with the async flag so your page load times don't increase. To use it, place the following code before calling any other WonderPush functions.

<script src="https://cdn.by.wonderpush.com/sdk/1.1/wonderpush-loader.min.js" async></script>
<script>window.WonderPush = window.WonderPush || [];</script>

Our API functions can be called asynchronously using either:

1. WonderPush.push(["functionName", param1, param2]);
2. WonderPush.push(function() { WonderPush.functionName(param1, param2); });

See push for more details.

init

Call this function from every page of your site to initialize WonderPush. This call is required before any other function can be used. You must use push with the array syntax to call init.

window.WonderPush = window.WonderPush || [];
WonderPush.push(["init", {
  webKey: "YOUR_WEBKEY",
  // other initialization options 
}]);

📘

Please note that calling init more than once has no effect. If you are using Google Tag Manager, you will have to replace the WonderPush tag with a regular script tag that calls WonderPush.push(['init', { webKey: "YOUR_WEBKEY" }])

Initialization options are:

push

Pass in a callback and it will be executed when WonderPush is ready to operate. Pass in an array starting with a string and the corresponding function will be called.

WonderPush is ready to use when the async script tag has been loaded, and its configuration fetched.

If you've specified requiresUserConsent: true in your init, WonderPush will also wait for setUserConsent to be called with true.

Callback syntax

This syntax is the most convenient to call multiple WonderPush functions in a single block, and to read their return values.

Please note that this syntax can not be used for functions available prior to initialization such as init and setUserConsent.

window.WonderPush = window.WonderPush || [];
WonderPush.push(function() {
  // Do something with the WonderPush object.
})

Array syntax

This syntax is more compact when you don't need to read the result of the function. It is also the only option when calling functions available prior to initialization such as init and setUserConsent.

// call some function on the WonderPush object when ready
window.WonderPush = window.WonderPush || [];
WonderPush.push(["someFunction", param1, param2]);

Previous SDKs ready

In previous versions of our SDK, push used to be called ready. If you're using the deprecated ready, your app will continue to work. You should consider upgrading by following the migration instructions.

Subscribing users

subscribeToNotifications

Subscribes to push notifications.

If you're calling this function from a domain or subdomain that is not the push notification domain as specified in your dashboard, or if you're calling this function from a non-HTTPS page, the registration process must open a pop-up window. To avoid pop-up blockers, specify the event related to the user click as first argument of the subscribeToNotifications function.

<a href="#" onclick="WonderPush.subscribeToNotifications(event); return false;">Subscribe to push notifications</a>

In this example we create a link that triggers the push notification subscription process.

unsubscribeFromNotifications

Unsubscribes from push notifications.

Please note that calling this function does not affect the push notification permission.

<a href="#" onclick="WonderPush.unsubscribeFromNotifications(); return false;">Unsubscribe from push notifications</a>

isSubscribedToNotifications

Returns a Promise object that resolves to a boolean indicating whether the user is subscribed to push notifications.

window.WonderPush = window.WonderPush || [];
WonderPush.push(function() {
  WonderPush.isSubscribedToNotifications().then(function (isSubscribed) {
    console.log("is user subscribed to notifications: ", isSubscribed);
  });
});

In this example, we wait for WonderPush to be ready with the push function, then we call isSubscribedToNotifications and log the result to the console once the Promise resolves.

sendSelfNotification

Request the WonderPush servers to send a notification back to the calling user. If called with no argument, a default testing message is used.

This method works like a stripped down version of the POST /v1/deliveries endpoint of the Management API. The allowed options, all optional, are:

Typical usage includes:

• Testing proper configuration, when called with no parameter.
• Manually triggering a notification directly from the user's device, using texts generated from the website itself, when using the notification option.
• Manually triggering a notification directly from the user's device, using texts entered in the dashboard, when using the campaignId option.
• Manually triggering a notification directly from the user's device, using texts entered in the dashboard, while filling some parameters from the website itself, when using the campaignId and notificationParams options.

setUserId

Sets the user ID to the provided value. When the user ID changes, a new installation is created. See User IDs for more on using your own user IDs.

window.WonderPush = window.WonderPush || [];
WonderPush.push(['setUserId', "ADAPT_THIS_USER_ID"]);

unsetUserId

Clears out the userId. Equivalent to setUserId(null).

window.WonderPush = window.WonderPush || [];
WonderPush.push(['unsetUserId']);

getUserId

Returns a Promise resolving to the current user ID or null.

window.WonderPush = window.WonderPush || [];
WonderPush.push(function() {
  WonderPush.getUserId().then(console.log);
});

getInstallationId

Returns a Promise resolving to the current installation ID or null if it not available yet.

window.WonderPush = window.WonderPush || [];
WonderPush.push(function() {
  WonderPush.getInstallationId().then(console.log);
});

Note: The Installation ID is obtained asynchronously after the WonderPush SDK is initialized and has contacted the WonderPush servers. Changing the User ID will make the SDK use a new installation and this asynchronous process starts anew. Once the SDK has obtained an Installation ID, it will remember it for subsequent use and it will be available right away.

Native Subscription Options

These initialization options can be passed to init under the subscriptionNative field, to trigger the native subscription dialog of your web browser.

User Interfaces

showSubscriptionDialog

Show the subscription dialog as configured by the subscriptionDialog init options.

The subscription dialog is shown from the top of the window and looks like this:

Subscription Dialog Options

These initialization options must be placed within your call to init, inside the subscriptionDialog field.

For examplem this corresponds to the default options:

window.WonderPush = window.WonderPush || [];
WonderPush.push(["init", {
  // ... other options
  subscriptionDialog: {
    triggers: {},
    title: "Would you like to subscribe to push notifications?",
    message: "You can always unsubscribe at any time.",
    positiveButton: "Subscribe",
    negativeButton: "Later",
  },
}]);

Trigger Options

Trigger options are used to trigger behaviors based on the navigation of the user. Trigger options can be combined to create complex behaviors.

For example:

window.WonderPush = window.WonderPush || [];
WonderPush.push(["init", {
  // ... other options
  subscriptionDialog: {
    triggers: {
      minPages: 3,
      snooze: 86400000, // 24 hours
    }
  },
}]);

In this example, the subscription dialog automatically appears after 3 page views. If the user closes or dismiss the dialog, the dialog will appear again after the user performed 3 more page views and 24 hours have elapsed.

Trigger options are:

showSubscriptionBell

Show or hide the subscription bell as configured by the subscriptionBell init options. The subscription bell sits at the bottom left or right corner of the window and can be used to give users a permanent access to subscribe to notifications, unsubscribe, and manage their private data

The subscription bell looks like this:

window.WonderPush = window.WonderPush || [];
WonderPush.push(function() {
  // Hide the subscription bell
  WonderPush.showSubscriptionBell(false);
});

<!-- A button that shows the subscription bell -->
<a href="#" 
   onclick="WonderPush.showSubscriptionBell(true); return false;"
   >Show subscription bell</a>

Subscription Bell Options

These initialization options must be specified within your call to init, inside the subscriptionBell field.

showSubscriptionSwitch

Appends a subscription switch dynamically to the provided parentNode, typically used for Single Page Applications.

WonderPush = window.WonderPush || [];
WonderPush.push(function() {
    var parentNode = document.getElementById('theIdOfSomeElementYouWantToAddASwitchTo');
    WonderPush.showSubscriptionSwitch(parentNode);
});

The subscription switch allows users to subscribe to notifications and unsubscribe.

An alternative to using showSubscriptionSwitch is to create an element with id wonderpush-subscription-switch. At page load time, WonderPush will turn this element into a subscription switch. Most of the options below can be specified directly on the wonderpush-subscription-switch element itself via data- attributes:

<div id="wonderpush-subscription-switch"
        data-sentence="Subscribe to notifications: "></div>

The subscription switch looks like this:

Subscription Switch Options

Most of these initialization options can be specified within your call to init inside the subscriptionSwitch field, or directly in your call to showSubscriptionSwitch, to the exception of switchElementId that can only be specified at init time.

showTagSwitches

Appends a collection of tag switches to the provided parentNode.

The tag switches allow users to subscribe to notifications and tag themselves at the same time. You can use tag switches to let users subscribe to topics of their choice for example.

An alternative to using showTagSwitches is to create an element with class wonderpush-tag-switch. At page load time, WonderPush will turn this element into a tag switch. Most of the options below can be specified directly on the wonderpush-tag-switch element itself via data- attributes:

<script>
  window.WonderPush = window.WonderPush || [];
	WonderPush.push(function() {
  	WonderPush.showTagSwitches(document.body, [
      {sentence: 'Sports: ', tag: 'sports'},
    ]);
  });
</script>

Would be equivalent to:

<div class="wonderpush-tag-switch"
     data-sentence="Sports: "
     data-tag="sports"></div>

And would render something like this:

Tag Switch Options

***** Either the tag or the field together with value options are mandatory. They define what tag is manipulated, or what value is to be put or removed and into which property field, when the switch is flipped.

Cross-domain popup window

When subscribing users from another domain than the one configured in your dashboard, a pop-up window will appear. This process is called cross-domain subscription.

Elements of this popup window are configurable via the Cross-domain options below.

Cross-domain Options

These options control the texts displayed by the cross-domain popup window.

For example, this corresponds to the default values:

window.WonderPush = window.WonderPush || [];
WonderPush.push(["init", {
  // ... other options
  optInOptions: {
    externalBoxMessage: "We'd like to send you notifications",
    externalBoxExampleTitle: "Example notification",
    externalBoxExampleMessage: "This is an example notification",
    externalBoxDisclaimer: "You can always unsubscribe at anytime.",
    externalBoxProcessingMessage: "Subscribing...",
    externalBoxSuccessMessage: "Thanks for subscribing!",
    externalBoxFailureMessage: "Sorry, something went wrong.",
    externalBoxTooLongHint: "Poor connection or private browsing?",
    externalBoxCloseHint: "Close",
    positiveButtonText: "Subscribe",
    negativeButtonText: "Later",
    },
}]);

Segmentation

Segmentation functions allow you to mark installations so they can be added to segments and you can send them targeted notifications later.

There are many ways of performing segmentation:

• Tags
• Events
• Installation properties

Tags are like labels you can stick on users. Use tags to create segments in your dashboard and send targeted push notifications. Example: all users that have the "customer" tag.

Events have a date, a type of your choice and attributes. Use events to create segments in your dashboard and send targeted push notifications. Example: all users that purchased in the last hour is a typical event-based segment.

Installation properties represent traits of the user. That's a good place to store age, gender and other data traditionally used for segmentation. Create property-based segments in your dashboard. Example: all users above 18 is a typical property-based segment.

trackEvent

Tracks a custom event of your choice. E.g. purchase.

Example:

window.WonderPush = window.WonderPush || [];
WonderPush.push(function() {

  WonderPush.trackEvent('purchase', {
    string_product: "Some product",
    float_price: 1.99,
  });

});

addTag

Adds one or more tags to the current installation.

window.WonderPush = window.WonderPush || [];
WonderPush.push(function() {

  WonderPush.addTag("customer");
  WonderPush.addTag("economics", "sport", "politics");

});

removeTag

Removes one or more tags from the current installation.

window.WonderPush = window.WonderPush || [];
WonderPush.push(function() {

  WonderPush.removeTag("customer");
  WonderPush.removeTag("economics", "sport", "politics");

});

removeAllTags

Removes all tags from the current installation.

hasTag

Tests whether a given tag is attached to the current installation.

window.WonderPush = window.WonderPush || [];
WonderPush.push(function() {

  WonderPush.hasTag("customer").then(function(isCustomer) {
    if (isCustomer) {
      // Display paid features
    }
  });

});

getTags

Returns all the tags attached to the current installation as a promise resolving to an array of strings.

window.WonderPush = window.WonderPush || [];
WonderPush.push(function() {

  WonderPush.getTags().then(function(tags) {
    // Work on the tags variable
  });

});

getPropertyValue

Returns a Promise that resolves to the value of a given property associated to the current installation.

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.

window.WonderPush = window.WonderPush || [];
WonderPush.push(function() {

  WonderPush.getPropertyValue("string_lastname").then(function(lastName) {
    // Use lastName
  });

});

getPropertyValues

Returns a Promise that resolves to an array of the values of a given property associated to the current installation.

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.

window.WonderPush = window.WonderPush || [];
WonderPush.push(function() {

  WonderPush.getPropertyValues("string_favorityPlayers").then(function(favoritePlayers) {
    // Use the favoritePlayers array
  });

});

addProperty

Adds the value to a given property associated to the current installation.

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.

window.WonderPush = window.WonderPush || [];
WonderPush.push(function() {
  
  // You can add a single value
  WonderPush.addProperty("string_interests", "sport");
  
  // You can add multiple values
  WonderPush.addProperty("string_interests", "sport", "entertainment");
  
  // You can add an array of values
  WonderPush.addProperty("string_interests", ["sport", "entertainment"]);
  
});

removeProperty

Removes the value from a given property associated to the current installation.

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.

window.WonderPush = window.WonderPush || [];
WonderPush.push(function() {
  
  // You can remove a single value
  WonderPush.removeProperty("string_interests", "sport");
  
  // You can remove multiple values
  WonderPush.removeProperty("string_interests", "sport", "entertainment");
  
  // You can remove an array of values
  WonderPush.removeProperty("string_interests", ["sport", "entertainment"]);
  
});

setProperty

Sets the value to a given property associated to the current installation.

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

window.WonderPush = window.WonderPush || [];
WonderPush.push(function() {
  
  // You can set a single value
  WonderPush.setProperty("bool_isCustomer", true);
  
  // You can remove a field using null or undefined
  WonderPush.setProperty("int_age", null);
  
  // You can set an array of values
  WonderPush.setProperty("string_interests", ["sport", "entertainment"]);
  
});

unsetProperty

Removes the value of a given property associated to the current installation.

The previous value is replaced with null.

window.WonderPush = window.WonderPush || [];
WonderPush.push(function() {
  
  WonderPush.unsetProperty("string_favoritePlayers");
  
});

putProperties

Updates the properties of the current installation. Omitting a previously set property leaves it untouched. To remove a property, you must pass it explicitly with a value of null.

Example:

window.WonderPush = window.WonderPush || [];
WonderPush.push(function() {

  // Puts the int_age property with a value of 34 in the installation
  WonderPush.putProperties({
    int_age: 34
  });
});

getProperties

Returns a Promise that resolves to an Object containing the properties of the current installation.

Example:

window.WonderPush = window.WonderPush || [];
WonderPush.push(function() {

  WonderPush.getProperties().then(function(properties) {
    console.log("Properties of the current installation are:", properties);
  });
});

useGeolocation

Attach GeoLocation position to this installation.

getCountry

Returns the user's country, either as previously stored, or undefined.

setCountry

Overrides the user's country. Defaults to getting the country code from the system default locale.

You should use an ISO 3166-1 alpha-2 country code, eg: US, FR, GB. Use null to disable the override.

getCurrency

Returns the user's currency, either as previously stored, or undefined.

setCurrency

Overrides the user's currency. Defaults to getting the currency code from the system default locale.

You should use an ISO 4217 currency code, eg: USD, EUR, GBP. Use null to disable the override.

getLocale

Returns the user's locale, either as previously stored, or as guessed from the system.

setLocale

Overrides the user's locale. Defaults to getting the language and country codes from the system default locale.

You should use an xx-XX form of RFC 1766, composed of a lowercase ISO 639-1 language code, an underscore or a dash, and an uppercase ISO 3166-1 alpha-2 country code. Use null to disable the override.

getTimeZone

Returns the user's time zone, either as previously stored, or as guessed from the system.

setTimeZone

Overrides the user's time zone. Defaults to getting the time zone code from the system default locale.

You should use an IANA time zone database codes, Continent/Country style preferably like Europe/Paris, or abbreviations like CET, PST, UTC, which have the drawback of changing on daylight saving transitions. Use null to disable the override.

Privacy

setUserConsent

Sets user privacy consent. You must use push with the array syntax to call setUserConsent.

Works in conjunction with the requiresUserConsent init option.

When this option is specified, calls to push are blocked and any method of the SDK results in rejecting Promises until setUserConsent is called with true.

Calling setUserConsent with false blocks the SDK again.

window.WonderPush = window.WonderPush || [];
WonderPush.push(["setUserConsent", true]);

clearEventsHistory

Instructs to delete any event associated with the all installations present on the device, locally and on WonderPush servers.

clearPreferences

Instructs to delete any custom data (including installation properties) associated with the all installations present on the device, locally and on WonderPush servers.

clearAllData

Instructs to delete any event, installation and potential user objects associated with all installations present on the device, locally and on WonderPush servers.

downloadAllData

Initiates the download of all the WonderPush data relative to the current installation, in JSON format.

Custom DOM Events

The WonderPush SDK fires a few custom DOM events on the window object. The type of event is always WonderPushEvent and the payload's name property determines what type of WonderPushEvent is emitted.

window.addEventListener('WonderPushEvent', function(event) {
  var eventType = event.detail ? event.detail.name  : undefined;
  // Do something in response to this eventType
});

subscription

The event type subscription allows you to listen to users subscribing and unsubscribing. The value of the event.detail.state property tells you what just happened. It is WonderPush.SubscriptionState.SUBSCRIBED when user just subscribed, WonderPush.SubscriptionState.UNSUBSCRIBED when user just unsubscribed. This event is fired as soon as the SDK is loaded, to give you the initial state, plus everytime it changes, so you can follow the current state.

For example:

// Store the previous subscription state to observe transitions
var previousWonderPushSubscriptionState;
window.addEventListener('WonderPushEvent', function(event) {
  if (!event.detail || event.detail.name !== 'subscription') return;
  if (previousWonderPushSubscriptionState === WonderPush.SubscriptionState.NOT_SUBSCRIBED && event.detail.state === WonderPush.SubscriptionState.SUBSCRIBED) {
    // Transitioning from not subscribed to subscribed
    console.log('User just subscribed!');
  } else if (previousWonderPushSubscriptionState === WonderPush.SubscriptionState.UNSUBSCRIBED && event.detail.state === WonderPush.SubscriptionState.SUBSCRIBED) {
    // Transitioning from unsubscribed to subscribed
    console.log('User just resubscribed!');
  } else if (previousWonderPushSubscriptionState === WonderPush.SubscriptionState.SUBSCRIBED && event.detail.state === WonderPush.SubscriptionState.UNSUBSCRIBED) {
    // Transitioning from subscribed to unsubscribed
    console.log('User just unsubscribed!');
  } else if (previousWonderPushSubscriptionState === undefined && event.detail.state === WonderPush.SubscriptionState.SUBSCRIBED) {
    // Initial state is subscribed
    console.log('User already subscribed!');
  } else if (previousWonderPushSubscriptionState === undefined && event.detail.state === WonderPush.SubscriptionState.NOT_SUBSCRIBED) {
    // Initial state is not subscribed
    console.log('User not subscribed (yet)!');
  } else if (previousWonderPushSubscriptionState === undefined && event.detail.state === WonderPush.SubscriptionState.UNSUBSCRIBED) {
    // Initial state is unsubscribed
    console.log('User already unsubscribed!');
  }
  previousWonderPushSubscriptionState = event.detail.state;
});

session

The event type session allows you to listen to the SDK creating an installation on WonderPush servers. The value of the event.detail.state property tells you what just happened. It is WonderPush.SessionState.INIT_SUCCESS when the installation has just been created. This event is fired as soon as the SDK is loaded, to give you the initial state, plus everytime it changes, so you can follow the current state.

For instance you can use this to reliably get the installationId whenever it gets known:

new Promise((resolve, reject) => {
    window.WonderPush = window.WonderPush || [];
    WonderPush.push(function() {
        if (WonderPush.getSessionState() === WonderPush.SessionState.INIT_SUCCESS) {
            WonderPush.getInstallationId().then(resolve, reject);
            return;
        }
        var listener = function(event) {
            if (event.detail.name !== 'session') return;
            if (event.detail.state === WonderPush.SessionState.INIT_SUCCESS) {
                window.removeEventListener('WonderPushEvent', listener);
                WonderPush.getInstallationId().then(resolve, reject);
            };
        };
        window.addEventListener('WonderPushEvent', listener);
    });
}).then(installationId => {
    // Do something with the installationId
});

trackEvent

The event type trackEvent allows you to listen to every event send by the WonderPush SDK and react to it.

window.addEventListener('WonderPushEvent', function(event) {
  if (!event.detail || event.detail.name !== 'trackEvent') return;
  console.log('WonderPush event tracked:', event.detail.event);
});

Note that the @NOTIFICATION_OPENED and @NOTIFICATION_RECEIVED events are only triggered inside the Service Worker. You will not be able to listen for them from your website pages. You need to run this code in your Service Worker file.

Popups (formerly known as In-app messaging)

setInAppMessagingDisplayCallback

Setting the display callback lets you handle the display of a popup yourself. This method takes a single argument: a function that accepts two arguments:

• the popup to display
• an InAppMessageReportingCallback object you must call when the popup is displayed, clicked or dismissed.

Return true when you wish to handle the display yourself, false when you want WonderPush to handle the display.

window.WonderPush = window.WonderPush || [];
WonderPush.push(function() {
  
  WonderPush.setInAppMessagingDisplayCallback(function(inApp, reportingCallback) {
    // Display popup
    // Report popup viewed
    // Report any popup clicks
    return true; // false if you don't want WonderPush to handle the display
  });
  
});

See handling the display of popups yourself for details on how to implement this.

setInAppMessagesSuppressed

Lets you disable or enable popups.

WonderPush.push(function() {
  // Disables popups
  WonderPush.setInAppMessagesSuppressed(true);
});

getInAppMessagesSuppressed

Whether popups are disabled.

Migrating from previous versions of the Website SDK

Previous versions of the Website SDK provided functions called init and ready and most other functions had different names. Migrating to this new API is automatic, you do not need to do anything to call the new functions. The old ones remain available and you can just call the new ones on the WonderPushSDK object you're used to manipulate.

If you wish to migrate to the new way of doing things, which we recommend, perform all of these steps:

1. Incorporate the async script tag and snippet
2. Remove the javascript snippet that looked like (function(w,d,s,i,n)….
3. Change your call to init to use the array syntax of push.

Change:

// DEPRECATED
WonderPush.init({
    webKey: "YOUR_WEBKEY",
});

to:

// VALID
window.WonderPush = window.WonderPush || [];
WonderPush.push(["init", {
    webKey: "YOUR_WEBKEY",
}]);

4. Change your calls to ready to use the callback syntax of push. To ease the transition, you can also simply alias ready to push like this:

window.WonderPush = window.WonderPush || [];
WonderPush.ready = WonderPush.push;

// You can continue to use `ready` with the same syntax as before
WonderPush.ready(function(WonderPushSDK) {
  // Do something with WonderPushSDK, or WonderPush indifferently
});