Meir!!! copy
for iOS and Android, by Eddy Verbruggen
- This repo is for PhoneGap 3.0.0 and up
- For PhoneGap 2.9.0 and lower, switch to the phonegap-2.9.0-and-lower branch
- Description
- Installation 2. Automatically (CLI / Plugman) 2. Manually 2. PhoneGap Build
- Usage
- URL Scheme hints
- License
This plugin allows you to start your app by calling it with a URL like mycoolapp://path?foo=bar
- Compatible with Cordova Plugman
- Submitted and waiting for approval at PhoneGap Build (more information)
- Forget about using config.xml to define a URL scheme. This plugin adds 2 essential enhancements:
- Uniform URL scheme with Android (for which there is no option to define a URL scheme via PhoneGap configuration at all).
- You still need to wire up the Javascript to handle incoming events. This plugin assists you with that.
- Tested on iOS 5.1, 6 and 7.
- Unlike iOS, there is no way to use config.xml to define a scheme for your app. Now there is.
- Tested on Android 4.3, will most likely work with 2.2 and up.
LaunchMyApp is compatible with Cordova Plugman.
Replace mycoolapp
by a nice scheme you want to have your app listen to:
$ cordova plugin add https://github.com/EddyVerbruggen/LaunchMyApp-PhoneGap-Plugin.git --variable URL_SCHEME=mycoolapp
(note that the phonegap cli doesn't accept variables, so please use the cordova cli as shown above)
The LaunchMyApp.js file is brought in automatically.
Note for iOS: there was a bug in CLI which caused an error in your *-Info.plist
.
Please manually remove the blank line and whitespace (if any) from NSMainNibFile
and NSMainNibFile~ipad
(or your app won't start at all).
1. Copy www/ios/LaunchMyApp.js
to www/js/plugins/LaunchMyApp.js
and reference it in your index.html
:
<script type="text/javascript" src="js/plugins/LaunchMyApp.js"></script>
2. Add this to your *-Info.plist
(replace URL_SCHEME
by a nice scheme you want to have your app listen to, like mycoolapp
):
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleURLSchemes</key>
<array>
<string>URL_SCHEME</string>
</array>
</dict>
</array>
1. Copy www/android/LaunchMyApp.js to www/js/plugins/LaunchMyApp.js and reference it in your index.html
:
<script type="text/javascript" src="js/plugins/LaunchMyApp.js"></script>
2. Add the following xml to your config.xml
to always use the latest version of this plugin:
<plugin name="LaunchMyApp" value="nl.xservices.plugins.LaunchMyApp"/>
3. Copy LaunchMyApp.java
to platforms/android/src/nl/xservices/plugins
(create the folders)
4. Add the following to your AndroidManifest.xml
inside the /manifest/application/activity
node (replace URL_SCHEME
by a nice scheme you want to have your app listen to, like mycoolapp
):
<intent-filter>
<data android:scheme="URL_SCHEME"/>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
</intent-filter>
5. In AndroidManifest.xml
set the launchMode to singleTask to avoid issues like [#24]. <activity android:launchMode="singleTask" ..
Using LaunchMyApp with PhoneGap Build requires you to add the following xml to your config.xml
to use the latest version of this plugin (replace mycoolapp
by a nice scheme you want to have your app listen to):
<gap:plugin name="nl.x-services.plugins.launchmyapp">
<param name="URL_SCHEME" value="mycoolapp" />
</gap:plugin>
The LaunchMyApp.js file is brought in automatically.
1a. Your app can be launced by linking to it like this from a website or an email for example (all of these will work):
<a href="mycoolapp://">Open my app</a>
<a href="mycoolapp://somepath">Open my app</a>
<a href="mycoolapp://somepath?foo=bar">Open my app</a>
<a href="mycoolapp://?foo=bar">Open my app</a>
mycoolapp
is the value of URL_SCHEME you used while installing this plugin.
1b. If you're trying to open your app from another PhoneGap app, use the InAppBrowser plugin and launch the receiving app like this, to avoid a 'protocol not supported' error:
<button onclick="window.open('mycoolapp://', '_system')">Open the other app</button>
2. When your app is launched by a URL, you probably want to do something based on the path and parameters in the URL. For that, you could implement the (optional) handleOpenURL(url)
method, which receives the URL that was used to launch your app.
function handleOpenURL(url) {
console.log("received url: " + url);
}
If you want to alert the URL for testing the plugin, at least on iOS you need to wrap it in a timeout like this:
function handleOpenURL(url) {
setTimeout(function() {
alert("received url: " + url);
}, 0);
}
A more useful implementation would mean parsing the URL, saving any params to sessionStorage and redirecting the app to the correct page inside your app. All this happens before the first page is loaded.
Please choose a URL_SCHEME which which complies to these restrictions:
- Don't use an already registered scheme (like
fb
,twitter
,comgooglemaps
, etc). - Use only lowercase characters.
- Don't use a dash
-
because on Android it will become underscore_
. - Use only 1 word (no spaces).
TIP: test your scheme by installing the app on a device or simulator and typing yourscheme:// in the browser URL bar, or create a test HTML page with a link to your app to impress your buddies.
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:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
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.