Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

Push

Methods 11  
Properties 4
Examples 1

The Push API provides access to Push messaging functionality. Use this API to give your application the ability to receive server initiated messages.

Enabling the API

In order to use this API you must include the following extension in your build.yml:

For APNS or GCM:

capabilities: ["push"]

For RhoConnect Push Service:

extensions: ["rhoconnect-push", "rhoconnect-client"]
For Win32(XPE) MSMQ(Microsoft Message Queue) and .Net Framework 3.5 must be installed on device to get it work.

JavaScript Usage

Be sure to review the JavaScript API Usage guide for important information about using this API in JavaScript.

Ruby Usage

Be sure to review the Ruby API Usage guide for important information about using this API in Ruby.

Methods

enumerate(CallBackHandler callback)

getAllProperties(CallBackHandler callback)

This method will return all of object/value pairs for the propertyNames of the API class.

Parameters

  • callback : CallBackHandler Optional

Async Callback Returning Parameters: HASH

    • : STRING

Synchronous Return:

  • HASH :

    Map of all available properties

    : this method also supports async callbacks - check the Callback tab for callback return parameters.
    • : STRING

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.getAllProperties(CallBackHandler callback)
  • Default Instance: This method can be accessed via the default instance object of this class.
    • JavaScript: Rho.Push.getAllProperties(CallBackHandler callback)
    • Ruby: Rho::Push.getAllProperties(CallBackHandler callback)

getDefault()

This method will return an object that represents the default instance of the API Class. For example Camera.getDefault will return a Camera object that represents the default camera.

Synchronous Return:

  • SELF_INSTANCE :

    Default object of Module.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.Push.getDefault()
    • Ruby: Rho::Push.getDefault()

getDeviceId(CallBackHandler callback)

Returns push token used to identify particular device.

Parameters

  • callback : CallBackHandler Optional

Async Callback Returning Parameters: STRING

    Synchronous Return:

    • STRING : this method also supports async callbacks - check the Callback tab for callback return parameters.

    Method Access:

    • Instance Method: This method can be accessed via an instance object of this class:
      • myObject.getDeviceId(CallBackHandler callback)
    • Default Instance: This method can be accessed via the default instance object of this class.
      • JavaScript: Rho.Push.getDeviceId(CallBackHandler callback)
      • Ruby: Rho::Push.getDeviceId(CallBackHandler callback)

    getProperties(ARRAY arrayofNames, CallBackHandler callback)

    This method will return a set of object/value pairs for the list of the propertyName that is passed in. The propertyNames must be a valid property of the API class.

    Parameters

    • arrayofNames : ARRAY

      List of properties I want to know about

      • Object : STRING

    • callback : CallBackHandler Optional

    Async Callback Returning Parameters: HASH

      • : STRING

    Synchronous Return:

    • HASH :

      Map of properties I want to know about

      : this method also supports async callbacks - check the Callback tab for callback return parameters.
      • : STRING

    Method Access:

    • Instance Method: This method can be accessed via an instance object of this class:
      • myObject.getProperties(ARRAY arrayofNames, CallBackHandler callback)
    • Default Instance: This method can be accessed via the default instance object of this class.
      • JavaScript: Rho.Push.getProperties(ARRAY arrayofNames, CallBackHandler callback)
      • Ruby: Rho::Push.getProperties(ARRAY arrayofNames, CallBackHandler callback)

    getProperty(STRING propertyName, CallBackHandler callback)

    This method will return the value of the propertyName that is passed in. The propertyName must be a valid property of the API class.

    Parameters

    • propertyName : STRING

      The property to return info about.

    • callback : CallBackHandler Optional

    Async Callback Returning Parameters: STRING

      Synchronous Return:

      • STRING :

        The property to return info about.

        : this method also supports async callbacks - check the Callback tab for callback return parameters.

      Method Access:

      • Instance Method: This method can be accessed via an instance object of this class:
        • myObject.getProperty(STRING propertyName, CallBackHandler callback)
      • Default Instance: This method can be accessed via the default instance object of this class.
        • JavaScript: Rho.Push.getProperty(STRING propertyName, CallBackHandler callback)
        • Ruby: Rho::Push.getProperty(STRING propertyName, CallBackHandler callback)

      setDefault(SELF_INSTANCE: Rho::Push defaultInstance)

      This method allows you to set the attributes of the default object instance by passing in an object of the same class.

      Parameters

      • defaultInstance : SELF_INSTANCE: Rho::Push

        An instance object that is of the same class.

      Synchronous Return:

      • Void

      Method Access:

      • Class Method: This method can only be accessed via the API class object.
        • JavaScript: Rho.Push.setDefault(SELF_INSTANCE: Rho::Push defaultInstance)
        • Ruby: Rho::Push.setDefault(SELF_INSTANCE: Rho::Push defaultInstance)

      setProperties(HASH propertyMap)

      This method will set the values of a list of properties for the API class. The propertyName must be a valid property for the class and must also not be read only.

      Parameters

      • propertyMap : HASH

        Map of properties I want to set

        • Object : STRING

      Synchronous Return:

      • Void

      Method Access:

      • Instance Method: This method can be accessed via an instance object of this class:
        • myObject.setProperties(HASH propertyMap)
      • Default Instance: This method can be accessed via the default instance object of this class.
        • JavaScript: Rho.Push.setProperties(HASH propertyMap)
        • Ruby: Rho::Push.setProperties(HASH propertyMap)

      setProperty(STRING propertyName, STRING propertyValue)

      This method will set the value of a property for the API class. The propertyName must be a valid property for the class and must also not be read only.

      Parameters

      • propertyName : STRING

        The one property name that I want to set

      • propertyValue : STRING

        The one property value that I want to set

      Synchronous Return:

      • Void

      Method Access:

      • Instance Method: This method can be accessed via an instance object of this class:
        • myObject.setProperty(STRING propertyName, STRING propertyValue)
      • Default Instance: This method can be accessed via the default instance object of this class.
        • JavaScript: Rho.Push.setProperty(STRING propertyName, STRING propertyValue)
        • Ruby: Rho::Push.setProperty(STRING propertyName, STRING propertyValue)

      startNotifications(CallBackHandler callback)

      Start listening for push messages, errors or other push related events.

      Parameters

      • callback : CallBackHandler Mandatory

      Async Callback Returning Parameters: HASH

        • doSync : STRING

          List of sources to sync separated by comma or ‘all’.

        • alertText : STRING

          Alert message to show to user.

        • vibrateDuration : INTEGER

          Vibrate duration in milliseconds.

        • alertSound : STRING

          Path to sound file to play when push message is received.

      Synchronous Return:

      • Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

      Method Access:

      • Instance Method: This method can be accessed via an instance object of this class:
        • myObject.startNotifications(CallBackHandler callback)
      • Default Instance: This method can be accessed via the default instance object of this class.
        • JavaScript: Rho.Push.startNotifications(CallBackHandler callback)
        • Ruby: Rho::Push.startNotifications(CallBackHandler callback)

      stopNotifications()

      Stop listening push events.

      Synchronous Return:

      • Void

      Method Access:

      • Instance Method: This method can be accessed via an instance object of this class:
        • myObject.stopNotifications()
      • Default Instance: This method can be accessed via the default instance object of this class.
        • JavaScript: Rho.Push.stopNotifications()
        • Ruby: Rho::Push.stopNotifications()

      Properties

      pushAppName : STRING Read Only

      Application name used by RhoConnect Push server to identify application.

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.pushAppName
      • Default Instance: This property can be accessed via the default instance object of this class.
        • JavaScript: Rho.Push.pushAppName
        • Ruby: Rho::Push.pushAppName

      pushServer : STRING Read Only

      URL of RhoConnect Push server.

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.pushServer
      • Default Instance: This property can be accessed via the default instance object of this class.
        • JavaScript: Rho.Push.pushServer
        • Ruby: Rho::Push.pushServer

      type : STRING Read Only

      Push engine type.

      Possible Values (STRING):

      Constant: Rho.Push.PUSH_TYPE_RHOCONNECT (For Ruby use "::" instead of ".")
      String: rhoconnect-push

      RhoConnect push engine.

      Constant: Rho.Push.PUSH_TYPE_NATIVE (For Ruby use "::" instead of ".")
      String: native-push

      Native push engine (like GCM on Android).

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.type
      • Default Instance: This property can be accessed via the default instance object of this class.
        • JavaScript: Rho.Push.type
        • Ruby: Rho::Push.type

      userNotifyMode : STRING

      Deprecated

      UI notification mode. Use Rho.Notification instead.

      Default: backgroundNotifications

      Possible Values (STRING):

      Constant: Rho.Push.PUSH_NOTIFY_NONE (For Ruby use "::" instead of ".")
      String: none

      Do not notify user about received push messages.

      Constant: Rho.Push.PUSH_NOTIFY_ALERTS (For Ruby use "::" instead of ".")
      String: alert

      Notify user with alerts inside of application UI only.

      Constant: Rho.Push.PUSH_NOTIFY_NOTIFICATIONS (For Ruby use "::" instead of ".")
      String: notification

      Notify user using notification bar.

      Constant: Rho.Push.PUSH_NOTIFY_NOTIFICATIONS_AND_ALERTS (For Ruby use "::" instead of ".")
      String: backgroundNotifications

      Notify user using notification bar if in background and with alerts in foreground.

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.userNotifyMode
      • Default Instance: This property can be accessed via the default instance object of this class.
        • Ruby: Rho::Push.userNotifyMode

      Examples

      Handle push message

      Start Push Notifications service and define alert popup window in push callback method.

      function setupPush() {
  // Start listening for push messages. Parameter is an url to push_callback method
  Rho.Push.startNotifications(pushCallback);
}

function pushCallback(params) {
  // Show 'alert' popup window with push message text
  var propertyMap = {message: params["alert"], buttons: [{id: 'OK', title: 'OK'}]};
  Rho.Notification.showPopup(propertyMap);
}
                                
                            
      def setup_push
  # Start listening for push messages. Parameter is an url to push_callback method
  Rho::Push.startNotifications(url_for(:action=>:push_callback))
end


def push_callback
  # Show 'alert' popup window with push message text
  Rho::Notification.showPopup({'message' => @params['alert'], 'buttons' =>['OK']})
end