feat(share_plus): support rich preview on the share sheet

[slaci]

Description

Support rich preview on Android with the help of the new title and thumbnail parameters. The title is also used for the Web Share API's title parameter in favor of the subject, but falls back to the subject for backward compatibility (as the previous code used the subject for this).

The contribution guide says features for only one platform won't be accepted, but I still want to try.

Related Issues

• Fix [Request]: (share_plus) EXTRA_TITLE in share Intent on Android #3307
• Fix [share_plus] [Request]: Thumbnail support #1221
• Related [Request]: share_plus refactor and cleanup #1099

Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I titled the PR using Conventional Commits.
• I did not modify the CHANGELOG.md nor the plugin version in pubspec.yaml files.
• All existing and new tests are passing.
• The analyzer (flutter analyze) does not report any problems on my PR.

Breaking Change

Does your PR require plugin users to manually update their apps to accommodate your change?

• Yes, this is a breaking change (please indicate that with a ! in the title as explained in Conventional Commits).
• No, this is not a breaking change.

[miquelbeltran]

Hi @slaci thanks for the contribution!

I am not convinced about adding another two parameters to the method, specially title, which added to text and subject just becomes more confusing what does what on which platform.

The share method definitely needs a refactor and a parameter cleanup in some way. Maybe this PR is an opportunity to do that?

There is some discussion about that in #3307

The contribution guide says features for only one platform won't be accepted, but I still want to try.

That's true, maybe there is a way to provide a preview thumbnail on iOS as well?

[vbuberen]

I like the idea of adding this functionality as it is something that Android offers by default. But agree with Miguel that we might think about the API more here.

[slaci]

I can extract the thumbnail to a SharePlusAndroidSettings class or something. The sharePositionOrigin could go into an IOS or Apple one, but that would be a breaking change (or the parameter could be deprecated first of course).

The rest of the parameters are problematic, as the new title param is not the odd one, but the subject. Android uses the title for the EXTRA_TITLE parameter and the web uses it as the title parameter of the Web Share API. For iOS I may need some more research indeed, but as I see that could also use the title. There is the thumbnailImageForActivityType method which currently returns the image when an image is shared. It may be worth to check how this works (what happens if I pass a thumbnail to it when sharing text). When an NSURL is shared, then the activityViewControllerLinkMetadata callback runs and creates an LPLinkMetadata which contains a title + thumbnail, but this is sadly only for urls (as far as I understand).

[slaci]

I have spent some hours checking the iOS thumbnail possibilities, but sadly I couldn't figure out when the mentioned thumbnailImageForActivityType runs.

There are multiple reports about this, but sadly without any answers: SO | Apple Forum

From the docs it seems like it depends on the target app (though not 💯 ), like the subject (eg. the subjectForActivityType runs for the Mail app), but I couldn't find any app that would trigger the thumbnail callback or maybe it is totally bugged on iOS 18.

I haven't played with the title too much yet, but currently the subject is used for the LPLinkMetadata's title when it is available which is incosistent with my changes. However it is only used for shareXFiles (because files are provided as NSURL-es, so they have this metadata) where I don't pass the title as providing a title when sharing files didn't do anything on Android nor web (will need to check what happens on iOS if anything in this case).

So if I could make the thumbnail work on iOS, then it could stay as a common option, otherwise I guess I would need to extract it to a Platform specific option class.

[miquelbeltran]

Thanks for looking into it @slaci !

Re: params, I'm thinking that just having a single ShareParams class with all options may be the easiest, unify it all into a single share(ShareParams) method, and that should go all the way down. That will allow us to use any of the provided optional params no matter if sharing a uri, text, or files. We may need to add some asserts to enforce providing certain combination of params, but that would be it.

class ShareParams {
  final String? text;

  /// Used as share sheet title where supported (e.g. EXTRA_TITLE on Android)
  final String? title;

  /// Only used as email subject where supported (e.g. EXTRA_SUBJECT on Android)
  final String? subject;

  /// Only used in Android as preview thumbnail
  final XFile? previewThumbnail;

  /// Only used in iPad and Mac as share sheet origin
  final Rect? sharePositionOrigin;

  /// Share a URI, alternative to sharing [text]
  final Uri? uri;

  /// Share multiple files, can be used in combination with [text]
  final List<XFile>? files;
  final List<String>? fileNameOverrides;

  ShareParams({
    this.text,
    this.subject,
    this.extraTitle,
    this.previewThumbnail,
    this.sharePositionOrigin,
    this.uri,
    this.files,
    this.fileNameOverrides,
  });
}

Since we would be at it, I'd like to unify all methods into one, and to make Share class instantiable, instead of providing a static method (some people have asked this to be able to mock it)

[miquelbeltran]

Added a comment on #3307 (comment) your feedback would be appreciated!

[miquelbeltran]

FYI, started working on the shareplus refactor, that should simplify adding this and other optional parameters: #3404