Document the prebind_url option.

docs/source/configuration.rst

@@ -284,71 +284,74 @@ Default:  ``false``
 
 See also: :ref:`session-support`
 
-Use this option when you want to attach to an existing XMPP connection that was
-already authenticated (usually on the backend before page load).
+Use this option when you want to attach to an existing XMPP
+`BOSH <https://en.wikipedia.org/wiki/BOSH>`_ session.
 
-This is useful when you don't want to render the login form on the chat control
-box with each page load.
+Usually a BOSH session is set up server-side in your web app.
 
-For prebinding to work, you must set up a pre-authenticated BOSH session,
-for which you will receive a JID (jabber ID), SID (session ID) and RID
-(Request ID).
+Attaching to an existing BOSH session that was set up server-side is useful
+when you want to maintain a persistent single session for your users instead of
+requiring them to log in manually.
 
-These values (``rid``, ``sid`` and ``jid``) need to be passed into
-``converse.initialize`` (with the exception of ``keepalive``, see below).
+When a BOSH session is initially created, you'll receive three tokens.
+A JID (jabber ID), SID (session ID) and RID (Request ID).
 
-Additionally, you also have to specify a ``bosh_service_url``.
+Converse.js needs these tokens in order to attach to that same session.
 
-Using prebind in connection with keepalive
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+There are two complementary configuration settings to ``prebind``.
+They are :ref:`keepalive` and :ref:`prebind_url`.
 
-The ``prebind`` and `keepalive`_ options can be used together.
+``keepalive`` can be used keep the session alive without having to pass in
+new tokens to ``converse.initialize`` every time you reload the page. This
+removes the need to set up a new BOSH session every time a page loads.
 
-The ``keepalive`` option caches the ``rid``, ``sid`` and ``jid`` values
-(henceforth referred to as *session tokens*) one receives from a prebinded
-BOSH session, in order to re-use them when the page reloads.
+``prebind_url`` lets you specify a URL which converse.js will call whenever a
+new BOSH session needs to be set up.
 
-However, if besides setting ``keepalive`` to ``true``, you also set ``prebind``
-to ``true``, and you pass in valid session tokens to ``converse.initialize``,
-then those passed in session tokens will be used instead of any tokens cached by
-``keepalive``.
 
-If you set ``prebind`` to ``true``  and don't pass in the session tokens to
-``converse.initialize``, then converse.js will look for tokens cached by
-``keepalive``.
+Here's an example of converse.js being initialized with these three options:
 
-If you've set ``keepalive`` and ``prebind`` to ``true``, don't pass in session
-tokens and converse.js doesn't find any cached session tokens, then
-converse.js will emit an event ``noResumeableSession`` and exit.
+.. code-block:: javascript
 
-This allows you to start a prebinded session with valid tokens, and then fall
-back to ``keepalive`` for maintaining that session across page reloads. When
-for some reason ``keepalive`` doesn't have cached session tokens anymore, you
-can listen for the ``noResumeableSession`` event and take that as a cue that
-you should again prebind in order to get valid session tokens.
+    converse.initialize({
+        bosh_service_url: 'https://bind.example.com',
+        keepalive: true,
+        prebind: true,
+        prebind_url: 'http://example.com/api/prebind',
+        allow_logout: false
+    });
 
-Here is a code example:
+.. note:: The ``prebind_url`` configuration setting is new in version 0.9 and
+    simplifies the code needed to set up and maintain prebinded sessions.
 
-.. code-block:: javascript
+    When using ``prebind_url`` and ``keepalive``, you don't need to manually pass in
+    the RID, SID and JID tokens anymore.
 
-        converse.on('noResumeableSession', function () {
-            $.getJSON('/prebind', function (data) {
-                converse.initialize({
-                    prebind: true,
-                    keepalive: true,
-                    bosh_service_url: 'https://bind.example.com',
-                    jid: data.jid,
-                    sid: data.sid,
-                    rid: data.rid
-                });
-            });
-        });
-        converse.initialize({
-            prebind: true,
-            keepalive: true,
-            bosh_service_url: 'https://bind.example.com'
-        }));
 
+.. _`prebind_url`:
+
+prebind_url
+-----------
+
+* Default:  ``null``
+* Type:  URL
+
+See also: :ref:`session-support`
+
+This setting should be used in conjunction with :ref:`prebind` and :ref:`keepalive`.
+
+It allows you to specify a URL which converse.js will call when it needs to get
+the RID and SID (Request ID and Session ID) tokens of a BOSH connection, which
+converse.js will then attach to.
+
+The server behind ``prebind_url`` should return a JSON encoded object with the
+three tokens::
+
+    {
+        "jid": "me@example.com/resource",
+        "sid": "346234623462",
+        "rid": "876987608760"
+    }
 
 providers_link
 --------------

docs/source/setup.rst

@@ -126,7 +126,7 @@ Server-side authentication (prebind)
 It's possible to enable shared sessions whereby users already
 authenticated in your website will also automatically be logged in on the XMPP server,
 
-This session can be made to persist across page loads. In other words, we want
+This session can also be made to persist across page loads. In other words, we want
 a user to automatically be logged in to chat when they log in to the website,
 and we want their chat session to persist across page loads.
 
@@ -158,47 +158,11 @@ page load). Each page load is a new request which requires a new unique RID.
 The best way to achieve this is to simply increment the RID with each page
 load.
 
-When you initialize converse.js in your browser, you need to pass it these two
-tokens. Converse.js will then use them to attach to the session you just
-created.
-
-You can embed the RID and SID tokens in your HTML markup or you can do an
-XMLHttpRequest call to your server and ask it to return them for you.
-
-Below is one example of how this could work. An Ajax call is made to the
-relative URL **/prebind** and it expects to receive JSON data back.
-
-.. code-block:: javascript
-
-    $.getJSON('/prebind', function (data) {
-        converse.initialize({
-            prebind: true,
-            bosh_service_url: data.bosh_service_url,
-            jid: data.jid,
-            sid: data.sid,
-            rid: data.rid
-        });
-    );
-
-**Here's what's happening:**
-
-The JSON data returned from the Ajax call to example.com/prebind contains the user's JID (jabber ID), RID, SID and the URL to the
-BOSH server (also called a *connection manager*).
-
-These values are then passed to converse.js's ``initialize`` method.
-
-.. note::
-   If you want to enable single session support, you need to set **prebind: true**
-   when calling **converse.initialize** (see ./index.html).
-   Additionally you need to pass in valid **jid**, **sid**, **rid** and
-   **bosh_service_url** values.
-
-   The :ref:`prebind` configuration setting can be used together with the
-   :ref:`keepalive` setting. This means you only have to prebind once for the
-   first page the user loads and not anymore for subsequent pages.
-
-   For more info, please refer to the :ref:`configuration-variables` section.
+You'll need to configure converse.js with the :ref:`prebind`, :ref:`keepalive` and 
+:ref:`prebind_url` settings.
 
+Please read the documentation on those settings for a fuller picture of what
+needs to be done.
 
 Example code for server-side prebinding
 =======================================