Understanding data flow in WonderPush

Main concepts

Installations

The central object in WonderPush is the installation.

The installation object represents the link between a device or browser and a WonderPush project, for a given userId, by default anonymous. Installation objects hold the most important piece of data: the push token used to send a push notification. Installation objects also hold core properties like the device type, language; and custom properties and tags you have decided to add to fill your business needs.

Our SDKs are creating and updating these objects for you. You cannot modify them server-side.

Events

An installation can emit a number of events that are attached to it and tracked in a timeline.

Events are recorded when interesting things take place in the user journey. Some built-in events are application or website openings, notification receipts or clicks. You can also track any custom event to fill your business needs. They have a name and optional properties attached to them.

Users

Your end-users are sometimes identified within your application or website. You can have a link between your installations and some userId. It enables you to better integrate WonderPush with external systems that rely on such IDs, or segment the installations more easily within WonderPush with data that you may upload from your own servers.

The user object can hold custom properties that you modify server-side, and are not modifiable from our SDKs in the end-user devices.

A note on changing of userId:

As you may have noticed earlier, we said that an installation is tied to a given device or browser and a given userId.

Whenever the userId changes on your application or website, a new installation object is created. This is completely analogous to creating a brand new profile. Nothing is shared with the previously used installation, except for one identifier called deviceId.

📘

Devices

Devices are never represented as such within WonderPush. A given device or browser is merely identified by a random deviceId that is generated by the SDKs the first time an end-user opens your application or website.

A single device can only have a single push token for your application or website. Only one installation will hence bear a given push token at any time. The push token will be moved from installation to installation when you change the userId used.

Typical data flow

For a new anonymous push subscriber

When an end-user first opens your application or website, our SDKs will create a local representation of it to store its state. Typically you did not set a userId yet as the end-user is still unknown to you and has not created an account or logged in yet. As soon as the end-user subscribes an anonymous installation will be created on WonderPush servers and the SDKs will receive its installationId.

The SDK will then send the push token, the core properties and any custom properties or tags you may have set. It will also start to send the newly collected events, starting with the events collected within the session just before the opt-in: the application opening and presence.

WonderPush servers will process those changes and generate an @OPT_IN event.

All these events are associated with the installationId. Typically the userId will be null at this point and the field would simply be omitted.

After a subsequent login

When an end-user subscribed push notifications finally logs into your application or website, you will set its userId with any identifier you already have that represents the user in your database.

Our SDKs will then create a new blank installation associated with this userId, and then send the push token, the core properties. Note that because this is akin to loading a new profile, the installation has no custom properties or tags at the beginning, but you can add them at any time.

Newly collected events are now associated with the new installationId and the given userId.

As the new installation now has the push token, the WonderPush servers will generate an @OPT_IN event on the logged installation and an @OPT_OUT event on the anonymous installation and remove the push token from there.

After logout

When you unset the userId, our SDKs will move the push token back to the previous anonymous installation, and switch the custom properties and tags to take the one of that installation.

Newly collected events are now associated with the new installationId and no userId.

As the anonymous installation now has the push token, the WonderPush servers will generate an @OPT_IN event on the anonymous installation and an @OPT_OUT event on the logged installation and remove the push token from there.