The presence plugin is a service that provides simple presence information over HTTP. It can be used to display an online status icon for a user or component on a web page or to poll for presence information from a web service.
Copy presence.jar into the plugins directory of your Openfire installation. The plugin will then be automatically deployed. To upgrade to a new version, copy the new presence.jar file over the existing file.
The following parameters can be passed into the request:
| Name | Description | |
|---|---|---|
| jid | Required | The bare JID (address) of the user to get presence information for (e.g. "jsmith@example.com"). The address must be on the same server that the presence service is deployed on. |
| req_jid | Optional | The bare JID (address) of the user requesting presence information. This parameter may be required in order to have permission to get presence information. For example, the presence service can be configured to only allow presence requests from users that have a presence subscription to the requested jid. |
| type | Optional | The type of response to return. Valid values are image, text or xml. If this parameter is not specified, the default value is image, which will display an image representing the user's presence. If xml is specified, an XML representation of the user's presence will be returned. If text is specified, the status text of the user's presence will be returned. |
| images | Optional | The presence service includes a default set of images that will be returned for a user's presence. You can specify a custom set of images using this parameter. The value should be the URL to the images and should include an --IMAGE-- token. For example: "http://www.example.com/images/--IMAGE--.gif". The token will be dynamically replaced with one of the following values depending on the presence status: available, chat, away, xa, dnd, offline, or forbidden. If this option is used, the presence service will respond with an http redirect pointing to the supplied image url. |
| [image_type] | Optional | Instead of specifying a single location for all custom presence images, you can override each image location directly. The parameter name should be one of the following values: available, chat, away, xa, dnd, offline, or forbidden. The parameter value should be the full URL of the image, such as "http://www.example.com/images/dnd.png". These parameters can be used in combination with the "images" parameter to specify a base location for custom images but then to override specific images with different locations. |
Sample HTML
The following example is the simplest form of calling the service to display default presence images. The server name and user must be customized for your deployment:
This example requests a user's presence by the user "jsmith" and specifies custom images that should be used to display the user's presence:
This example requests the presence of a user in XML format:
This example requests the status text of the presence of a user in text format:
Working With Firewalls
Because the presence plugin runs within the Openfire admin console web container, users behind firewalls may have problems seeing the presence icons. For example, if the Openfire admin console runs on the default port of 9090 and a user is only allowed to receive HTTP traffic on port 80, then a web request like the following won't work:
One solution for Apache users is to use mod_rewrite, mod_proxy and mod_proxy_http to serve traffic for the plugin on port 80. Sample Apache configuration entries for performing this mapping are below. Essentially, we make Apache intercept all requests for the presence plugin on port 80 and then proxy a real connection to the HTTP server on port 9090.
1 |
<virtualhost *:80>
servername example.com
....
ProxyVia On
RewriteEngine On
RewriteCond %{REQUEST_URI} ^/plugins/presence/status
RewriteRule ^/(.*) http://example.com:9090/$1 [P]
</virtualhost>
|