summaryrefslogtreecommitdiff
path: root/integration-general.rst
blob: fc8f0d6894ce8118ecb2725d7bf28b6f6e4b6bc6 (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
================================
Taler Wallet Website Integration
================================

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.