@rea.ch/capacitor-native-share

Converts a native share to a js event.

Install

In order to use this library, first add it to your project by:

npm install @rea.ch/capacitor-native-share --save

or

yarn add @rea.ch/capacitor-native-share

Web

There are two methods that can be used to obtain the shared items:

• getLastSharedItems: Returns a promise that resolves in the last items shared to the app. The idea behind this is to use it as soon as the app is initialized.

• addListener: Emits every time the app receives a share only if the listener was registered before receiving the shared.

Example

import { NativeShare } from '@rea.ch/capacitor-native-share';

// ...

public onAppInitialization(): void {
	NativeShare.getLastSharedItems()
		.then(this.handleShare.bind(this))
		.catch(console.error);

	NativeShare.addListener(
		NativeShareEventType.SHARE_RECEIVED,
		this.handleShare.bind(this)
	);
}

private handleShare(share: NativeShareShareReceived): void {
	// ...
}

Android

Edit your android's AndroidManifest.xml file with the types that you want to handle (ref):

<!-- Single share -->
<intent-filter>
	<action android:name="android.intent.action.SEND" />

	<category android:name="android.intent.category.DEFAULT" />
	<category android:name="android.intent.category.BROWSABLE" />

	<!-- Any type of data -->
	<data android:mimeType="*/*" />
</intent-filter>

<!-- multiple share -->
<intent-filter>
	<action android:name="android.intent.action.SEND_MULTIPLE" />

	<category android:name="android.intent.category.DEFAULT" />
	<category android:name="android.intent.category.BROWSABLE" />

	<!-- Any type of data -->
	<data android:mimeType="*/*" />
</intent-filter>

iOS

There are some special setup that needs to be done in iOS:

App Extension

Create an App Share Extension.

App Group

Create an App Group so the extension and the app can share data.

Modify your Podfile

You need to modify your Podfile to include a library to your extension:

...
target 'App' do
  capacitor_pods
  # Add your Pods here
end

+ target 'YOUR_SHARE_EXTENSION_NAME' do
+   # We need this to override the extension class
+   pod 'Rea.chCapacitorNativeShare', :path => '../../node_modules/@rea.ch/capacitor-share-extension'
+ end

Override extension class

Extend the class NativeShareExtension in your extension's ShareViewController.swift and:

1. override the function getContainerAppUrlExtension so it returns your App's Url Scheme (tutorial).

2. override the function getAppGroupIdentifier so it returns yout extension and app's App Group's name.

import UIKit
import Social
import MobileCoreServices
import ReachCapacitorNativeShare

class ShareViewController: NativeShareExtension {
    override func getContainerAppUrlExtension() -> String {
        return "ReachCapacitorNativeShareExample"
    }

    override func getAppGroupIdentifier() -> String {
        return "group.ch.rea.plugins.nativeshareexample"
    }
}

Override AppDelegate class

Modify your AppDelegate.swift with the following

import ReachCapacitorNativeShare

// ...

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    // ...
    
    var store: NativeShareStore = NativeShareStore.store

	// ...

	func applicationWillTerminate(_ application: UIApplication) {
        NativeShareDelegateUtils.cleanTemporalFolder( appGroupName: "YOUR_APP_GROUP_NAME" )
    }

    func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
        let success: Bool = ApplicationDelegateProxy.shared.application(app, open: url, options: options)

        let nativeShareHandlerSuccess = NativeShareDelegateUtils.handleApplicationUrl(app: app, url: url, store: store)

        return success && nativeShareHandlerSuccess
    }

	// ...
}

Common errors

sharedApplication is unavailable

'sharedApplication' is unavailable: not available on iOS (App Extension) - Use view controller based solutions where appropriate instead.

Uncheck the Pods targets Capacitor and CapacitorCordova's Allow app extension API only option after every cap sync or pod install. ref

API

• Interfaces

Interfaces

NativeShareGetItemsOptions

| Prop | Type | Description | | ---------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | autoRemove | boolean | Whether to remove the share event so if you call {@link NativeSharePlugin.getLastSharedItems} again it will return void. Default: true. |

NativeShareShareReceived

| Prop | Type | | ------------ | ------------------------------------------------------------------------------- | | items | { [idx: string]: NativeShareItem; } | | length | number |

NativeShareItem

| Prop | Type | Description | | -------------- | ------------------- | ------------------------------------------ | | text | string | The text shared. It can also be a website. | | uri | string | The uri (path) to the shared file. | | mimeType | string | The mimeType of the shared file. |

Alternatives

This library is based on these two libraries that handles the share in a similar way:

• carsten-klaffke/send-intent
• marwonline/capacitor-share-target