The Installation object

This object describes a push notification installation.

The installation object represents the link between a device or browser and a WonderPush project. It is also bound to a given userId, if you are using this feature. This means that when a user logs and you change the userId used in the SDKs, another installation is created to handle this brand new profile on the same device.

Installation objects for your project are listed on every segment detail page of the online dashboard.

Installation objects hold the most important piece of data: the push token. The push token is required by device makers (Apple for iOS devices, Google for Android devices and Chrome browsers, Mozilla for Firefox browsers) in order to send a push notification to the corresponding device.

Installation objects also hold informative data about the device they are linked to. WonderPush lets you use this data for segmentation.

A sample installation

Below is a JSON representation of an example installation object. In this document, we'll go through all its fields.

{
  "id": "e2ba48f97a45be39f6c921e7b7a2adf65ad451b5",
  "applicationId": "01906i1feoq2cu1p",
  "userId": null,
  "creationDate": 1410539794529,
  "updateDate": 1410539796299,
  "accessToken": "Hkn6z9fZCEUJBvoRtasoqT2LDYPxDOh4ftGQRpnEn71NFw4VPQdySx8gJi7xrwHWl",
  "application": {
    "id": "01906i1feoq2cu1p",
    "integrator": "wonderpush-cordova-sdk-2.0.0",
    "sdkVersion": "Android-1.1.0.0",
    "version": "1.0",
    "apple": { // iOS only
      "appId": "N23GS8SFD9.com.mycompany.myapp",
      "apsEnvironment": "production", // or "development"
      "backgroundModes": ["remote-notification"]
    }
  },
  "device": {
    "id": "c51c72f4a3700183",
    "federatedId": "0:ef5c2057-7b49-49f8-835e-e4dd615069a2",
    "platform": "Android",
    "screenHeight": 1186,
    "model": "Nexus 4",
    "osVersion": "19",
    "screenWidth": 768,
    "brand": "LGE",
    "configuration": {
      "carrier": "Bouygues Telecom",
      "country": "FR",
      "currency": "EUR",
      "locale": "fr_FR",
      "timeZone": "Europe/Paris"
    },
    "screenDensity": 320
  },
  "preferences": {
    "subscriptionStatus": "optIn",
    "subscribedToNotifications": true,
    "osNotificationsVisible": true,
    "disabledAndroidChannels": ["foo", "bar"] // Android only
  },
  "pushToken": {
    "meta": {
      "updateDate": 1410539796298
    },
    "data": "02J0fDm4dwsAylLXKr47YhNwEaZU1EfcLww5LGlye_5mGGgaGcbrXtXU6HKCUXabGUHBNX0V4htJvHBAflIgABe4H5SskfwA_Ie3WHmjAfiy2whXUvMWK5gH6jRZOwQJltiMbilfoPxvF",
    "senderIds": ["123456789"], // Android only
    "applicationServerKey": "base64urlsafe", // Web only
    "auth": "base64urlsafe", // Web only
    "p256dh": "base64urlsafe", // Web only
    "expirationDate": 1577836799999, // Web only
    "origin": "https://your.domain", // Web only
    "userVisibleOnly": true // Web only
  },
  "custom": {
    "tags": ["foo", "bar"],
    // The following demonstrate the possible properties an installation can hold,
    // not the exact properties name you might be using in your project.
    "byte_foo": 127,
    "short_foo": 32767,
    "int_foo": 2147483647,
    "long_foo": 9223372036854775807,
    "float_foo": 0.0,
    "double_foo": 0.0,
    "bool_foo": true,
    "string_foo": "bar",
    "date_foo": "2019-12-31T23:59:59.999Z",
    "date_bar": 1577836799999,
    "geoloc_foo": {"lat": 48.85837, "lon": 2.294481},
    "geoloc_bar": "48.85837,2.294481",
    "geoloc_qux": [2.294481, 48.85837],
    "string_anyPropertyType": ["can", "also", "store", "an", "array"]
  }
}

Installation ID

A unique identifier for this installation object. Use it to send a notification to this installation only, via the API or the online dashboard with an installation id segmentation rule.

📘

What is the difference between Installation ID and Device ID?

On a given device, for a given application, you will have a single deviceId.
If you change the userId then new installations will be created to represent these new profiles, and you will have multiple installationIds.
In a sense, the installationId is a hash of your WonderPush applicationId, the device platform (Android/iOS), deviceId and userId.

User ID

If you've attached this installation to one of your own user IDs, this field will hold its value. Null otherwise.

Creation date

Number of milliseconds since 01/01/1970 UTC when the installation was created.

Update date

Number of milliseconds since 01/01/1970 UTC when the installation was updated.

Access token

The access token that this installation uses to converse with WonderPush via our SDKs.

Application ID

The unique identifier of your WonderPush project.

Application SDK version

The version of our SDK that was last used to create or update this installation.

Application Version

The version of your application that was last used to create or update this installation. There's a dedicated segmentation criterion for this data.

Device ID

A UUIDv4, a random unique identifier that is created during the first run and reused until the application is uninstalled. Will be reused for all the installations of a given project on a particular device.

Device Platform

One of iOS, Android or Web.

Device screen width / height

The width / height of the screen.

Device model

The model of the mobile device or user agent of the browser.

Device OS version

The version of the mobile device's OS or browser.

Device brand

Apple for iOS devices, name of the maker for Android devices, Chrome or Firefox for web browsers.

Device carrier

For mobile devices, name of the carrier when available.

Device configuration country

For mobile devices, ISO code of the carrier's country when available.

Device configuration currency

For mobile devices, ISO code of the carrier's currency when available.

Device configuration locale

ISO code of the device's or web browser's locale.

Device configuration timezone

ISO code of the device's or web browser's timezone.

Device screen density

For mobile devices, the pixel density ratio. 2 for Apple retina devices.

Preferences subscription status

The preferences subscription status lets you find out if users accept to be contacted.
optIn for installations that have accepted push notifications, optOut for installations that do not wish to be contacted. Missing or null otherwise.

Push token

The push token is a piece of data required by device makers in order to send a push notification to the corresponding device.

Every device maker has their own wording (some call it device token) and documentation on the subject:

Since WonderPush is cross platform, we just talk about push token.

Push token meta update date

Number of milliseconds since 01/01/1970 UTC when the push token was updated or created.

Properties

Properties you put using our SDKs are stored in an object accessible via the key custom.

Infering the subscription state from this object

Here are the rules to determine whether an installation is opt-in, soft opt-out or opt-out:

  1. If the pushToken.data field is empty, the installation is opt-out.
  2. If the pushToken.data field is filled but the preferences.subscriptionStatus field is "optOut", the installation is soft opt-out.
  3. If the pushToken.data field is filled but the preferences.subscriptionStatus field is not "optOut" (that is "optIn" or empty), the installation is opt-in.