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
=============================
2020-09-18 11:19:44 +02:00
You can try out the latest version of Converse at `conversejs.org <https://conversejs.org> `_
2019-05-28 17:12:50 +02:00
for the overlayed version and `conversejs.org/fullscreen.html <https://conversejs.org/fullscreen.html> `_
for the full page version.
2020-09-18 11:19:44 +02:00
If you want to host and serve Converse yourself, there are a few options available.
2019-05-28 17:12:50 +02:00
Let your XMPP server serve Converse for you
-------------------------------------------
If you run your own XMPP server, you might first want to check whether it has
2020-09-18 11:19:44 +02:00
a plugin or module for hosting Converse.
2019-05-28 17:12:50 +02:00
2022-06-10 17:24:41 +02:00
* `Openfire <http://www.igniterealtime.org/projects/openfire/> `_ has the `inverse <https://www.igniterealtime.org/projects/openfire/plugin-archive.jsp?plugin=inverse> `_ plugin.
* `Prosody <https://prosody.im/> `_ has `mod_conversejs <https://modules.prosody.im/mod_conversejs.html> `_ .
* `ejabberd <http://www.ejabberd.im/> `_ has `mod_conversejs <https://docs.ejabberd.im/admin/configuration/modules/#mod-conversejs> `_ .
2019-05-28 17:12:50 +02:00
Serving Converse yourself
-------------------------
2020-09-18 11:19:44 +02:00
Alternative you can serve only Converse without requiring any particular XMPP server.
2019-05-28 17:12:50 +02:00
2020-09-18 11:19:44 +02:00
To do so, you'll need to get the right files to host, for which you have four options.
2019-05-28 17:12:50 +02:00
.. note ::
2020-09-18 11:19:44 +02:00
Pro-tip, if you just want to quickly test things locally, you can run `` make serve `` inside a checkout of the Converse repo.
Converse is then hosted at http://localhost:8000
2019-05-28 17:12:50 +02:00
2018-10-26 15:39:49 +02:00
Option 1: Use the content delivery network
2019-05-28 17:12:50 +02:00
***** ***** ***** ***** ***** ***** ***** ***** **
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
2019-05-22 14:03:13 +02:00
* https://cdn.conversejs.org/dist/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
2023-08-31 21:00:52 +02:00
* https://cdn.conversejs.org/10.1.6/dist/converse.min.js
* https://cdn.conversejs.org/10.1.6/dist/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
2023-08-31 21:00:52 +02:00
<link rel="stylesheet" type="text/css" media="screen" href="https://cdn.conversejs.org/10.1.6/dist/converse.min.css">
<script src="https://cdn.conversejs.org/10.1.6/dist/converse.min.js" charset="utf-8"></script>
2017-04-18 19:24:49 +02:00
2018-10-26 15:39:49 +02:00
2019-05-28 16:29:41 +02:00
Option 2: Download the builds from Github
2019-05-28 17:12:50 +02:00
***** ***** ***** ***** ***** ***** ***** ***** *
2019-05-28 16:29:41 +02:00
The `Converse releases page on Github <https://github.com/conversejs/converse.js/releases> `_
has the release notes for every release as well as links to downloadable zip files
containing all the files you need to host Converse yourself.
Extract the zip file and include converse.min.js and converse.min.css files in
2019-05-28 16:31:57 +02:00
the *<head>* element of your page, similar as shown in option 1 above.
2019-05-28 16:29:41 +02:00
Option 3: Building the files yourself
2019-05-28 17:12:50 +02:00
***** ***** ***** ***** ***** ***** ***** **
2018-10-26 15:39:49 +02:00
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
2020-09-18 11:19:44 +02:00
To build the files and also start an HTTP server, you can run `` make serve `` .
2018-10-26 15:39:49 +02:00
2020-09-18 11:19:44 +02:00
The distribution files will be added to the `` ./dist `` folder inside the repo.
2019-05-28 17:12:50 +02:00
2018-09-18 10:53:43 +02:00
Initializing Converse
2019-05-28 17:12:50 +02:00
=====================
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
2020-09-18 11:19:44 +02:00
Originally this version was available as a separate build file, but
2018-01-09 15:49:45 +01:00
as of version 4.0.0 and higher, the difference between the "overlay" and the
2020-09-18 11:19:44 +02:00
"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
