diff options
Diffstat (limited to 'StoneIsland/plugins/cordova-plugin-x-socialsharing/README.md')
| -rw-r--r--[-rwxr-xr-x] | StoneIsland/plugins/cordova-plugin-x-socialsharing/README.md | 104 |
1 files changed, 82 insertions, 22 deletions
diff --git a/StoneIsland/plugins/cordova-plugin-x-socialsharing/README.md b/StoneIsland/plugins/cordova-plugin-x-socialsharing/README.md index 21709982..52e5515c 100755..100644 --- a/StoneIsland/plugins/cordova-plugin-x-socialsharing/README.md +++ b/StoneIsland/plugins/cordova-plugin-x-socialsharing/README.md @@ -24,6 +24,7 @@ Every now and then kind folks ask me how they can give me all their money. So if 4. [iOS and Android](#4a-usage-on-ios-and-android) 4. [Windows Phone](#4b-usage-on-windows-phone) 4. [Share-popover on iPad](#4c-share-popover-on-ipad) + 4. [Whitelisting on iOS 9](#4d-whitelisting-on-ios-9) 5. [Credits](#5-credits) 6. [License](#6-license) @@ -154,6 +155,33 @@ However, what exactly gets shared, depends on the application the user chooses t - Facebook iOS: message, image (other filetypes are not supported), link. Beware that since a Fb update in April 2015 sharing a prefilled message is no longer possible when the Fb app is installed (like Android), see #344. Alternative: use `shareViaFacebookWithPasteMessageHint`. ### Using the share sheet +Since version 5.1.0 (for iOS and Android) it's recommended to use `shareWithOptions` as it's the most feature rich way to share stuff cross-platform. + +It will also tell you if sharing to an app completed and which app that was (if that app plays nice, that is). + +```js +// this is the complete list of currently supported params you can pass to the plugin (all optional) +var options = { + message: 'share this', // not supported on some apps (Facebook, Instagram) + subject: 'the subject', // fi. for email + files: ['', ''], // an array of filenames either locally or remotely + url: 'https://www.website.com/foo/#bar?a=b', + chooserTitle: 'Pick an app' // Android only, you can override the default share sheet title +} + +var onSuccess = function(result) { + console.log("Share completed? " + result.completed); // On Android apps mostly return false even while it's true + console.log("Shared to app: " + result.app); // On Android result.app is currently empty. On iOS it's empty when sharing is cancelled (result.completed=false) +} + +var onError = function(msg) { + console.log("Sharing failed with message: " + msg); +} + +window.plugins.socialsharing.shareWithOptions(options, onSuccess, onError); +``` + +#### You can still use the older `share` method as well Here are some examples you can copy-paste to test the various combinations: ```html <button onclick="window.plugins.socialsharing.share('Message only')">message only</button> @@ -226,6 +254,18 @@ iOS Quirks: <button onclick="window.plugins.socialsharing.shareViaWhatsApp('Message via WhatsApp', null /* img */, null /* url */, function() {console.log('share ok')}, function(errormsg){alert(errormsg)})">msg via WhatsApp (with errcallback)</button> ``` +##### Experimental feature: sharing directly to someone +Available in 5.0.8 and up - please let me know if this works for your device! Open an issue if not.. + +```html +<button onclick="window.plugins.socialsharing.shareViaWhatsAppToReceiver(receiver, 'Message via WhatsApp', null /* img */, null /* url */, function() {console.log('share ok')})">msg via WhatsApp for Addressbook ID 101</button> +``` +For `receiver` on iOS pass in the Addressbook ID (or 'abid'). You can find those abid's by using the [Cordova Contacts Plugin](https://github.com/apache/cordova-plugin-contacts). +The result in the success callback of the `find` function is a JSON array of contact objects, use the 'id' you find in those objects. +Don't pass in an image on iOS because that can't be sent to someone directly unfortunately. Message and URL are fine though. + +On Android pass in the phone number of the person you want to send a message to (untested at the moment). + ####SMS Note that on Android, SMS via Hangouts may not behave correctly ```html @@ -247,7 +287,7 @@ window.plugins.socialsharing.shareViaEmail( ['cc@person1.com'], // CC: must be null or an array null, // BCC: must be null or an array ['https://www.google.nl/images/srpr/logo4w.png','www/localimage.png'], // FILES: can be null, a string, or an array - onSuccess, // called when sharing worked, but also when the user cancelled sharing via email (I've found no way to detect the difference) + onSuccess, // called when sharing worked, but also when the user cancelled sharing via email. On iOS, the callbacks' boolean result parameter is true when sharing worked, false if cancelled. On Android, this parameter is always true so it can't be used). See section "Notes about the successCallback" below. onError // called when sh*t hits the fan ); ``` @@ -441,31 +481,51 @@ window.plugins.socialsharing.setIPadPopupCoordinates(targetBounds); window.plugins.socialsharing.share('Hello from iOS :)') ``` -## 5. Credits ## +## 4d. Whitelisting on iOS 9 -This plugin was enhanced for Plugman / PhoneGap Build by [Eddy Verbruggen](http://www.x-services.nl). -The Android and Windows Phone code was entirely created by the author. -The first iteration of the iOS code was inspired by [Cameron Lerch](https://github.com/bfcam/phonegap-ios-social-plugin). +On iOS 9 you have to make sure to whitelist the applications you want to use for sharing. Without whitelisting "query schemes", you may get the error callback invoked when calling the `canShareVia` function (and possibly the `shareVia`). You can verify this is a permissions issue by observing the output in XCode for something like: + +> -canOpenURL: failed for URL: "whatsapp://app" - error: "This app is not allowed to query for scheme whatsapp" +You have a few options to prevent this by whitelisting the application you want to share via: -## 6. License +### Directly editing the .plist file +This is a stright forward approach - you just manually edit the .plist file - either from within XCode or using a text editor. You can see example entries above (e.g. xyz). While this is simple to do, the changes may be lost when rebuilding the project or tweaking the platform (e.g. upgrading) and is less recomended. -[The MIT License (MIT)](http://www.opensource.org/licenses/mit-license.html) +### Use query schema plugin +There is a plugin designed specifically to address query schema whitelisting. You can find the plugin and how to use it [here](https://www.npmjs.com/package/cordova-plugin-queries-schemes). In general, after installation, you can change plugin.xml file under the plugin subfolder within the plugins directory of your project to add the required schemas. Here again though, you have to edit an additional file and should take care not to overwrite it when making changes to your project. -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: +### Use Custom Config plugin +The Custom Config plugin ([here](https://github.com/dpa99c/cordova-custom-config)) allows you to add configuration to your platforms "native" configuration files (e.g. .plist or AndroidManifest.xml) through the project's main config.xml file. -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. +To address query schema issue, after installaing the plugin you can edit the iOS platform section of your config.xml (in the project main folder) to include the required entries: + +```xml +<?xml version='1.0' encoding='utf-8'?> +<widget id="your.app.id" + version="0.9.1" + xmlns="http://www.w3.org/ns/widgets" + xmlns:cdv="http://cordova.apache.org/ns/1.0"> + + <!-- a bunch of elements like name, description etc --> + + <platform name="ios"> + + <!-- add this entry --> + <config-file platform="ios" target="*-Info.plist" parent="LSApplicationQueriesSchemes"> + <array> + <string>whatsapp</string> + <!-- add more query scheme strings --> + </array> + </config-file> + </platform> +</widget> +``` -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN -THE SOFTWARE. +The advantage with this method is that editing is done in the config.xml file which will most often be in your source control anyway and hence, changes to it will be reserved. + +## 5. Credits ## + +This plugin was enhanced for Plugman / PhoneGap Build by [Eddy Verbruggen](http://www.x-services.nl). +The Android and Windows Phone code was entirely created by the author. +The first iteration of the iOS code was inspired by [Cameron Lerch](https://github.com/bfcam/phonegap-ios-social-plugin). |