Clarify how one should use prebind and keepalive together.
This commit is contained in:
parent
64847bcb96
commit
5bad6b02b6
11
converse.js
11
converse.js
@ -4559,11 +4559,14 @@
|
|||||||
this.connection = new Strophe.Connection(this.bosh_service_url);
|
this.connection = new Strophe.Connection(this.bosh_service_url);
|
||||||
|
|
||||||
if (this.prebind) {
|
if (this.prebind) {
|
||||||
if ((!this.jid) || (!this.sid) || (!this.rid) || (!this.bosh_service_url)) {
|
if (this.jid && this.sid && this.rid) {
|
||||||
throw('If you set prebind=true, you MUST supply JID, RID and SID values');
|
|
||||||
}
|
|
||||||
this.connection.attach(this.jid, this.sid, this.rid, this.onConnect);
|
this.connection.attach(this.jid, this.sid, this.rid, this.onConnect);
|
||||||
}
|
}
|
||||||
|
if (!this.keepalive) {
|
||||||
|
throw("If you use prebind and don't use keepalive, "+
|
||||||
|
"then you MUST supply JID, RID and SID values");
|
||||||
|
}
|
||||||
|
}
|
||||||
if (this.keepalive) {
|
if (this.keepalive) {
|
||||||
rid = this.session.get('rid');
|
rid = this.session.get('rid');
|
||||||
sid = this.session.get('sid');
|
sid = this.session.get('sid');
|
||||||
@ -4573,7 +4576,7 @@
|
|||||||
rid += 1;
|
rid += 1;
|
||||||
this.session.save({rid: rid}); // The RID needs to be increased with each request.
|
this.session.save({rid: rid}); // The RID needs to be increased with each request.
|
||||||
this.connection.attach(jid, sid, rid, this.onConnect);
|
this.connection.attach(jid, sid, rid, this.onConnect);
|
||||||
} else {
|
} else if (prebind) {
|
||||||
delete this.connection;
|
delete this.connection;
|
||||||
this.emit('noResumeableSession');
|
this.emit('noResumeableSession');
|
||||||
}
|
}
|
||||||
|
@ -4,7 +4,7 @@ Changelog
|
|||||||
0.8.4 (Unreleased)
|
0.8.4 (Unreleased)
|
||||||
------------------
|
------------------
|
||||||
|
|
||||||
* Bugfix. Error when trying to use prebind and keepalive together. [jcbrand]
|
* Bugfix. Error when trying to use prebind and keepalive together. [heban and jcbrand]
|
||||||
* Bugfix. Cannot read property "top" of undefined. [jcbrand]
|
* Bugfix. Cannot read property "top" of undefined. [jcbrand]
|
||||||
* Add new event, noResumeableSession, for when keepalive=true and there aren't
|
* Add new event, noResumeableSession, for when keepalive=true and there aren't
|
||||||
any prebind session tokens. [jcbrand]
|
any prebind session tokens. [jcbrand]
|
||||||
|
@ -1033,8 +1033,10 @@ Default: ``true``
|
|||||||
Determines whether Converse.js will maintain the chat session across page
|
Determines whether Converse.js will maintain the chat session across page
|
||||||
loads.
|
loads.
|
||||||
|
|
||||||
*Please be aware*: This is a new still relatively experimental feature and there might be some
|
See also:
|
||||||
unhandled edge-cases.
|
|
||||||
|
* `Prebinding and Single Session Support`_
|
||||||
|
* `Using prebind in connection with keepalive`_
|
||||||
|
|
||||||
message_carbons
|
message_carbons
|
||||||
---------------
|
---------------
|
||||||
@ -1131,19 +1133,71 @@ prebind
|
|||||||
|
|
||||||
Default: ``false``
|
Default: ``false``
|
||||||
|
|
||||||
|
See also: `Prebinding and Single Session Support`_
|
||||||
|
|
||||||
Use this option when you want to attach to an existing XMPP connection that was
|
Use this option when you want to attach to an existing XMPP connection that was
|
||||||
already authenticated (usually on the backend before page load).
|
already authenticated (usually on the backend before page load).
|
||||||
|
|
||||||
This is useful when you don't want to render the login form on the chat control
|
This is useful when you don't want to render the login form on the chat control
|
||||||
box with each page load.
|
box with each page load.
|
||||||
|
|
||||||
For prebinding to work, your backend server must authenticate for you, and
|
For prebinding to work, you must set up a pre-authenticated BOSH session,
|
||||||
then return a JID (jabber ID), SID (session ID) and RID (Request ID).
|
for which you will receive a JID (jabber ID), SID (session ID) and RID
|
||||||
|
(Request ID).
|
||||||
|
|
||||||
If you set ``prebind`` to ``true``, you have to make sure to also pass in these
|
These values (``rid``, ``sid`` and ``jid``) need to be passed into
|
||||||
values as ``jid``, ``sid``, ``rid``.
|
``converse.initialize`` (with the exception of ``keepalive``, see below).
|
||||||
|
|
||||||
|
Additionally, you also have to specify a ``bosh_service_url``.
|
||||||
|
|
||||||
|
Using prebind in connection with keepalive
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The ``prebind`` and `keepalive`_ options can be used together.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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::
|
||||||
|
|
||||||
|
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'
|
||||||
|
}));
|
||||||
|
|
||||||
Additionally, you have to specify ``bosh_service_url``.
|
|
||||||
|
|
||||||
roster_groups
|
roster_groups
|
||||||
-------------
|
-------------
|
||||||
|
Loading…
Reference in New Issue
Block a user