Web Client 8.0.8

MpnDevice

MpnDevice

Class representing a device that supports Web Push Notifications.
It contains device details and the listener needed to monitor its status.
An MPN device is created from the application identifier, the platform and a device token (a.k.a. registration token) obtained from web push notifications APIs, and must be registered on the LightstreamerClient in order to successfully subscribe an MPN subscription. See MpnSubscription.
After creation, an MpnDevice object is in "unknown" state. It must then be passed to the Lightstreamer Server with the LightstreamerClient#registerForMpn method, which enables the client to subscribe MPN subscriptions and sends the device details to the server's MPN Module, where it is assigned a permanent device ID and its state is switched to "registered".
Upon registration on the server, active MPN subscriptions of the device are received and exposed with the LightstreamerClient#getMpnSubscriptions method.
An MpnDevice's state may become "suspended" if errors occur during push notification delivery. In this case MPN subscriptions stop sending notifications and the device state is reset to "registered" at the first subsequent registration.

Constructor

new MpnDevice(token, appId, platform)

Creates an object to be used to describe an MPN device that is going to be registered to the MPN Module of Lightstreamer Server.
During creation the MpnDevice tries to acquires any previously registered device token from localStorage. It then saves the current device token on localStorage. Saving and retrieving the previous device token is used to handle automatically the cases where the token changes. The MPN Module of Lightstreamer Server is able to move MPN subscriptions associated with the previous token to the new one.

Parameters:
Name Type Description
token String

the device token

appId String

the application identifier

platform String

either "Google" for Google's Firebase Cloud Messaging (FCM) or "Apple" for Apple Push Notification Service (APNs)

Throws:

IllegalArgumentException if token or appId is null or platform is not "Google" or "Apple".

Methods

addListener(listener)

Adds a listener that will receive events from the MpnDevice instance.
The same listener can be added to several different MpnDevice instances.

Lifecycle: a listener can be added at any time.

Parameters:
Name Type Description
listener MpnDeviceListener

An object that will receive the events as shown in the MpnDeviceListener interface.
Note that the given instance does not have to implement all of the methods of the MpnDeviceListener interface. In fact it may also implement none of the interface methods and still be considered a valid listener. In the latter case it will obviously receive no events.

getApplicationId() → {String}

The application ID of this MPN device. It is used by the server as part of the device identification.

Lifecycle: This method can be called at any time.

Returns:

the MPN device application ID.

Type
String

getDeviceId() → {String}

The server-side unique persistent ID of the device.
The ID is available only after the MPN device object has been successfully registered on the server. I.e. when its status is REGISTERED or SUSPENDED.
Note: a device token change, if the previous device token was correctly stored on localStorage, does not cause the device ID to change: the server moves previous MPN subscriptions from the previous token to the new one and the device ID remains unaltered.

Lifecycle: This method can be called at any time.

Returns:

the MPN device ID.

Type
String

getDeviceToken() → {String}

The device token of this MPN device. It is passed during creation and is used by the server as part of the device identification.

Lifecycle: This method can be called at any time.

Returns:

the MPN device token.

Type
String

getListeners() → {Array.<MpnDeviceListener>}

Returns an array containing the MpnDeviceListener instances that were added to this client.

Returns:

an Array containing the listeners that were added to this client. Listeners added multiple times are included multiple times in the array.

Type
Array.<MpnDeviceListener>

getPlatform() → {String}

The platform identifier of this MPN device. It equals Google or Apple and is used by the server as part of the device identification.

Lifecycle: This method can be called at any time.

Returns:

the MPN device platform.

Type
String

getPreviousDeviceToken() → {String}

The previous device token of this MPN device. It is obtained automatically from localStorage during creation and is used by the server to restore MPN subscriptions associated with this previous token. May be null if no MPN device has been registered yet on the application.

Lifecycle: This method can be called at any time.

Returns:

the previous MPN device token, or null if no MPN device has been registered yet.

Type
String

getStatus() → {String}

The status of the device.
The status can be:

Lifecycle: This method can be called at any time.

See:
Returns:

the status of the device.

Type
String

getStatusTimestamp() → {Number}

The server-side timestamp of the device status.

Lifecycle: This method can be called at any time.

See:
Returns:

The server-side timestamp of the device status.

Type
Number

isRegistered() → {boolean}

Checks whether the MPN device object is currently registered on the server or not.
This flag is switched to true by server sent registration events, and back to false in case of client disconnection or server sent suspension events.

Lifecycle: This method can be called at any time.

See:
Returns:

true if the MPN device object is currently registered on the server.

Type
boolean

isSuspended() → {boolean}

Checks whether the MPN device object is currently suspended on the server or not.
An MPN device may be suspended if errors occur during push notification delivery.
This flag is switched to true by server sent suspension events, and back to false in case of client disconnection or server sent resume events.

Lifecycle: This method can be called at any time.

See:
Returns:

true if the MPN device object is currently suspended on the server.

Type
boolean

removeListener(listener)

Removes a listener from the MpnDevice instance so that it will not receive events anymore.

Lifecycle: a listener can be removed at any time.

Parameters:
Name Type Description
listener MpnDeviceListener

The listener to be removed.