The WonderPush Developer Hub

Welcome to the WonderPush developer hub. You'll find comprehensive guides and documentation to help you start working with WonderPush as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    


Event-based segmentation lets you target users based on their journey

Events are recorded when interesting things take place in the user journey. Events may contain additional information about what happened. They are stored on WonderPush servers for 3 months.

A few common examples of events are:

  • user purchased something,
  • user read an article,
  • user added something to his/her cart.

There are 2 pieces of information in an event:

  1. its name,
  2. an optional collection of attributes further describing what happened.

Built-in events

WonderPush automatically keeps track of a number of events. They are called build-in events and they share one important characteristic: their name all start with the @ character.

Here's a list of build-in events:


This event represent the beginning of a user session. It occurs whenever users hit your app/website and their last interaction is older than 30 minutes (15 minutes if they are clicking on a notification).

Use this event to target users that visited your app/website recently or a long time ago.


This event occurs whenever a notification is sent to a user. Please note that not all notifications are delivered. If you're looking for delivered notifications, use the @NOTIFICATION_RECEIVED event.


This event occurs whenever a notification is delivered to a user.


This event occurs when a users clicks a notification, or a notification button (except the dismiss button). When a button is clicked, the @NOTIFICATION_OPENED event has a buttonLabel attribute that contains the label of the button.


This event occurs whenever we try to send a notification and fail. Common failure reasons are:

  • the push token was invalidated (because the user removed the notification permission)
  • an expired push certificate (mobile only)
  • a configuration issue.

If you are seeing many failures, do not hesitate to contact us by chat, we are here to assist.


This event occurs whenever users browse your app/website or leave. It contains 3 attributes:

  • fromDate: the date when the presence started
  • untilDate: the date when the presence ended (please note that this date might be in the future)
  • elapsedTime: the amount of time between fromDate and untilDate
    Use this event to target users that are currently using or not using your app/website.


This event occurs whenever a user signs up for push notifications.

There a a few subtypes for this event:

  • new: an opt-out installation (the default when it just got created) becomes opt-in
  • soft: a soft opt-out installation becomes opt-in
  • moved: a opt-out installation becomes opt-in because of a userId change


This event occurs whenever a users opts out of push notifications. See Soft opt-out for a detailed explanation of how opting out works.

There are a few subtypes for this event:

  • soft: an opt-in installation becomes soft opt-out
  • removed: rare case where the SDK removes a no longer valid push token
  • moved: an opt-in installation becomes opt-out because of a userId change
  • invalidated: the push token is reported as invalid when we try to push it, the installation hence becomes opt-out, this is what happens on uninstalls

Your own events

You can track your own events. Their name cannot start with @.

There are multiple ways to track an event:

  • Client-side, by writing some code in your app/website
  • Server-side, by calling the REST API
  • In response to a user click on a notification

Event attributes

Your events can host attributes with the data of your choice. These attributes are prefixed by their type. For example, an attributes containing a string value must have a name that starts with string_. See Format of property names for more detail.

Tracking an event on the client side

All our SDKs allow you to track events. The method/function is called trackEvent. Here's a simple example of tracking a purchase event of a pair of trousers worth $49.99.

JSONObject attributes = new JSONObject();
attributes.put("string_category", "trousers");
attributes.put("float_price", 49.99f);
attributes.put("string_currency", "usd");
WonderPush.trackEvent("purchase", attributes);
WonderPush.trackEvent("purchase", [
  "string_category": "trousers",
  "float_price": 49.99,
  "string_currency": "usd"
[WonderPush trackEvent:"purchase" withData:@{
  @"string_category": @"trousers",
  @"float_price": @(49.99),
  @"string_currency": @"usd"
window.WonderPush = window.WonderPush || [];
    WonderPush.trackEvent("purchase", {
        string_category: "trousers",
      float_price: 49.99,
      string_currency: "usd"
WonderPush.trackEvent("purchase", {
  string_category: "trousers",
  string_currency: "usd",
  float_price: 49.99,
  string_currency: "usd"

Tracking an event on the server side

This is easily achieved using the /events call of our REST API.

In the following example we track a purchase event of a pair of trousers worth $49.99. Adapt YOUR_ACCESS_TOKEN, YOUR_USER_ID and YOUR_INSTALLATION_ID.

curl --request POST \
  --url '' \
  --header 'content-type: application/json' \
  --data '{"userId":"YOUR_USER_ID", \
  "installationId":"YOUR_INSTALLATION_ID", \
  "body":{"type":"purchase","custom":{ \
  "string_category":"trousers", \

Tracking an event in response to a user click on a notification

Just head over to the Compose tab of the Create/edit notification page and choose Add action and Track event for the notification itself or for any button.


Updated 3 days ago

What's Next



Event-based segmentation lets you target users based on their journey

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.