summaryrefslogtreecommitdiff
path: root/integration-general.rst
blob: 308ecf5a6874cd7e39ed0703d43e875696de69f0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
.. _integration-general:

================================
Taler Wallet Website Integration
================================

.. note::
 The wallet-Websites communication is switching to a new policy which
 is NOT based on DOM events, therefore obsoleting this page. To be soon
 documented.


Websites (such as banks and online shops) can communicate with
the Taler wallet by a standardized protocol.

From a technical perspective, the Taller wallet communicates with
the website by sending and receiving `DOM events <http://www.w3.org/TR/DOM-Level-3-Events/>`_
on the bank website's ``HTMLDocument``.

DOM events used by Taler have the prefix ``taler-``.

-------------------------
Wallet Presence Awareness
-------------------------

The bank website queries the wallet's presence by sending a ``taler-probe`` event. The
event data should be `null`.

If the wallet is present and active, it will respond with a ``taler-wallet-present`` event.

While the user agent is displaying a website, the user might deactivate or
re-activate the wallet.  A Taler-aware *should* react to those events, and
indicate to the user that they should (re-)enable the wallet if necessary.

When the wallet is activated, the ``taler-wallet-load`` event is sent
by the wallet.  When the wallet is deactivated, the ``taler-wallet-unload`` event
is sent by the wallet.

.. _communication:

----------------------
Communication Example
----------------------

The bank website can send the event ``taler-XYZ`` with the event data ``eventData``
to the wallet with the following JavaScript code:

.. sourcecode:: javascript

  const myEvent = new CustomEvent("taler-XYZ", eventData);
  document.dispatchEvent(myEvent);

Events can be received by installing a listener:


.. sourcecode:: javascript

  function myListener(talerEvent) {
    // handle event here!
  }
  document.addEventListener("taler-XYZ", myListener);


--------------------
Normalized Base URLs
--------------------

Exchanges and merchants have a base URL for their service.  This URL *must* be in a
canonical form when it is stored (e.g. in the wallet's database) or transmitted
(e.g. to a bank page).

1. The URL must be absolute.  This implies that the URL has a schema.
2. The path component of the URL must end with a slash.
3. The URL must not contain a fragment or query.

When a user enters a URL that is, technically, relative (such as "alice.example.com/exchange"), wallets
*may* transform it into a canonical base URL ("http://alice.example.com/exchange/").  Other components *should not* accept
URLs that are not canonical.

Rationale:  Joining non-canonical URLs with relative URLs (e.g. "exchange.example.com" with "reserve/status") 
results in different and slightly unexpected behavior in some URL handling libraries.
Canonical URLs give more predictable results with standard URL joining.