Feat/share multiple

[jfmcquade]

PR Checklist

• PR title descriptive (can be used in release notes)

Description

Allows authoring of sharing multiple data types at once via the platform's share API, e.g. an action to share both a text and image to be sent via WhatsApp (ParentingForLifelongHealth/plh-facilitator-app-mx-content#169).

Refactors the share template action to use a new syntax. Previously, the share action use the syntax of a list of arguments, with the ability to specify a single data type, e.g. share: file: path/to/image.png. Now, a key/value pair parameter based syntax is supported, bringing this action in line with more recently added ones, as well as enabling support for multiple data types via a single action. E.g. share | file: path/to/image.png, text: @local.some_text.

Parameter.	Value	Notes
text	A string of text to share
image	A path to an image, in usual authoring format
url	A URL string
title	A string of text	This will be interpreted by some apps, e.g. it will populate the subject line of a new email when shared to an email client, but does not have wide support. For example, it appears to be ignored when sharing to WhatsApp
dialog_title	A string to display as the title of the native "share" dialog that pops up	This is stated in Capacitor's docs to be supported only on Android. However from my testing, it appears that recent versions of Android do not support it. I haven't been able to confirm support on older Android versions

Testing

Testing this functionality proved a bit difficult, considering the different moving parts and combinations of platform and target app for sharing.

We use Capacitor's Share API to interface with native share functionality on Android and iOS. As sharing files on web does not seem to be supported via Capacitor Share, I've used the Web Share API directly on web. Once the data has been shared to the device-dependent sharing feature, this has to then interface with the specific API of the targeted app. Different apps receiving the shared data will interpret it differently, and of particular interest to our use cases is WhatsApp. Whilst I couldn't find definitive up-to-date information, there was some suggestion that WhatsApp could not receive both text and image on iOS. Fortunately, it seems that information is inaccurate or outdated, as I was able to share text and image from the debug app to WhatsApp on iPhone.

In order to test the full sharing pipeline (specifically including sharing to WhatsApp), I needed to test on real devices with WhatsApp installed, as this isn't possible through appetize. From my testing, the functionality worked as expected (see screenshots below).

For additional functional testing of this PR, I think using appetize is sufficient. We should test that the share feature works as expected when sharing to some app.

• The Android emulator includes the default "Messages" app, which can be seen as analogous to WhatsApp.
• The iOS emulator does not include a messaging app. The only option is to share to the "Reminders" app, which prompts a warning that images cannot be shared without a premium account (showing at least that an image is attempting to be shared).

As long as the data is coming through as expected, we can consider the functionality to be working. Indeed, we have no control over how WhatsApp consumes the data it receives from the native share feature, so it's sufficient to confirm that we are handing over the data correctly. As stated, I was able to confirm on both Android and iOS that the feature worked as expected.

Testing links

• iOS appetize
• android appetize
• PR Web Preview link
• Link to join internal testers of the Debug App on Google Play (must be logged in with an account that is registered in the list of IDEMS Beta Testers group)
• I can invite you to test the iOS app via TestFlight on request

Git Issues

Closes #2764
Relevant content issue, which can be closed once the authoring has been updated accordingly: ParentingForLifelongHealth/plh-facilitator-app-mx-content#169

Screenshots/Videos

feature_share template:

Appetize Android:

appetize.android.mov

Appetize iOS:

appetize.ios.mov

Native iOS

I haven't made a screen recording for privacy reasons as I was testing on someone else's phone, but this image shows the text and image successfully shared to whatsapp when passed to a single share action via the text and file params:

Native Android

Annoyingly, the image itself hasn't come through to the app build that I made using the github action on the debug content repo. There is an issue with assets being included properly, as is evident on the debug web preview, likely an issue with git lfs. However, the image and text do appear to be attempted to be shared correctly with WhatsApp, and I can confirm that they come through when sharing to an email client (Outlook)

This was the result of sharing to Outlook via the first button on the tempalte, with all possible params populated:

[github-actions]

Visit the preview URL for this PR (updated for commit a7e7bb4):

https://plh-teens-app1--pr2768-feat-share-multiple-5paiigcw.web.app

_{(expires Wed, 26 Feb 2025 15:52:49 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: e4c0bab6b08dd290fbf002fd6e07987fa4b5fce1}

[chrismclarke]

I really like the move to params, think it gives the action a lot more flexibility. See a few minor nit-picks inline, but overall I think looking good.

[jfmcquade]

Thanks @chrismclarke, good suggestions for code tidying.

[chrismclarke]

Thanks for making the updates @jfmcquade , looks good to me!

[esmeetewinkel]

Looking good, appreciate the testing limitations. I tested where I could, working fine generally.

I did find when using the PR web preview on my windows computer to share (message + image) to whatsapp, that only the image was shared. Text does get shared in a message that has only text. Not sure if that is what you expected?

Screenity.video.-.Feb.6.2025.webm

[jfmcquade]

I did find when using the PR web preview on my windows computer to share (message + image) to whatsapp, that only the image was shared. Text does get shared in a message that has only text. Not sure if that is what you expected?

Yes, @ChrisMarsh82 also found some behaviour like this. It's not the behaviour I expected, but I don't think we have control over it. My understanding is that this lies with the app's integration into the platform's share API. In this case, the Web Share API's hand-off to WhatsApp Desktop on Windows. We know that both text and file are being sent by the app to the Web Share API, since variously the image and the text are shared when sharing to different target apps, so I think it's a case of WhatsApp Desktop never being able to receive both text and image from the API, and prioritising the image.

I'm aware that saying something isn't possible is a strong claim – @chrismclarke does this seem sensible?

The fact that our current use case is covered, namely sharing text and image to whatsapp on Android and iOS means that I'm happy for this to be merged as-is. One thing we could consider would be providing a warning, either to users or authors, when sharing to different platforms to try and clarify what is possible (although it is hard to get clarity without exhaustively testing all combinations of platform, sharing data, and target app).

[chrismclarke]

he app's integration into the platform's share API. In this case, the Web Share API's hand-off to WhatsApp Desktop on Windows. We know that both text and file are being sent by the app to the Web Share API, since variously the image and the text are shared when sharing to different target apps, so I think it's a case of WhatsApp Desktop never being able to receive both text and image from the API, and prioritising the image.

Yeah there will be a whole host of issues beyond our control, depending on OS (windows/mac/linux), browser (chrome/firefox/safari) / platform (android/ios + webview implementation), external target (whatsapp, email, etc.)

So I think given that it works in at least one environment I'd say the code has been implemented as best as we can hope for, for now at least. If we have a specific use case we know is required then that can be a follow-up issue for deeper dive in case there might either be workarounds or reason to provide some sort of warning/disable for specific device/platforms