From 3125aef3058b17ea94a2d0a1cd52fae8fbc53573 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Tue, 6 May 2025 16:47:45 +0100 Subject: [PATCH 1/4] App store compliant handling of payment links within events --- proposals/xxxx-external-payment-details.md | 130 +++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 proposals/xxxx-external-payment-details.md diff --git a/proposals/xxxx-external-payment-details.md b/proposals/xxxx-external-payment-details.md new file mode 100644 index 00000000000..7c441b04450 --- /dev/null +++ b/proposals/xxxx-external-payment-details.md @@ -0,0 +1,130 @@ +# MSCxxxx: App store compliant handling of payment links within events + +## Background + +Developers of Matrix clients that are distributed via the Apple [App Store](https://www.apple.com/app-store/) must comply with the [App Review Guidelines](https://developer.apple.com/app-store/review/guidelines/). + +These guidelines include restrictions on which payment methods are offered and how they are accessed. + +If a homeserver operator requires a paid plan for usage of some capabilities then a conflict of interests can arise between the homserver operator and the application developer: + +The homeserver operator may wish to promote the paid service by sending [Server Notices](https://spec.matrix.org/v1.14/client-server-api/#server-notices) to the user or some equivalent mechanism. However, the App Review Guidelines impose restrictions on the Matrix client such as: + +> **3.1.3(f) Free Stand-alone Apps:** Free apps acting as a stand-alone companion to a paid web based tool (e.g. VoIP, Cloud Storage, Email Services, Web Hosting) do not need to use in-app purchase, provided there is no purchasing inside the app, or calls to action for purchase outside of the app. + +A Server Notice that contains a link to an account management page that offers sign up would likely fall within the class of *"calls to action for purchase outside of the app"*. + +As things stand today, if the homeserver wishes to allow users to use whichever client they wish then the homeserver operator cannot put payment links into the events. + +This MSC proposes a way in which the homeserver and the client developer can collaborate to provide a satisfactory user experience whilst also remaining compliant. + +## Proposal + +Build on the `org.matrix.custom.html` format and add a permitted attribute `data-mx-external-payment-details` to the `` tag. + +This would mean that clients can choose whether to render the ``. + +This is similar to how [spoilers](https://spec.matrix.org/v1.14/client-server-api/#spoiler-messages) work today. + +An example of full event might look as follows: + +```json +{ + "msgtype": "m.text", + "format": "org.matrix.custom.html", + "body": "Please use a web browser to manage your account", + "formatted_body": "Please use a web browser to manage your account or click here" +} +``` + +On a client that is aware of the new attribute and chooses to not render, it would appear as: + +> Please use a web browser to manage your account + +However, on a client that is either not-aware or chooses to render, then it would appear as: + +> Please use a web browser to manage your account or click [here](https://account.example.com/plan) + +## Potential issues + +### Opt-in for clients means potentially not compliant by default + +When formulating this proposal, it was considered what would be the best approach to balance: work effort, client compliance, and user experience. + +The following table outlines the options that were considered: + +Approach | Description | For | Against +-|-|-|- +Restricted clients opt-in (as proposed) | Additional metadata is added to events so that "restricted" clients can hide the restricted content | - Only restricted clients (e.g. iOS) need to be updated
- No change needed for other clients | - Restricted clients may not be compliant by default, as they need to be aware of and implement this new capability +Compliant by default | Remove payment links from events. Then provide metadata to say that there is version of the content with links | - All clients are compliant by default as no payment links are present| - All non-restricted clients would ideally be updated to be aware of the presence of the extended content and deliver the best UX + +The first approach was chosen as it is the least disruptive to existing clients and that there is a small number of known iOS clients to consider. + +### Per territory restrictions + +Some App Store restrictions apply per territory. In such cases a client may base the decision whether to render on both the presence of the `data-mx-external-payment-details` attribute and the territory that the device is configured against. + +## Alternatives + +### Additional field along side the `formatted_body` + +Instead of modifying the `formatted_body` you could add a field alongside that the client could choose to render. + +e.g. + +```json +{ + "msgtype": "m.text", + "format": "org.matrix.custom.html", + "body": "Please use a web browser to manage your account", + "formatted_body": "Please use a web browser to manage your account", + "formatted_body_with_external_payment_details": "You can manage your account here" +} +``` + +Or the inverse: + +```json +{ + "msgtype": "m.text", + "format": "org.matrix.custom.html", + "body": "Please use a web browser to manage your account", + "formatted_body": "You can manage your account here", + "formatted_body_without_external_payment_details": "Please use a web browser to manage your account" +} +``` + +A benefit of this approach is that the entire rendering can be replaced and not just that which is covered by the `span`. + +### Extensible events + +One could define a mix-in called `m.payment_details_hidden` with content which should be displayed by clients which know they should hide payment details. Something like this: + +```json +{ + "msgtype": "m.text", + "format": "org.matrix.custom.html", + "body": "Please use a web browser to manage your account", + "formatted_body": "You can manage your account here", + "m.payment_details_hidden": { + "m.text": "Please use a web browser to manage your account", + "m.html": "Please use a web browser to manage your account", + } +} +``` + +However, this is clunky and has more duplication, and the spoiler-text inspired approach seems good enough. + +## Security considerations + +No additional requirements. The client should continue apply the existing security constraints to `formatted_body`. + +## Unstable prefix + +The following should be used: + +- `data-mscXXXX-external-payment-details` instead of `data-mx-external-payment-details` + +## Dependencies + +None. From 62a7433424171c4c8029c0f79ee19e3a5544de0e Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Tue, 6 May 2025 16:48:37 +0100 Subject: [PATCH 2/4] MSC4286 --- ...al-payment-details.md => 4286-external-payment-details.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename proposals/{xxxx-external-payment-details.md => 4286-external-payment-details.md} (97%) diff --git a/proposals/xxxx-external-payment-details.md b/proposals/4286-external-payment-details.md similarity index 97% rename from proposals/xxxx-external-payment-details.md rename to proposals/4286-external-payment-details.md index 7c441b04450..04ba76dc57a 100644 --- a/proposals/xxxx-external-payment-details.md +++ b/proposals/4286-external-payment-details.md @@ -1,4 +1,4 @@ -# MSCxxxx: App store compliant handling of payment links within events +# MSC4286: App store compliant handling of payment links within events ## Background @@ -123,7 +123,7 @@ No additional requirements. The client should continue apply the existing securi The following should be used: -- `data-mscXXXX-external-payment-details` instead of `data-mx-external-payment-details` +- `data-msc4286-external-payment-details` instead of `data-mx-external-payment-details` ## Dependencies From f40d72b0a397179f848942b318b157e053c15728 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Tue, 6 May 2025 16:56:31 +0100 Subject: [PATCH 3/4] Line length --- proposals/4286-external-payment-details.md | 49 +++++++++++++++------- 1 file changed, 34 insertions(+), 15 deletions(-) diff --git a/proposals/4286-external-payment-details.md b/proposals/4286-external-payment-details.md index 04ba76dc57a..be84e28a6c1 100644 --- a/proposals/4286-external-payment-details.md +++ b/proposals/4286-external-payment-details.md @@ -2,25 +2,37 @@ ## Background -Developers of Matrix clients that are distributed via the Apple [App Store](https://www.apple.com/app-store/) must comply with the [App Review Guidelines](https://developer.apple.com/app-store/review/guidelines/). +Developers of Matrix clients that are distributed via the Apple [App Store](https://www.apple.com/app-store/) +must comply with the [App Review Guidelines](https://developer.apple.com/app-store/review/guidelines/). These guidelines include restrictions on which payment methods are offered and how they are accessed. -If a homeserver operator requires a paid plan for usage of some capabilities then a conflict of interests can arise between the homserver operator and the application developer: +If a homeserver operator requires a paid plan for usage of some capabilities then a conflict of +interests can arise between the homserver operator and the application developer: -The homeserver operator may wish to promote the paid service by sending [Server Notices](https://spec.matrix.org/v1.14/client-server-api/#server-notices) to the user or some equivalent mechanism. However, the App Review Guidelines impose restrictions on the Matrix client such as: +The homeserver operator may wish to promote the paid service by sending +[Server Notices](https://spec.matrix.org/v1.14/client-server-api/#server-notices) to the user or +some equivalent mechanism. However, the App Review Guidelines impose restrictions on the Matrix +client such as: -> **3.1.3(f) Free Stand-alone Apps:** Free apps acting as a stand-alone companion to a paid web based tool (e.g. VoIP, Cloud Storage, Email Services, Web Hosting) do not need to use in-app purchase, provided there is no purchasing inside the app, or calls to action for purchase outside of the app. +> **3.1.3(f) Free Stand-alone Apps:** Free apps acting as a stand-alone companion to a paid web +> based tool (e.g. VoIP, Cloud Storage, Email Services, Web Hosting) do not need to use in-app +> purchase, provided there is no purchasing inside the app, or calls to action for purchase outside +> of the app. -A Server Notice that contains a link to an account management page that offers sign up would likely fall within the class of *"calls to action for purchase outside of the app"*. +A Server Notice that contains a link to an account management page that offers sign up would likely +fall within the class of *"calls to action for purchase outside of the app"*. -As things stand today, if the homeserver wishes to allow users to use whichever client they wish then the homeserver operator cannot put payment links into the events. +As things stand today, if the homeserver wishes to allow users to use whichever client they wish +then the homeserver operator cannot put payment links into the events. -This MSC proposes a way in which the homeserver and the client developer can collaborate to provide a satisfactory user experience whilst also remaining compliant. +This MSC proposes a way in which the homeserver and the client developer can collaborate to provide +a satisfactory user experience whilst also remaining compliant. ## Proposal -Build on the `org.matrix.custom.html` format and add a permitted attribute `data-mx-external-payment-details` to the `` tag. +Build on the `org.matrix.custom.html` format and add a permitted attribute +`data-mx-external-payment-details` to the `` tag. This would mean that clients can choose whether to render the ``. @@ -49,26 +61,31 @@ However, on a client that is either not-aware or chooses to render, then it woul ### Opt-in for clients means potentially not compliant by default -When formulating this proposal, it was considered what would be the best approach to balance: work effort, client compliance, and user experience. +When formulating this proposal, it was considered what would be the best approach to balance: work +effort, client compliance, and user experience. The following table outlines the options that were considered: Approach | Description | For | Against -|-|-|- -Restricted clients opt-in (as proposed) | Additional metadata is added to events so that "restricted" clients can hide the restricted content | - Only restricted clients (e.g. iOS) need to be updated
- No change needed for other clients | - Restricted clients may not be compliant by default, as they need to be aware of and implement this new capability +Restricted clients opt-in (as proposed) | Additional metadata is added to events so that"restricted" clients can hide the restricted content | - Only restricted clients (e.g. iOS) need to be updated
- No change needed for other clients | - Restricted clients may not be compliant by default, as they need to be aware of and implement this new capability Compliant by default | Remove payment links from events. Then provide metadata to say that there is version of the content with links | - All clients are compliant by default as no payment links are present| - All non-restricted clients would ideally be updated to be aware of the presence of the extended content and deliver the best UX -The first approach was chosen as it is the least disruptive to existing clients and that there is a small number of known iOS clients to consider. +The first approach was chosen as it is the least disruptive to existing clients and that there is a +small number of known iOS clients to consider. ### Per territory restrictions -Some App Store restrictions apply per territory. In such cases a client may base the decision whether to render on both the presence of the `data-mx-external-payment-details` attribute and the territory that the device is configured against. +Some App Store restrictions apply per territory. In such cases a client may base the decision +whether to render on both the presence of the `data-mx-external-payment-details` attribute and the +territory that the device is configured against. ## Alternatives ### Additional field along side the `formatted_body` -Instead of modifying the `formatted_body` you could add a field alongside that the client could choose to render. +Instead of modifying the `formatted_body` you could add a field alongside that the client could +choose to render. e.g. @@ -94,11 +111,13 @@ Or the inverse: } ``` -A benefit of this approach is that the entire rendering can be replaced and not just that which is covered by the `span`. +A benefit of this approach is that the entire rendering can be replaced and not just that which is +covered by the `span`. ### Extensible events -One could define a mix-in called `m.payment_details_hidden` with content which should be displayed by clients which know they should hide payment details. Something like this: +One could define a mix-in called `m.payment_details_hidden` with content which should be displayed +by clients which know they should hide payment details. Something like this: ```json { From 304ded59fb8087d65150077817ee274ae2c006d0 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Sat, 14 Jun 2025 13:45:22 +0100 Subject: [PATCH 4/4] Update proposals/4286-external-payment-details.md Co-authored-by: Christian Paul --- proposals/4286-external-payment-details.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4286-external-payment-details.md b/proposals/4286-external-payment-details.md index be84e28a6c1..0453ce5ae79 100644 --- a/proposals/4286-external-payment-details.md +++ b/proposals/4286-external-payment-details.md @@ -8,7 +8,7 @@ must comply with the [App Review Guidelines](https://developer.apple.com/app-sto These guidelines include restrictions on which payment methods are offered and how they are accessed. If a homeserver operator requires a paid plan for usage of some capabilities then a conflict of -interests can arise between the homserver operator and the application developer: +interests can arise between the homeserver operator and the application developer: The homeserver operator may wish to promote the paid service by sending [Server Notices](https://spec.matrix.org/v1.14/client-server-api/#server-notices) to the user or