2015-05-02 01:21:25 +02:00
|
|
|
.. raw:: html
|
|
|
|
|
|
|
|
|
|
<div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/quickstart.rst">Edit me on GitHub</a></div>
|
|
|
|
|
|
2016-12-22 14:00:03 +01:00
|
|
|
==========
|
|
|
|
|
Quickstart
|
|
|
|
|
==========
|
|
|
|
|
|
|
|
|
|
Getting a demo up and running
|
|
|
|
|
=============================
|
|
|
|
|
|
2018-10-26 15:39:49 +02:00
|
|
|
Option 1: Use the content delivery network
|
|
|
|
|
------------------------------------------
|
2014-12-07 00:53:17 +01:00
|
|
|
|
2018-09-18 10:53:43 +02:00
|
|
|
Converse has a `CDN <https://en.wikipedia.org/wiki/Content_delivery_network>`_, provided by `KeyCDN <http://keycdn.com/>`_,
|
2017-09-03 22:12:17 +02:00
|
|
|
which hosts its JavaScript and CSS files.
|
2014-12-07 00:53:17 +01:00
|
|
|
|
2016-06-21 09:07:22 +02:00
|
|
|
The latest versions of these files are available at these URLs:
|
2014-12-07 00:53:17 +01:00
|
|
|
|
2016-06-21 09:07:22 +02:00
|
|
|
* https://cdn.conversejs.org/dist/converse.min.js
|
|
|
|
|
* https://cdn.conversejs.org/css/converse.min.css
|
2014-12-07 00:53:17 +01:00
|
|
|
|
2018-11-10 21:59:57 +01:00
|
|
|
If you are integrating Converse into an existing website or app, then we recommend
|
|
|
|
|
that you load a specific version of Converse. Otherwise your website or app
|
|
|
|
|
might break when a new backwards-incompatible version of Converse is released.
|
2018-09-18 10:53:43 +02:00
|
|
|
|
2018-11-10 21:59:57 +01:00
|
|
|
To load a specific version of Converse you can put the version in the URL:
|
2016-06-21 09:07:22 +02:00
|
|
|
|
2019-04-04 12:33:08 +02:00
|
|
|
* https://cdn.conversejs.org/4.2.0/dist/converse.min.js
|
|
|
|
|
* https://cdn.conversejs.org/4.2.0/css/converse.min.css
|
2014-12-07 00:53:17 +01:00
|
|
|
|
2017-04-18 19:24:49 +02:00
|
|
|
You can include these two URLs inside the *<head>* element of your website
|
|
|
|
|
via the *script* and *link* tags:
|
2016-06-21 09:07:22 +02:00
|
|
|
|
|
|
|
|
.. code-block:: html
|
2014-12-07 00:53:17 +01:00
|
|
|
|
2019-04-04 12:33:08 +02:00
|
|
|
<link rel="stylesheet" type="text/css" media="screen" href="https://cdn.conversejs.org/4.2.0/css/converse.min.css">
|
|
|
|
|
<script src="https://cdn.conversejs.org/4.2.0/dist/converse.min.js" charset="utf-8"></script>
|
2017-04-18 19:24:49 +02:00
|
|
|
|
2018-10-26 15:39:49 +02:00
|
|
|
|
|
|
|
|
Option 2: Building the files yourself
|
|
|
|
|
-------------------------------------
|
|
|
|
|
|
2018-11-10 21:59:57 +01:00
|
|
|
Instead of using the CDN, you can also create your own builds and host them yourself.
|
2018-10-26 15:39:49 +02:00
|
|
|
|
2018-11-10 21:59:57 +01:00
|
|
|
Have a look at the :ref:`creating_builds` section on how to create your own builds.
|
2018-10-26 15:39:49 +02:00
|
|
|
|
2018-11-10 21:59:57 +01:00
|
|
|
In short, you should be able to do it by running ``make dist`` inside a
|
|
|
|
|
checkout of the `Converse repo <http://github.com/conversejs/converse.js/>`_.
|
2018-10-26 15:39:49 +02:00
|
|
|
|
|
|
|
|
Besides including the ``converse.min.js`` and ``converse.min.css`` files,
|
|
|
|
|
you'll also need to make sure that the ``webfonts`` directory is available in
|
|
|
|
|
the same location as ``converse.min.css``.
|
|
|
|
|
|
|
|
|
|
|
2018-09-18 10:53:43 +02:00
|
|
|
Initializing Converse
|
|
|
|
|
---------------------
|
2014-12-07 00:53:17 +01:00
|
|
|
|
2018-11-10 21:59:57 +01:00
|
|
|
You'll need to initialize Converse with configuration settings relevant to your requirements.
|
|
|
|
|
Take a look at the :ref:`configuration-settings` section for info on all the available settings.
|
2014-12-07 00:53:17 +01:00
|
|
|
|
2017-09-03 22:12:17 +02:00
|
|
|
To quickly get started, you can put the following JavaScript code at the
|
2017-04-18 19:24:49 +02:00
|
|
|
bottom of your page (after the closing *</body>* element)::
|
2014-12-07 00:53:17 +01:00
|
|
|
|
2015-06-22 14:47:53 +02:00
|
|
|
<script>
|
2014-12-07 00:53:17 +01:00
|
|
|
converse.initialize({
|
2017-11-17 19:20:42 +01:00
|
|
|
bosh_service_url: 'https://conversejs.org/http-bind/', // Please use this connection manager only for testing purposes
|
2017-03-07 07:56:43 +01:00
|
|
|
show_controlbox_by_default: true
|
2014-12-07 00:53:17 +01:00
|
|
|
});
|
2015-06-22 14:47:53 +02:00
|
|
|
</script>
|
2014-12-07 00:53:17 +01:00
|
|
|
|
|
|
|
|
The `index.html <https://github.com/jcbrand/converse.js/blob/master/index.html>`_ file inside the
|
2018-11-10 21:59:57 +01:00
|
|
|
Converse repository serves as a nice, usable example.
|
2018-01-09 15:49:45 +01:00
|
|
|
|
|
|
|
|
Fullscreen version
|
|
|
|
|
------------------
|
|
|
|
|
|
2018-09-18 10:53:43 +02:00
|
|
|
Converse also comes in a fullscreen version.
|
|
|
|
|
A hosted version is available online at `conversejs.org/fullscreen <https://conversejs.org/fullscreen.html>`_.
|
2018-01-09 15:49:45 +01:00
|
|
|
|
|
|
|
|
Originally this version was available as a separate build file, but
|
|
|
|
|
as of version 4.0.0 and higher, the difference between the "overlay" and the
|
|
|
|
|
"fullscreen" versions of converse.js is simply a matter of configuring the
|
2018-05-24 14:37:52 +02:00
|
|
|
:ref:`view_mode`.
|
2018-01-09 15:49:45 +01:00
|
|
|
|
2018-09-18 10:53:43 +02:00
|
|
|
For example::
|
2016-12-22 14:00:03 +01:00
|
|
|
|
2018-09-18 10:53:43 +02:00
|
|
|
<script>
|
|
|
|
|
converse.initialize({
|
|
|
|
|
bosh_service_url: 'https://conversejs.org/http-bind/', // Please use this connection manager only for testing purposes
|
|
|
|
|
view_mode: 'fullscreen'
|
|
|
|
|
});
|
|
|
|
|
</script>
|
2016-12-22 14:00:03 +01:00
|
|
|
|
|
|
|
|
Where to go from here?
|
|
|
|
|
======================
|
|
|
|
|
|
2018-11-10 21:59:57 +01:00
|
|
|
Have a look at the various :ref:`features <features>` that Converse provides, for some of
|
|
|
|
|
them you might have to do more setup work, like configuring an XMPP server or
|
|
|
|
|
webserver.
|
|
|
|
|
|
2016-12-22 14:00:03 +01:00
|
|
|
You might want to implement some kind of persistent single-session solution for
|
|
|
|
|
your website, where users authenticate once in your website and are then
|
|
|
|
|
automatically logged in to the XMPP server as well. For more info on how this
|
|
|
|
|
can be achieved, read: :ref:`session-support`.
|
|
|
|
|
|
2019-02-25 14:18:05 +01:00
|
|
|
For end-to-end encryption via OMEMO, you'll need to load `libsignal-protocol.js
|
|
|
|
|
<https://github.com/signalapp/libsignal-protocol-javascript>`_ separately in
|
|
|
|
|
your page. Take a look at the section on :ref:`libsignal <dependency-libsignal>` and the
|
|
|
|
|
:ref:`security considerations around OMEMO <feature-omemo>`.
|
|
|
|
|
|
2018-09-18 10:53:43 +02:00
|
|
|
Perhaps you want to create your own custom build of Converse? Then head over
|
2018-11-10 21:59:57 +01:00
|
|
|
to the :doc:`builds` section, or more generally the :doc:`development <development>`
|
2016-12-22 14:00:03 +01:00
|
|
|
documentation.
|
2014-12-07 00:53:17 +01:00
|
|
|
|
2018-11-10 21:59:57 +01:00
|
|
|
Do you want to know how to theme Converse? Then read the :doc:`theming <theming>`
|
2016-12-22 14:00:03 +01:00
|
|
|
documentation.
|
2014-12-07 00:53:17 +01:00
|
|
|
|
