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