taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

081-shop-discovery.rst (4494B)

      1 DD 81: Shop Discovery
      2 #####################
      3 
      4 Summary
      5 =======
      6 
      7 This design document specifies a feature provided by wallets that enables
      8 users to find shops that accept Taler payments in a particular currency.
      9 
     10 Motivation
     11 ==========
     12 
     13 After withdrawing money into their Taler wallet, users do not necessarily know
     14 many shops that accept Taler payments.
     15 
     16 Requirements
     17 ============
     18 
     19 * Feature should be easily discoverably by users
     20 * Implementation should have minimal complexity
     21 
     22 Proposed Solution
     23 =================
     24 
     25 Exchanges provide meta-data that allows wallets to help users discover shops
     26 that accept Taler.
     27 
     28 In the MVP of this feature, an exchange can publish a single link to a website.
     29 
     30 In later iterations, the exchange could also provide more structured data, like
     31 map markers (coordinates + description + icon?) that the wallet displays in an
     32 aggregated fashion.
     33 
     34 As of now (2026-01-20), we'll only implement the MVP with a single link per
     35 exchange, since:
     36 
     37 * The map would add complexity
     38 * Structured data would require a spec and separate exchange APIs
     39 * Maps are difficult to provide on mobile platforms in a way that
     40   is compatible with software freedoms while at the same not
     41   raising the complexity of the app enormously.
     42 
     43 Implementation Plan (MVP)
     44 =========================
     45 
     46 Exchange API
     47 ------------
     48 
     49 An exchange can configure **one** shopping URL that is returned by the ``/keys`` response (in the ``shopping_url`` field).
     50 
     51 
     52 Wallet-core API
     53 ---------------
     54 
     55 The response to ``getBalances`` already lists all currency scopes with their
     56 balance info. This response is extended with into about the applicable shopping
     57 URLs in the field ``balances[].shoppingUrls``.
     58 
     59 When multiple exchanges in a scope offer the same shopping URL, duplicates are filtered
     60 in the ``shoppingUrls`` field.
     61 
     62 Example response (some fields omitted):
     63 
     64 .. code:: typescript
     65 
     66    // getBalances response with shopping URLs
     67    {
     68      "balances": [
     69        {
     70          "scopeInfo": {
     71            "currency": "CHF",
     72            "type": "global",
     73          },
     74          "available": "CHF:5",
     75          "shoppingUrls": [
     76            "https://shops.taler-ops.ch/"
     77          ],
     78          // [...]
     79        }
     80      ]
     81    }
     82 
     83 
     84 Wallet UI
     85 ---------
     86 
     87 .. image:: images/081/wireframe-shopping-urls.excalidraw.svg
     88 
     89 Description:
     90 
     91 * When the user presses the Taler action button,
     92   the menu sheet now displays a new UI element with
     93   the label "Where to pay with $CURRENCY".
     94 
     95   * TBD: How does this look on the webext where we do not have an action button?
     96 
     97 * The $CURRENCY is determined by currency (scope) that the
     98   user currently has selected.
     99 
    100 * When there are no shopping URLs available, the UI element
    101   is now shown.
    102 
    103 * TBD: What happens when no currency scope is selected, i.e.
    104   the user is on the overview screen?
    105 
    106   * Alternative A: No extra UI element for shop discovery is shown.
    107   * Alternative B: Shop discovery item gets label "Where to pay with Taler",
    108     when tapping/clicking, user first selects currency scope from a list.
    109 
    110 * When tapping/clicking the shop discovery element, the app shows another page
    111   with the available shop discovery link(s).
    112 
    113 Alternatives:
    114 
    115 * The shop discover button could directly lead the user to
    116   the ``shopping_url`` Website instead of showing another screen.
    117 
    118   * Incompatible with multiple links
    119   * Better to show the URL to the user before they visit it
    120 
    121 * The "Where to pay with $CURRENCY" could also be displayed
    122   in the currency overview with the new Vlada-style design
    123   for that view.  However, since it's currently not implemented
    124   on any platform, the proposed UI puts the new element in
    125   the action button menu.
    126 * The "Where to pay with $CURRENCY" could allow the user to
    127   select a different currency. 
    128 
    129 
    130 Test Plan
    131 =========
    132 
    133 * Deployed exchanges already provide shopping URLs.
    134 * A wallet-core dev experiment can be used to override exchange scopes and shopping URLs.
    135 
    136 Definition of Done
    137 ==================
    138 
    139 * [x] Implemented in exchange
    140 * [x] Implemented in wallet-core
    141 * [ ] Consensus on DD
    142 * [ ] Implemented on Android UI
    143 * [ ] Implemented on iOS UI
    144 * [ ] Implemented on webext UI
    145 * [ ] QC session with Android UI
    146 * [ ] QC session with iOS UI
    147 * [ ] QC session with webext UI
    148 
    149 
    150 Alternatives
    151 ============
    152 
    153 * Structured data / map.
    154 
    155   * Could happen later, but not for first iteration / MVP.
    156 
    157 Drawbacks
    158 =========
    159 
    160 * Extra complexity.
    161 
    162 Discussion / Q&A
    163 ================
    164 
    165 (This should be filled in with results from discussions on mailing lists / personal communication.)