ejabberd-contrib/mod_webpresence

mod_webpresence - Presence on the Web

• Requires: ejabberd 19.08 or higher
• Authors: Igor Goryachev, Badlop, runcom
• http://www.ejabberd.im/mod_webpresence

Description

This module allows any local user of the ejabberd server to publish his presence information in the web. This module is the succesor of Igor Goryachev's mod_presence.

Allowed output methods are

• Icons (various themes available)
• Status text
• Raw XML
• Avatar, stored in the user's vCard

No web server, database, additional libraries or programs are required.

Configuration

• host

  Define the hostname of the service. You can use the keyword @HOST@. Default value: "webpresence.@HOST@"

• access

  Specify who can register in the webpresence service. Don't bother to specify all because this module can only show presence of local users. Default value: local

• pixmaps_path

  Take special care with commas and dots: if this module does not seem to work correctly, the problem may be that the configuration file has syntax errors. Remember to put the correct path to the pixmaps directory, and make sure the user than runs ejabberd has read access to that directory. Default value: "./pixmaps"

• baseurl

  This informational option is used only when sending a message to the user and when building the JavaScript code. It is the base part of the URL of the webpresence HTTP content. You can use the keyword @HOST@. If the option is not specified, it takes as default value: http://host:52080/presence/

Example Configuration

listen:
  -
    port: 5280
    module: ejabberd_http
    request_handlers:
      "/presence": mod_webpresence

modules:
  mod_webpresence:
    pixmaps_path: "/path/to/pixmaps"

If problems appear, remember to always look first the ejabberd log files ejabberd.log and sasl.log since they may provide some valuable information.

Automatic Enable

If you want certain Jabber accounts to be automatically accepted, without requiring the user to register in the service, you can user ACL+ACCESS. The ACCESSNAME webpresence_auto is available for that purpose.

In that case, all the output methods are enabled, the icon theme is jsf-jabber-text and RandomID is disabled.

The default behaviour is to not have automatic webpresence:

access:
  webpresence_auto:
    all: deny

For example, if you want all the local users to be automatically enabled in the service:

access:
  webpresence_auto:
    local: allow

Note that this ACCESS rule is only checked if the user is not registered. So, if the user registers and disables all output methods, his registration prevails over your setup. If you want to ensure the users do not register and disable output methods, you can use the Access configurable parameter.

Example Configuration

Example 1

listen:
  -
    port: 5280
    module: ejabberd_http
    request_handlers:
      "/presence": mod_webpresence

modules:
  mod_webpresence:
    pixmaps_path: "/path/to/pixmaps"

Example 2

listen:
  -
    port: 80
    module: ejabberd_http
    request_handlers:
      "/status": mod_webpresence

modules:
  mod_webpresence:
    host: "webstatus.@HOST@"
    access: local
    pixmaps_path: "/path/to/pixmaps"
    baseurl: "http://www.example.org/status/"

Usage

The web-presence feature by default is switched off for every user. If user wants to use it, he should register on service webpresence.example.org, which is accessible from Service Discovery. There are several switches for web-presence, but right now are all enabled and can't be disabled at all:

• Jabber ID: publish the presence in URIs that use the user's Jabber ID.
• Random ID: publish the presence in URIs that use a Random ID.
• XML: allow XML output.
• Icon: allow icon output.
• Avatar: allow Avatar output.

Login to an account on your ejabberd server using a powerful Jabber client. Open the Service Discovery on your Jabber client, and you should see a new service called webpresence.example.org. Try to register on it. A formulary appears allowing the user to allow image publishing, and XML publishing.

Once you enabled some of those options, on a web browser open the corresponding URI:

• for XML output: http://example.org:5280/presence/jid/<user>/<server>/xml/
• for image output: http://example.org:5280/presence/jid/<user>/<server>/image/
• for image output with theme: http://example.org:5280/presence/jid/<user>/<server>/image/theme/<theme>/
• for avatar output: http://example.org:5280/presence/jid/<user>/<server>/avatar/

If you want to show the image or text outputs of a specific resource, add /res/<resource> to the URI:

http://example.org:5280/presence/jid/<user>/<server>/text/res/<resource>
http://example.org:5280/presence/jid/<user>/<server>/image/res/<resource>
http://example.org:5280/presence/jid/<user>/<server>/image/theme/<theme>/res/<resource>

For output types image and avatar, you can append any string to a valid URI. For example, you can use this URI:

http://example.org:5280/presence/jid/<user>/<server>/image/theme/<theme>/myimage.jpeg

The response is exactly the same than the regular image/theme/<theme>/

If you don't want to reveal your Jabber ID, you can enable Random ID URI. After the registration the user gets a message with his a pseudo-random ID. The URI can be formed this way:

http://example.org:5280/presence/rid/<rid>/image/

If the user forgets his Random ID, he can get another message by just registering again, there is no need to change the values. If the user wants to get a new Random ID, he must disable Random ID in the registration form, and later enable Random ID again. A new Random ID will be generated for him.

Example PHP Code

This PHP script generates HTML code. Thanks to Tobias Markmann and NoAlWin.

It assumes that the URI of the presence is:

http://example.org:5280/presence/jid/tom/example.org

<?php
	$doc = new DOMDocument();
	$doc->load('http://example.org:5280/presence/jid/tom/example.org/xml');
	$presences = $doc->getElementsByTagName("presence");
	foreach ($presences as $presence) {
		echo "<p>";
		echo "<img src='http://example.org:5280/presence/jid/tom/example.org/avatar' style='display: block; margin-right: 10px;float: left;'/>";
		echo "<a href='xmpp:".$presence->getAttribute('user').'@'.$presence->getAttribute('server')."'>";
		echo "Tobias Markmann</a><br />";
		$resources = $presence->getElementsByTagName("resource");
		if($resources->length == 0){
			echo 'Unavailable';
		}else{
			foreach ($resources as $resource) {
				echo "<a href='xmpp:".$presence->getAttribute('user').'@'.$presence->getAttribute('server').'/'.$resource->getAttribute('name')."'>".$resource->getAttribute('name')."</a> &gt; ";
				switch($resource->getAttribute('show')){
					case 'chat':	echo 'Free for chat'; break;
					case 'xa':	echo 'Extended away'; break;
					case 'dnd':	echo 'Do not disturb'; break;
					default:	echo ucfirst($resource->getAttribute('show'));
				}
				if($resource->nodeValue){
					echo ": ".$resource->nodeValue;
				}
				echo "<br />";
			}
		}
		echo "</p>";
	}
?>

JavaScript Callback

The JavaScript output supports cross-site AJAX calls.

Basically, it allows to tack on a callback parameter to presence requests like so:

http://example.org:5280/presence/jid/<user>/<server>/js?cb=doStuff

Which then gets fed back in the result as:

var jabber_resources = [...]; doStuff();

The motivation for this is to work around browser restrictions in cross-site scripting. You can use it by adding a new <script/> node to the DOM at runtime, with the presence URL as its source. This will cause doStuff() to be called when the presence information has loaded. The end result is you can display real-time presence updates on a different domain than your jabber server.