Class: MojioPushSDK

Defined in:	MojioPushSDK.coffee
Inherits:	MojioRestSDK

Overview

The Push segment of the Mojio SDK. The Push segement of the SDK provides a mechanism for applications to subscribe to changes occurring on primary API resources of Vehicles, Users, Mojios, Trips, Groups, and Apps.

Mojio maintains a separate "Push" style API where applications can subscribe to changes on resources and receive those changes across multiple transports. Current transports include: SIGNALR, HTTPS POST, and MQTT.

Subscriptions are instantiated by posting "Observers" to the Push API's REST interface. Observers define what, when and how data is channeled to the application from the server.

What is defined by specification of the resource type and id. The "What" delivered can be narrowed down to a specific set of fields through a filter specification (basically a list of the names of the fields).

The "When" is defined by optional conditions, debounce, throttle, and timings.

The "How" is defined by a transport specification that has the connection details to a method, server or hub, depending on the transport type. For SignalR, Mojio provides the hub of communication, for other protocols like MQTT or Http Post, the application writer is responsible for the communication infrastructure.

The inheritance path is: MojioPushSDK->MojioRestSDK->MojioAuthSDK->MojioModelSDK

Examples:

mojioSdk = new MojioSDK({sdk: MojioPushSDK}) # instantiate the mojioSDK to all available API calls.

Instance Method Summary

# (object) observe(key) Observe a Vehicle, Mojio, or User object in the Mojio API.
# (object) fields(fields) Limit the fields returned to a specific set of properties.
# (object) where(clause) The condition that must be satisfied for the observer to fire.
# (object) transport(transport) Specify how data is sent.
# (object) throttle(throttle) Limit how much data is sent.
# (object) debounce(debounce) Debounce the condtion for the obserer.
# (object) timing(state) Set the timing of the observer.

Inherited Method Summary

Methods inherited from MojioRestSDK

#put #post #delete #get #query #select #filter #top #skip #orderby #field #add #set #remove #authorize #unauthorize #token #parse #refresh #login #consent #loginAndConsent #prompt #scope #username #email #password #credentials #with #getToken #setup #setCriteria #users #vehicles #mojios #trips #apps #groups #permissions #images #tags #details #histories #states #locations #mock

Instance Method Details

# (object) observe(key)

Observe a Vehicle, Mojio, or User object in the Mojio API.

Observers on particular objects are setup by chaining them with calls to the RestSDK's entity methods: Vehicle, Vehicles, User, Users, Mojio, or Mojios. The observer will observe the entities specified in those calls.

Examples:

observe all vehicles for this user, assumes SignalR transport and the callback given is the handler.

sdk.observe("MyUniqueKeyName")
.vehicles() # observe all vehicles for the account of the authorized token
.callback((error, result) ->
     if (typeof result is 'boolean') # this is a callback via nodejs return
         console.log("Vehicle Observer created with signalR transport and this callback as the handler")
     else if (result instanceof 'object') # we are in a callback via signalR
         ... # receive the changes to the objects.
 )

sdk.observe("MyUniqueKeyName")
 .vehicle("[some id]") # observe all vehicles for a specific vehicle
 .callback((error, result) ->
    console.log("success in creating an observer") if (result?)
 )

Parameters:

key ( string ) — This parameter is a name that can be used to find the observer later, or to modify it.
callback ( function ) — Optional parameter to initiate the fluent chain if needed.

Returns:

( object ) — this

# (object) fields(fields)

Limit the fields returned to a specific set of properties.

Fields are given as an array of strings that are the names of the properties of the entity returned.

Examples:

sdk.observe({key: "MyUniqueKeyName"})
.vehicles()
.fields(
        "VIN",
        "AccidentState",
        "Battery",
        "Location",
        "Heading",
        "Altitude",
        "Speed",
        "Accelerometer",
        "LastContactTime",
        "GatewayTimeStamp",
        "FuelLevel"
    ])

Parameters:

fields ( array of strings ) — The fields of an object to deliver in the results of a query.
callback ( function ) — Optional parameter to initiate the fluent chain if needed.

Returns:

( object ) — this

# (object) where(clause)

The condition that must be satisfied for the observer to fire.

When the condition fires, the observer sends data. For instance, if the observer is setup with the condition send data when MilStatus is true, it will fire when the MilStatus field on the vehicle changes from false to true. See "timing" below to change the time when the data is sent.

Examples:

Send only when the battery level transitions is in this condition

sdk.observe({key: "MyUniqueKeyName"})
.vehicles()
.where("Battery > min or Battery < max")

Parameters:

clause ( string ) — A where clause for queries.
callback ( function ) — Optional parameter to initiate the fluent chain if needed.

Returns:

( object ) — this

# (object) transport(transport)

Specify how data is sent.

Specify the transport used to send data. Possible transports are numerous and include: SignalR, Http Post, MQTT, etc.

Examples:

Use SignalR as a transport with the given callback:

# coffeescript
sdk.observe({key: "MyUniqueKeyName"})
.vehicles()
.transport({
    Type: "SignalR",
    Callback: (error, result) -> # function to call when the condition fires.
        console.log("Error:"+ JSON.stringify(error)) if error
       console.log(JSON.stringify(result)) if result
})

Parameters:

transport ( object ) — An object that contains the information about how the entity will be delivered, eg http post, signalr etc.
callback ( function ) — Optional parameter to initiate the fluent chain if needed.

Returns:

( object ) — this

# (object) throttle(throttle)

Limit how much data is sent.

Throttle back the data sent by telling the push API to send data at a limited rate. The rate is limited by specifying a window of time to refrain from sending data after the observer has fired.

Examples:

Don't send data faster than 10 seconds, in other words, once data is sent, don't send anything again until 10 seconds have past.

throttle("10 seconds")

Parameters:

throttle ( object ) — An object that defines how often to send data.
callback ( function ) — Optional parameter to initiate the fluent chain if needed.

Returns:

( object ) — this

# (object) debounce(debounce)

Debounce the condtion for the obserer.

Prevent false positives by making sure that the condition has fired by specifying either the number of readings required for a condition to be considered true, or specifying the amount of time the condition must be true in order to be sure of the change.

Examples:

Set the observer so that it detects a transition if 6 true data points show the change.

debounce({ DataPoints: 6 })

Set the observer so that it detects a transition if the change has been active for 15 seconds.

debounce({ TimeWindow: "00:00:15" }) # time window is given in a csharp timespan format

Set the observer so that it detects a transition there are 6 true datapoints within 15 seconds.

debounce({ DataPoints: 6, TimeWindow: "00:00:15" }) # time window is given in a csharp timespan format

Parameters:

debounce ( object ) — An object that defines how to smooth out detection of transitions of state.
callback ( function ) — Optional parameter to initiate the fluent chain if needed.

Returns:

( object ) — this

# (object) timing(state)

Set the timing of the observer. Timing refers to when to send data in relation to the given condition. Possible timings are: leading, trailing, high, low, edge, and continuous.

leading- deliver data when the condition transitions from false to true.

trailing- deliver the data when the condition transitions from true to false

high- deliver the data when the condition is true and information comes from the vehicle (subject to throttle)

low- deliver the data when the condition is false and information comes from the vehicle (subject to throttle)

edge- both leading and trailing edges

continuous- both high and low

Examples:

Set the observer so that it detects a transition if 6 data points show the change.

timing("high")

Set the observer so that it detects a transition if the change has been active for 15 seconds.

timing("leading")

Parameters:

states ( string ) — An object that defines how to smooth out detection of transitions of state.
callback ( function ) — Optional parameter to initiate the fluent chain if needed.

Returns:

( object ) — this