Cordova SDK Reference
Cordova SDK Reference
Configuration options | |
CLIENT_ID | REQUIRED. The client ID found in your WonderPush dashboard. |
CLIENT_SECRET | REQUIRED. The client secret found in your WonderPush dashboard. |
SENDER_ID | The sender ID found in your Firebase Cloud Messaging settings. |
LOGGING | Controls debug logging. Defaults to false. |
REQUIRES_USER_CONSENT | Controls whether user consent is required for the SDK to operate. Defaults to false. |
Subscribing users | |
subscribeToNotifications | Prompts user to subscribe to push notifications. |
unsubscribeFromNotifications | Unsubscribes user from push notifications. |
isSubscribedToNotifications | Tells whether user is subscribed to push notifications. |
Segmentation | |
trackEvent | Sends an event with a name and payload of your choice. |
addTag | Adds one or more tags to this installation. |
removeTag | Removes one or more tags from this installation. |
removeAllTags | Removes all tags from this installation. |
hasTag | Tests whether a given tag is attached to this installation. |
getTags | Returns all the tags attached of this installation. |
getPropertyValue | Returns the value of a given property associated to this installation. |
getPropertyValues | Returns an immutable list of the values of a given property associated to this installation. |
addProperty | Adds the value to a given property associated to this installation. |
removeProperty | Removes the value from a given property associated to this installation. |
setProperty | Sets the value to a given property associated to this installation. |
unsetProperty | Removes the value of a given property associated to this installation. |
putProperties | Associates the provided name/value pairs to this installation. |
getProperties | Returns all the name/value pairs associated to this installation using putProperties. |
getCountry | Returns the user's country. |
setCountry | Overrides the user's country. |
getCurrency | Returns the user's currency. |
setCurrency | Overrides the user's currency. |
getLocale | Returns the user's locale. |
setLocale | Overrides the user's locale. |
getTimeZone | Returns the user's time zone. |
setTimeZone | Overrides the user's time zone. |
User IDs | |
setUserId | Assigns your own user ID to an installation. |
getUserId | Returns the user ID you've assigned to this installation if any. |
Installation info | |
getInstallationId | Returns the installationId identifying this installation in your application. |
getPushToken | Returns the push token (also called registration id by FCM). |
Privacy | |
getUserConsent | Queries privacy consent. |
setUserConsent | Provides privacy consent. |
clearEventsHistory | Clears all events recorded using trackEvent. |
clearPreferences | Clears all the name/value pairs associated to this installation using putProperties. |
clearAllData | Deletes any event, installation and potential user objects associated with all installations present on the device. |
downloadAllData | Initiates the download of all the WonderPush data related to the current installation, in JSON format. |
Debug | |
setLogging | Enables or disables verbose logging of WonderPush. |
Configuration options
Configuring the WonderPush Cordova SDK is done when you add it to your Cordova project, like this:
cordova plugin add wonderpush-cordova-sdk --variable CONFIGURATION_OPTION=VALUE --variable OTHER_CONFIGURATION_OPTION=OTHER_VALUE
Make sure you specify all the required options at once. That means
CLIENT_ID
andCLIENT_SECRET
at least.
CLIENT_ID
REQUIRED. The client id is used to identify the WonderPush project to work on.
cordova plugin add wonderpush-cordova-sdk --variable CLIENT_ID=VALUE
CLIENT_SECRET
REQUIRED. The client secret used to secure network calls.
cordova plugin add wonderpush-cordova-sdk --variable CLIENT_SECRET=VALUE
SENDER_ID
The Firebase FCM Sender ID used to register to push notifications.
By default, the SDK will use the Sender ID of the Firebase account integrated into your app if any, or will fall back to WonderPush own Sender ID, which is convenient but cannot offer push token portability.
cordova plugin add wonderpush-cordova-sdk --variable SENDER_ID=VALUE
LOGGING
Controls debug logging.
The default is false
.
cordova plugin add wonderpush-cordova-sdk --variable LOGGING=true
You can set this at runtime using the
setLogging()
method.
REQUIRES_USER_CONSENT
Controls whether user consent is required before doing anything.
The default is false
.
cordova plugin add wonderpush-cordova-sdk --variable REQUIRES_USER_CONSENT=true
Subscribing users
subscribeToNotifications
subscribeToNotifications
Subscribes to push notifications. Accepts an optional callback argument, called as soon as the SDK noted the desire to subscribe, should a prompt take place or not.
WonderPush.subscribeToNotifications(function() {
console.log("User subscribed to notifications");
});
// You can also use this variation that will show an alert dialog
// to Android users who have repeatedly denied the permission, taking them to the settings
// of your app where they can flip the permission switch:
WonderPush.subscribeToNotifications(true, function() {
console.log("User subscribed to notifications");
});
unsubscribeFromNotifications
unsubscribeFromNotifications
Unsubscribes from push notifications. Accepts an optional callback argument, called upon successful unsubscription.
This method marks the user as soft opt-out.
WonderPush.unsubscribeFromNotifications(function() {
console.log("User unsubscribed");
});
isSubscribedToNotifications
isSubscribedToNotifications
Accepts a callback argument called with a boolean, true
meaning that the user is subscribed to notifications, false
if user hasn't subscribed, has unsubscribed or if consent is required and not granted.
WonderPush.isSubscribedToNotifications(function(isSubscribed) {
console.log(isSubscribed ? "User is subscribed" : "User is not subscribed");
});
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 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
trackEvent
Tracks a custom event of your choice. E.g. purchase
.
Parameter | Type | Description |
---|---|---|
type | String | Required The type of the event to track. Event names starting with @ are reserved for internal use and cannot be used here. |
attributes | Object | Optional. Attributes associated with this event. See format of property names for detailed syntax. |
callback | Function | Optional. A success callback. |
Example:
var attributes = {
string_product: "Some product",
float_price: 1.99,
};
WonderPush.trackEvent("purchase", attributes, function() {
console.log("Event tracked");
});
addTag
addTag
Adds one or more tags to the current installation.
Parameter | Type | Description |
---|---|---|
tag | String or Array of strings | A single tag, or an array of tags to be added. |
callback | Function | Optional. A success callback. |
WonderPush.addTag("customer", function() {
console.log("Success");
});
WonderPush.addTag(["economics", "sport", "politics"], function() {
console.log("Success");
});
removeTag
removeTag
Removes one or more tags from the current installation.
Parameter | Type | Description |
---|---|---|
tag | String or Array of strings | A tag, or list of tags, to be removed. |
callback | Function | Optional. A success callback. |
WonderPush.removeTag("customer", function() {
console.log("Success");
});
WonderPush.removeTag(["economics", "sport", "politics"], function() {
console.log("Success");
});
removeAllTags
removeAllTags
Removes all tags from the current installation.
Parameter | Type | Description |
---|---|---|
callback | Function | Optional. A success callback. |
WonderPush.removeAllTags(function() {
console.log("Success");
});
hasTag
hasTag
Tests whether a given tag is attached to the current installation.
Parameter | Type | Description |
---|---|---|
tag | String | The tag to test. |
callback | Function | A callback accepting a Boolean as single argument representing the result of the check. |
WonderPush.hasTag("customer", function(hasTag) {
console.log(hasTag ? "User is a customer" : "User is not a customer");
});
getTags
getTags
Accepts a callback and calls it with all the tags attached to the current installation as an array of strings.
Parameter | Type | Description |
---|---|---|
callback | Function | A function accepting an array of strings as single argument. |
WonderPush.getTags(function(tags) {
console.log("User tags:", tags.join(', '));
});
getPropertyValue
getPropertyValue
Accepts a property name and a callback. Calls the callback with the value of the 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.
Parameter | Type | Description |
---|---|---|
property | String | The name of the property whose value we'll retrieve |
callback | Function | A callback accepting a single value argument |
WonderPush.getPropertyValue("string_lastname", function(value) {
console.log("Last name is", value);
});
getPropertyValues
getPropertyValues
Returns an list 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 null
if the property is absent. Returns an array wrapping any scalar value held by the property.
WonderPush.getPropertyValues("string_favoritePlayers", function(values) {
console.log("Favorite players:", values.join(", "));
});
addProperty
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.
See format of property names for detailed syntax.
Parameter | Type | Description |
---|---|---|
name | String | The name of the property. |
value | Scalar or Array | The value to add |
callback | Function | Optional. A success callback. |
// You can add a single value
WonderPush.addProperty("string_interests", "sports", function() {
console.log("Success");
});
// You can add an array of values
WonderPush.addProperty("string_interests", ["sports", "entertainment"], function() {
console.log("Success");
});
removeProperty
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 the given values are removed, even if it is present multiple times.
Parameter | Type | Description |
---|---|---|
name | String | The name of the property |
value | Scalar or Array | The value to remove |
callback | Function | Optional. A success callback. |
// You can remove a single value
WonderPush.removeProperty("string_interests", "sports", function() {
console.log("Success");
});
// You can remove an array of values
WonderPush.removeProperty("string_interests", ["sports", "entertainment"], function() {
console.log("Success");
});
setProperty
setProperty
Sets the value to a given property associated to the current installation.
The previous value is replaced entirely. The value can be a String
, Boolean
, Number
, Object
, Array
(which has the same effect as unsetProperty).
See format of property names for detailed syntax.
Parameter | Type | Description |
---|---|---|
name | String | The name of the property |
value | Scalar or Array | The value to set |
callback | Function | Optional. A success callback. |
// You can set a single value
WonderPush.setProperty("bool_isCustomer", true, function() {
console.log("Success");
});
// You can remove a field using null
WonderPush.setProperty("int_age", null, function() {
console.log("Success");
});
// You can set an array of values
WonderPush.setProperty("string_interests", ["sports", "entertainment"], function() {
console.log("Success");
});
unsetProperty
unsetProperty
Removes the value of a given property associated to the current installation.
The previous value is replaced with null
.
Parameter | Type | Description |
---|---|---|
name | String | The property to unset. |
callback | Function | Optional. A success callback. |
WonderPush.unsetProperty("string_favoritePlayers", function() {
console.log("Success");
});
putProperties
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
.
Parameter | Type | Description |
---|---|---|
properties | Object | Properties to add or update. See format of property names for detailed syntax. |
callback | Function | Optional. A success callback |
Example:
var properties = {
int_age: 34,
string_name: "John Doe",
};
WonderPush.putProperties(properties, function() {
console.log("Success");
});
getProperties
getProperties
Accepts a callback, called with an object containing the properties of the current installation.
Parameter | Type | Description |
---|---|---|
callback | Function | The callback accepting a single object as argument containing the properties. |
For example:
WonderPush.getProperties(function(properties) {
console.log("Properties: ", properties);
});
getCountry
getCountry
Accepts a callback as unique argument, and calls it the user's country, either as previously stored, or as guessed from the system.
Parameter | Type | Description |
---|---|---|
callback | Function | A callback accepting a single argument of type String or null. |
Example:
WonderPush.getCountry(function(country) {
console.log("Country:", country);
});
setCountry
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.
Parameter | Type | Description |
---|---|---|
country | String | The ISO 3166-1 alpha-2 country code. |
callback | Function | Optional. A success callback. |
Example:
WonderPush.setCountry("US", function() {
console.log("Success");
});
getCurrency
getCurrency
Accepts a callback as unique argument, and calls it the user's currency, either as previously stored, or as guessed from the system.
Parameter | Type | Description |
---|---|---|
callback | Function | A callback accepting a single argument of type String or null. |
Example:
WonderPush.getCurrency(function(currency) {
console.log("Currency:", currency);
});
setCurrency
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.
Parameter | Type | Description |
---|---|---|
currency | String | The ISO 4217 currency code. |
callback | Function | Optional. A success callback. |
Example:
WonderPush.setCurrency("USD", function() {
console.log("Success");
});
getLocale
getLocale
Accepts a callback as unique argument, and calls it the user's locale, either as previously stored, or as guessed from the system.
Parameter | Type | Description |
---|---|---|
callback | Function | A callback accepting a single argument of type String or null. |
Example:
WonderPush.getLocale(function(locale) {
console.log("Locale:", locale);
});
setLocale
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.
Parameter | Type | Description |
---|---|---|
locale | String | The 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. |
callback | Function | Optional. A success callback. |
Example:
WonderPush.setLocale("en-US", function() {
console.log("Success");
});
getTimeZone
getTimeZone
Accepts a callback as unique argument, and calls it the user's time zone, either as previously stored, or as guessed from the system.
Parameter | Type | Description |
---|---|---|
callback | Function | A callback accepting a single argument of type String or null. |
Example:
WonderPush.getTimeZone(function(timeZone) {
console.log("Time zone:", timezone);
});
setTimeZone
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/City
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.
Parameter | Type | Description |
---|---|---|
timeZone | String | The time zone in the Continent/City form. |
callback | Function | Optional. A success callback. |
Example:
WonderPush.setTimeZone("America/New_York", function() {
console.log("Success");
});
setUserId
setUserId
Assigns your own user ID to an installation. See User IDs.
Parameter | Type | Description |
---|---|---|
userId | String | The user ID. |
callback | Function | Optional. A success callback. |
Example:
WonderPush.setUserId("YOUR_OWN_USER_ID", function() {
console.log("Success");
});
getUserId
getUserId
Accepts a callback as unique argument, and calls it the user ID you've assigned to this installation if any.
Parameter | Type | Description |
---|---|---|
callback | Function | A callback accepting a single argument of type String or null. |
Example:
WonderPush.getUserId(function(userId) {
console.log("User ID:", userId);
});
Installation info
getInstallationId
getInstallationId
Accepts a callback as unique argument, and calls it the installation ID.
Parameter | Type | Description |
---|---|---|
callback | Function | A callback accepting a single argument of type String. |
Example:
WonderPush.getInstallationId(function(installationId) {
console.log("Installation ID:", installationId);
});
getPushToken
getPushToken
Accepts a callback as unique argument, and calls it the push token (device token) of this installation if any.
Parameter | Type | Description |
---|---|---|
callback | Function | A callback accepting a single argument of type String or null. |
Example:
WonderPush.getPushToken(function(pushToken) {
console.log("Push token:", pushToken);
});
Privacy
getUserConsent
getUserConsent
Gets user privacy consent.
See setUserConsent
below.
Parameter | Type | Description |
---|---|---|
callback | Function | A success callback. |
Example:
WonderPush.getUserConsent(function(userConsent) {
console.log(userConsent);
});
setUserConsent
setUserConsent
Sets user privacy consent.
Works in conjunction with the REQUIRES_USER_CONSENT
configuration option.
If user consent is required, the SDK takes no action until user consent it provided by calling setUserConsent(true)
. Calling setUserConsent(false)
blocks the SDK again.
Parameter | Type | Description |
---|---|---|
consent | Boolean | Whether the user gave his/her consent. |
callback | Function | Optional. A success callback. |
Example:
WonderPush.setUserConsent(true, function() {
console.log("Success");
});
clearEventsHistory
clearEventsHistory
Instructs to delete any event associated with the all installations present on the device, locally and on WonderPush servers.
Parameter | Type | Description |
---|---|---|
callback | Function | Optional. A success callback. |
Example:
WonderPush.clearEventsHistory(function() {
console.log("Success");
});
clearPreferences
clearPreferences
Instructs to delete any custom data (including installation properties) associated with the all installations present on the device, locally and on WonderPush servers.
Parameter | Type | Description |
---|---|---|
callback | Function | Optional. A success callback. |
Example:
WonderPush.clearPreferences(function() {
console.log("Success");
});
clearAllData
clearAllData
Instructs to delete any event, installation and potential user objects associated with all installations present on the device, locally and on WonderPush servers.
Parameter | Type | Description |
---|---|---|
callback | Function | Optional. A success callback. |
Example:
WonderPush.clearAllData(function() {
console.log("Success");
});
downloadAllData
downloadAllData
Initiates the download of all the WonderPush data relative to the current installation, as JSON.
Parameter | Type | Description |
---|---|---|
callback | Function | A callback accepting a single argument: the user data. |
Example:
WonderPush.downloadAllData(function(userData) {
console.log("User data:", userData);
});
Debug
setLogging
setLogging
Parameter | Type | Description |
---|---|---|
enable | Boolean | Whether to enable verbose logging of the WonderPush SDK. |
callback | Function | Optional. A success callback. |
Enables or disables verbose logging of WonderPush.
WonderPush.setLogging(true, function() {
console.log("Success");
});
Updated over 1 year ago