Document the prebind_url option.
This commit is contained in:
JC Brand
parent
9dd3440f86
commit
d40eebc41f
|
|
@ -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``.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Here is a code example:
|
||||
Here's an example of converse.js being initialized with these three options:
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
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'
|
||||
}));
|
||||
converse.initialize({
|
||||
bosh_service_url: 'https://bind.example.com',
|
||||
keepalive: true,
|
||||
prebind: true,
|
||||
prebind_url: 'http://example.com/api/prebind',
|
||||
allow_logout: false
|
||||
});
|
||||
|
||||
.. note:: The ``prebind_url`` configuration setting is new in version 0.9 and
|
||||
simplifies the code needed to set up and maintain prebinded sessions.
|
||||
|
||||
When using ``prebind_url`` and ``keepalive``, you don't need to manually pass in
|
||||
the RID, SID and JID tokens anymore.
|
||||
|
||||
|
||||
.. _`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
|
||||
--------------
|
||||
|
|
|
|||
|
|
@ -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
|
||||
=======================================
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user