doc/push.txt in rhoconnect-3.1.2 vs doc/push.txt in rhoconnect-3.2.0.beta1

- old
+ new

@@ -1,143 +1,14 @@ -Device Push +Push Synchronization === -RhoConnect has a simple ruby API for sending push notifications to a user's devices. This API can be called directly, queued as a resque job, or called remotely via the [RhoConnect REST API](/rhoconnect/rest-api). The push message can trigger the following actions in the rhodes application: alert with a message, sync one or more sources, vibrate, display a badge, play a sound file. +Use push synchronization when you want to automatically detect changes on the RhoConnect side, and you want to push those changes to your client without having to tell your client to sync. -We will now show you how to use the RhoConnect application to deliver push messages on each platform and how you can handle the push notification in your Rhodes application. +RhoConnect has a simple ruby API for sending push notifications (a ping call) to a user's devices. This API can be called directly, queued as a resque job, or called remotely via the [RhoConnect REST API](/rhoconnect/rest-api). The push message can trigger the following actions in the rhodes application: alert with a message, sync one or more sources, vibrate, display a badge, and play a sound file. -## iOS -To setup your RhoConnect application for iOS push, you will need to update `settings/settings.yml` to include the following: +The following sections show how to use the RhoConnect application to deliver push messages on each platform and how you can handle the push notification in your Rhodes application. - :::yaml - :development: - :redis: localhost:6379 - :iphonecertfile: settings/apple_push_cert.pem - :iphonepassphrase: #=> empty or put password for your certificate - :iphoneserver: gateway.sandbox.push.apple.com - :iphoneport: 2195 - :syncserver: http://localhost:9292/application/ - :licensefile: settings/license.key +You will need to perform the following tasks. -This is for running your application in development mode, for production you will need all of the iphone settings, and change the `:iphoneserver:` to: - - :::yaml - :iphoneserver: gateway.push.apple.com - -## Blackberry -To setup your RhoConnect application for BlackBerry push, you will need to update `settings/settings.yml` to include the following: - - :::yaml - :development: - :redis: localhost:6379 - :mdsserver: 192.168.1.110 - :mdsserverport: 8080 - :syncserver: http://localhost:9292/application/ - :licensefile: settings/license.key - -Replace `:mdsserver:` and `:mdsserverport:` with the hostname/IP and port of your machine (default port is 8080). - -## Android -To setup your RhoConnect application for Android push, you will need to update `settings/settings.yml` to include the following: - - :::yaml - :development: - :redis: localhost:6379 - :syncserver: http://localhost:9292/application/ - :licensefile: settings/license.key - :c2dm_username: username - :c2dm_passwd: passwd - :authtoken: authtoken - -In order to push messages to the Android device, your server needs to obtain Google's C2DM authentication token associated with the trusted google account. -For this purpose, you can specify C2DM Google account's username/password combo via the `:c2dm_username` and `:c2dm_passwd` settings. -At run-time, the system will use these credentials to obtain the C2DM token and store it in the Redis for the future use. -Once the token is expired, the system will automatically connect to the Google C2DM service to renew the token. - -Alternatively, you can use `:authtoken` setting to specify the pre-defined authentication token. This token MUST be related to the role-based google account registered for your application. See [the rhodes push instructions](/rhodes/device-caps#push-notifications) for more details. To retrieve this token, use sample script [c2dm.rb](http://github.com/rhomobile/rhodes/blob/master/bin/c2dm.rb). Uncomment last two lines and put your google account specific data, then run it. It will print token to stdout. -However, this approach will not allow the server to connect to the C2DM service and renew the token once it is expired. - -For those who interested in what this token means, the description is [here](http://code.google.com/apis/accounts/docs/AuthForInstalledApps.html). - -Now start up your RhoConnect application and setup [push notifications](/rhodes/device-caps#push-notifications) in your Rhodes application. - -## Testing Push in the Web Console -The [RhoConnect Web Console](/rhoconnect/web-console) includes a utility for testing push to make sure everything is wired up correctly. - -First, make sure you've logged in and performed a sync on the device/simulator you are going to test. - -Next, once you've logged into the web console, navigate to the user's page you used to login in the Rhodes application. For example, if you logged in as user 't', the url would be: - - http://localhost:9292/console/user?user_id=t - -You should see a registered device for this user, for example: "c92e36874bc74f39a8fbd7c1a86f9e0e". Click on the link for this device and you will see the device attributes: - - device_type: APPLE - device_pin: 10fd92abfa8ee48155d9af6e7329086322b323fd0d18fdbd19e92d03c0fef7c8 - device_port: 100 - user_id: t - app_id: application - -**NOTE: If you don't see all of these attributes, then something is incorrect in your Rhodes application settings. Please verify you followed the [Rhodes application push setup](/rhodes/device-caps#push-notifications).** - -Now that the device is registered, go back to the user page and click 'Ping User'. - -Here you can specify an alert message, sources array to sync, badge value (iOS only), sound file to play, and duration to vibrate. - -Enter in some values or try the defaults, you should see a push message on the device when you click "Ping!". - -By default, the sources list will be a comma-separated list of your RhoConnect application's sources. This sources list will be sent in the push message to trigger a sync. You can specify one or more sources, or 'all' to trigger a sync of all sources. - -## Push API -The RhoConnect push API consists of executing a ping call. There are three ways to execute a ping call: use RhoConnect API to remotely call the ping, perform the ping job directly in a blocking ruby call, enqueue a resque job to ping asynchronously. - -### RhoConnect API Ping Method -You can trigger a push remotely using the [RhoConnect API Ping method](/rhoconnect/rest-api). This is useful if you want to fully control the push process from a remote server (instead of your source adapter). - -### Direct Push -To perform a ping directly, you can call the following: - - :::ruby - PingJob.perform( - 'user_id' => current_user.login, - 'sources' => ['Product','Customer'], - 'message' => 'hello world', - 'vibrate' => 2000, - 'sound' => 'hello.mp3' - ) - -### Asynchronous Push -To queue a ping that is executed asynchronously in a job, you can call the following: - - :::ruby - Resque.enqueue( - PingJob, - 'user_id' => current_user.login, - 'sources' => ['Product','Customer'], - 'message' => 'hello world', - 'vibrate' => 2000, - 'sound' => 'hello.mp3' - ) - -**Note: For this job to execute, you will need to have a resque worker running. See running [async jobs](/rhoconnect/async-jobs) for more information.** - -### Example -Let's say we want to execute a ping for the `current_user` at the end of our source adapter query: - - :::ruby - def query(params=nil) - parsed = JSON.parse(RestClient.get("#{@base}.json").body) - - @result = {} - parsed.each do |item| - @result[item["product"]["id"].to_s] = item["product"] - end if parsed - PingJob.perform( - 'user_id' => current_user.login, - 'sources' => ['Product'], - 'message' => "There are new products!", - 'vibrate' => 2000 - ) - end - -### Push Notifications in Rhodes -Now that you can send push messages in your RhoConnect application, you can now handle the [push notification](/rhodes/device-caps#push-notifications) in your Rhodes application. \ No newline at end of file +* [Set up the configuration settings in the RhoConnect application](/rhoconnect/push-server-setup) for your mobile client operating system. +* [Execute a ping call](/rhoconnect/push-backend-setup) from your RhoConnect source adapter or from your backend application that uses a RhoConnect plugin. +* [Set up push notification support](/rhoconnect/push-client-setup) -- receiving push notifications from the RhoConnect server/backend -- on your Android, Blackberry, or iPhone client application.