| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="utf-8"> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> |
| <meta name="format-detection" content="telephone=no"> |
| <meta name="viewport" content="user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1, width=device-width" /> |
| <meta name="description" content=" "> |
| |
| <title> |
| |
| |
| Plugin Specification - Apache Cordova |
| |
| |
| </title> |
| |
| <link rel="SHORTCUT ICON" href="/favicon.ico"/> |
| |
| |
| |
| |
| |
| |
| <link rel="canonical" href="https://cordova.apache.org/docs/en/5.1.1/plugin_ref/spec.html"> |
| |
| <!-- CSS --> |
| <link rel="stylesheet" type="text/css" href="/static/css/main.css"> |
| <link rel="stylesheet" type="text/css" href="/static/css/lib/syntax.css"> |
| |
| <!-- Fonts --> |
| <!-- For attribution information, see www/attributions.html --> |
| <link href='https://fonts.googleapis.com/css?family=Raleway:700,400,300,700italic,400italic,300italic' rel='stylesheet' type='text/css'> |
| |
| <!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries --> |
| <!--[if lt IE 9]> |
| <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script> |
| <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script> |
| <![endif]--> |
| <script type="text/javascript"> |
| var disqus_developer = 1; // this would set it to developer mode |
| </script> |
| |
| <!-- JS --> |
| <script defer type="text/javascript" src="/static/js/lib/jquery-2.1.1.min.js"></script> |
| <script defer type="text/javascript" src="/static/js/lib/bootstrap.min.js"></script> |
| |
| <!-- Matomo --> |
| <script> |
| var _paq = window._paq = window._paq || []; |
| /* tracker methods like "setCustomDimension" should be called before "trackPageView" */ |
| _paq.push(['trackPageView']); |
| _paq.push(['enableLinkTracking']); |
| (function() { |
| var u="https://analytics.apache.org/"; |
| _paq.push(['setTrackerUrl', u+'matomo.php']); |
| _paq.push(['setSiteId', '16']); |
| var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0]; |
| g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s); |
| })(); |
| </script> |
| <!-- End Matomo Code --> |
| |
| |
| </head> |
| |
| <body> |
| <header> |
| <a class="scroll-point pt-top" name="top"></a> |
| <nav class="navbar navbar-inverse navbar-fixed-top"> |
| <div class="container-fluid"> |
| <div class="navbar-header"> |
| <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar"> |
| <span class="sr-only">Toggle navigation</span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| </button> |
| <a class="navbar-brand" href="/"><img id="logo_top" src="/static/img/cordova-logo-newbrand.svg"/></a> |
| </div> |
| <div id="navbar" class="navbar-collapse collapse"> |
| <div class="nav_bar_center"> |
| <ul class="nav navbar-nav"> |
| <li class="active"> |
| <a href="/docs/en/latest/">Documentation</a> |
| </li> |
| <li > |
| <a href="/plugins">Plugins</a> |
| </li> |
| <li > |
| <a href="/blog" id="blog_button">Blog<span class="badge" id="new_blog_count"></span></a> |
| </li> |
| <li > |
| <a href="/contribute">Contribute</a> |
| </li> |
| <li > |
| <a href="/contribute/team.html">Team</a> |
| </li> |
| <li> |
| <a href="/#getstarted">Get Started</a> |
| </li> |
| <li> |
| <form class="navbar-form navbar-right" id="header-search-form" role="search"> |
| <div class="input-group"> |
| |
| </div> |
| </form> |
| </li> |
| </ul> |
| </div> |
| </div><!--/.navbar-collapse --> |
| </div> |
| </nav> |
| <div id="_fixed_navbar_spacer" style="padding-top:50px"></div> |
| </header> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <div class="docs"> |
| |
| <!-- Table of Contents --> |
| <div class="hidden-xs hidden-sm site-toc-container"> |
| <ul class="site-toc"> |
| |
| |
| <li> |
| |
| <a class="" href="/docs/en/5.1.1/"> |
| |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| </li> |
| |
| |
| <li> |
| |
| <a class="" href="/docs/en/5.1.1/guide/overview/index.html"> |
| Overview |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| </li> |
| |
| |
| <li> |
| |
| <a class="" href="/docs/en/5.1.1/guide/support/index.html"> |
| Platform Support |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| </li> |
| |
| |
| <li> |
| |
| <a class="" href="/docs/en/5.1.1/guide/cli/index.html"> |
| The Command-Line Interface |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| </li> |
| |
| |
| <li> |
| |
| <a class="" href="/docs/en/5.1.1/guide/platforms/index.html"> |
| Platform Guides |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| </li> |
| |
| |
| <li> |
| |
| <a class="" href="/docs/en/5.1.1/plugin_ref/plugman.html"> |
| Using Plugman to Manage Plugins |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| </li> |
| |
| |
| <li> |
| |
| <a class="" href="/docs/en/5.1.1/config_ref/index.html"> |
| The config.xml File |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| </li> |
| |
| |
| <li> |
| |
| <a class="" href="/docs/en/5.1.1/config_ref/images.html"> |
| Icons and Splash Screens |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| </li> |
| |
| |
| <li> |
| |
| <a class="" href="/docs/en/5.1.1/guide/hybrid/webviews/index.html"> |
| Embedding WebViews |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| </li> |
| |
| |
| <li> |
| |
| <a class="" href="/docs/en/5.1.1/guide/hybrid/plugins/index.html"> |
| Plugin Development Guide |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| </li> |
| |
| |
| <li> |
| |
| <a class="" href="/docs/en/5.1.1/guide/appdev/privacy/index.html"> |
| Privacy Guide |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| </li> |
| |
| |
| <li> |
| |
| <a class="" href="/docs/en/5.1.1/guide/appdev/security/index.html"> |
| Security Guide |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| </li> |
| |
| |
| <li> |
| |
| <a class="" href="/docs/en/5.1.1/platform_plugin_versioning_ref/index.html"> |
| Platforms and Plugins Version Management |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| </li> |
| |
| |
| <li> |
| |
| <a class="" href="/docs/en/5.1.1/guide/appdev/whitelist/index.html"> |
| Whitelist Guide |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| </li> |
| |
| |
| <li> |
| |
| <a class="" href="/docs/en/5.1.1/cordova/storage/storage.html"> |
| Storage |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| </li> |
| |
| |
| <li> |
| |
| <a class="" href="/docs/en/5.1.1/guide/appdev/hooks/index.html"> |
| Hooks Guide |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| </li> |
| |
| |
| <li> |
| |
| <a class="" href="/docs/en/5.1.1/guide/next/index.html"> |
| Next Steps |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| </li> |
| |
| |
| <li> |
| |
| <a class="" href="/docs/en/5.1.1/cordova/events/events.html"> |
| Events |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| </li> |
| |
| |
| <li> |
| |
| <a class="" href="/docs/en/5.1.1/cordova/plugins/pluginapis.html"> |
| Plugin APIs |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| </li> |
| |
| </ul> |
| |
| </div> |
| |
| <!-- Page content --> |
| <div class="page-content-container"> |
| <div class="page-content"> |
| <div class="content-header"> |
| |
| <!-- ToC Dropdown (for XS and SM sizes only) --> |
| <div class="toc-dropdown dropdown visible-xs-block visible-sm-block"> |
| <button class="btn btn-default dropdown-toggle" type="button" id="tocDropdown" data-toggle="dropdown" aria-haspopup="true" aria-expanded="true"> |
| Table of Contents |
| <span class="caret"></span> |
| </button> |
| <ul class="dropdown-menu"> |
| |
| |
| <li> |
| <a class="" href="/docs/en/5.1.1/"> |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| <li> |
| <a class="" href="/docs/en/5.1.1/guide/overview/index.html"> |
| Overview |
| </a> |
| </li> |
| |
| |
| |
| |
| <li> |
| <a class="" href="/docs/en/5.1.1/guide/support/index.html"> |
| Platform Support |
| </a> |
| </li> |
| |
| |
| |
| |
| <li> |
| <a class="" href="/docs/en/5.1.1/guide/cli/index.html"> |
| The Command-Line Interface |
| </a> |
| </li> |
| |
| |
| |
| |
| <li> |
| <a class="" href="/docs/en/5.1.1/guide/platforms/index.html"> |
| Platform Guides |
| </a> |
| </li> |
| |
| |
| |
| |
| <li> |
| <a class="" href="/docs/en/5.1.1/plugin_ref/plugman.html"> |
| Using Plugman to Manage Plugins |
| </a> |
| </li> |
| |
| |
| |
| |
| <li> |
| <a class="" href="/docs/en/5.1.1/config_ref/index.html"> |
| The config.xml File |
| </a> |
| </li> |
| |
| |
| |
| |
| <li> |
| <a class="" href="/docs/en/5.1.1/config_ref/images.html"> |
| Icons and Splash Screens |
| </a> |
| </li> |
| |
| |
| |
| |
| <li> |
| <a class="" href="/docs/en/5.1.1/guide/hybrid/webviews/index.html"> |
| Embedding WebViews |
| </a> |
| </li> |
| |
| |
| |
| |
| <li> |
| <a class="" href="/docs/en/5.1.1/guide/hybrid/plugins/index.html"> |
| Plugin Development Guide |
| </a> |
| </li> |
| |
| |
| |
| |
| <li> |
| <a class="" href="/docs/en/5.1.1/guide/appdev/privacy/index.html"> |
| Privacy Guide |
| </a> |
| </li> |
| |
| |
| |
| |
| <li> |
| <a class="" href="/docs/en/5.1.1/guide/appdev/security/index.html"> |
| Security Guide |
| </a> |
| </li> |
| |
| |
| |
| |
| <li> |
| <a class="" href="/docs/en/5.1.1/platform_plugin_versioning_ref/index.html"> |
| Platforms and Plugins Version Management |
| </a> |
| </li> |
| |
| |
| |
| |
| <li> |
| <a class="" href="/docs/en/5.1.1/guide/appdev/whitelist/index.html"> |
| Whitelist Guide |
| </a> |
| </li> |
| |
| |
| |
| |
| <li> |
| <a class="" href="/docs/en/5.1.1/cordova/storage/storage.html"> |
| Storage |
| </a> |
| </li> |
| |
| |
| |
| |
| <li> |
| <a class="" href="/docs/en/5.1.1/guide/appdev/hooks/index.html"> |
| Hooks Guide |
| </a> |
| </li> |
| |
| |
| |
| |
| <li> |
| <a class="" href="/docs/en/5.1.1/guide/next/index.html"> |
| Next Steps |
| </a> |
| </li> |
| |
| |
| |
| |
| <li> |
| <a class="" href="/docs/en/5.1.1/cordova/events/events.html"> |
| Events |
| </a> |
| </li> |
| |
| |
| |
| |
| <li> |
| <a class="" href="/docs/en/5.1.1/cordova/plugins/pluginapis.html"> |
| Plugin APIs |
| </a> |
| </li> |
| |
| |
| |
| |
| </ul> |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a class="edit" href="https://github.com/apache/cordova-docs/tree/master/www/docs/en/5.1.1/plugin_ref/spec.md"><span class="glyphicon glyphicon-pencil" aria-hidden="true"></span> </a> |
| |
| |
| |
| <!-- Version dropdown --> |
| <div class="dropdown"> |
| <button class="btn btn-default dropdown-toggle" type="button" id="versionDropdown" data-toggle="dropdown" aria-haspopup="true" aria-expanded="true"> |
| 5.1.1 |
| |
| <span class="caret"></span> |
| </button> |
| <ul class="dropdown-menu" aria-labelledby="versionDropdown"> |
| |
| <!-- List versions available in this language --> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/dev/" class="missing-page"> |
| |
| |
| dev |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/latest/" class="missing-page"> |
| |
| |
| 12.x |
| |
| (Latest) |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/11.x/" class="missing-page"> |
| |
| |
| 11.x |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/10.x/" class="missing-page"> |
| |
| |
| 10.x |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/9.x/" class="missing-page"> |
| |
| |
| 9.x |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/8.x/" class="missing-page"> |
| |
| |
| 8.x |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/7.x/" class="missing-page"> |
| |
| |
| 7.x |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/6.x/" class="missing-page"> |
| |
| |
| 6.x |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/5.4.0/" class="missing-page"> |
| |
| |
| 5.4.0 |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/5.1.1/" class="missing-page"> |
| |
| <span class="selected"> |
| |
| 5.1.1 |
| |
| |
| </span> |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/5.0.0/" class="missing-page"> |
| |
| |
| 5.0.0 |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/4.0.0/" class="missing-page"> |
| |
| |
| 4.0.0 |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/3.6.0/" class="missing-page"> |
| |
| |
| 3.6.0 |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/3.5.0/" class="missing-page"> |
| |
| |
| 3.5.0 |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/3.4.0/" class="missing-page"> |
| |
| |
| 3.4.0 |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/3.3.0/" class="missing-page"> |
| |
| |
| 3.3.0 |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/3.2.0/" class="missing-page"> |
| |
| |
| 3.2.0 |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/3.1.0/" class="missing-page"> |
| |
| |
| 3.1.0 |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/3.0.0/" class="missing-page"> |
| |
| |
| 3.0.0 |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/2.9.0/" class="missing-page"> |
| |
| |
| 2.9.0 |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/2.8.0/" class="missing-page"> |
| |
| |
| 2.8.0 |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/2.7.0/" class="missing-page"> |
| |
| |
| 2.7.0 |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/2.6.0/" class="missing-page"> |
| |
| |
| 2.6.0 |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/2.5.0/" class="missing-page"> |
| |
| |
| 2.5.0 |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/2.4.0/" class="missing-page"> |
| |
| |
| 2.4.0 |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/2.3.0/" class="missing-page"> |
| |
| |
| 2.3.0 |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/2.2.0/" class="missing-page"> |
| |
| |
| 2.2.0 |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/2.1.0/" class="missing-page"> |
| |
| |
| 2.1.0 |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/2.0.0/" class="missing-page"> |
| |
| |
| 2.0.0 |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/1.9.0/" class="missing-page"> |
| |
| |
| 1.9.0 |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/1.8.1/" class="missing-page"> |
| |
| |
| 1.8.1 |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/1.8.0/" class="missing-page"> |
| |
| |
| 1.8.0 |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/1.7.0/" class="missing-page"> |
| |
| |
| 1.7.0 |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/1.6.1/" class="missing-page"> |
| |
| |
| 1.6.1 |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/1.6.0/" class="missing-page"> |
| |
| |
| 1.6.0 |
| |
| |
| |
| </a> |
| </li> |
| |
| <li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="/docs/en/1.5.0/" class="missing-page"> |
| |
| |
| 1.5.0 |
| |
| |
| |
| </a> |
| </li> |
| |
| </ul> |
| </div> |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| |
| <!-- Show warnings for special versions --> |
| <!-- dev warning --> |
| |
| |
| <!-- outdated warning --> |
| |
| <div class="alert docs-alert alert-danger" role="alert"> |
| <button type="button" class="close" data-dismiss="alert" aria-label="Close"> |
| <span aria-hidden="true">×</span> |
| </button> |
| This version of the documentation is outdated! |
| <a href="/docs/en/latest/"> |
| Click here for the latest released version. |
| </a> |
| </div> |
| |
| |
| <!-- plugin version warning --> |
| |
| |
| <div id="page-toc-source"> |
| <h1>Plugin Specification</h1> |
| |
| <p>The <code>plugin.xml</code> file is an XML document in the <code>plugins</code> namespace: |
| <code>http://apache.org/cordova/ns/plugins/1.0</code>. It contains a top-level |
| <code>plugin</code> element that defines the plugin, and children that define the |
| structure of the plugin.</p> |
| |
| <p>A sample plugin element:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><?xml version="1.0" encoding="UTF-8"?> |
| <plugin xmlns="http://apache.org/cordova/ns/plugins/1.0" |
| xmlns:android="http://schemas.android.com/apk/res/android" |
| id="com.alunny.foo" |
| version="1.0.2"> |
| </code></pre></div></div> |
| |
| <h2><em>plugin</em> Element</h2> |
| |
| <p>The <code>plugin</code> element is the plugin manifest's top-level element. It |
| features the following attributes:</p> |
| |
| <ul> |
| <li> |
| <p><code>xmlns</code> (required): |
| The plugin namespace, <code>http://apache.org/cordova/ns/plugins/1.0</code>. If |
| the document contains XML from other namespaces, such as tags to be |
| added to the <code>AndroidManifest.xml</code> file, those namespaces should |
| also be included in the top-level element.</p> |
| </li> |
| <li> |
| <p><code>id</code> (required): |
| A reverse-domain style identifier for the plugin, such as |
| <code>com.alunny.foo</code></p> |
| </li> |
| <li> |
| <p><code>version</code> (required): |
| A version number for the plugin, that matches the following |
| major-minor-patch style regular expression:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code> ^\d+[.]\d+[.]\d+$ |
| </code></pre></div> </div> |
| </li> |
| </ul> |
| |
| <h2><em>engines</em> and <em>engine</em> Elements</h2> |
| |
| <p>The child elements of the <code><engines></code> element specify versions of |
| Apache Cordova-based frameworks that this plugin supports. An example:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><engines> |
| <engine name="cordova" version="1.7.0" /> |
| <engine name="cordova" version="1.8.1" /> |
| <engine name="worklight" version="1.0.0" platform="android" scriptSrc="worklight_version"/> |
| </engines> |
| </code></pre></div></div> |
| |
| <p>Similar to the <code><plugin></code> element's <code>version</code> attribute, the specified |
| version string should match a major-minor-patch string conforming to |
| the regular expression:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code> ^\d+[.]\d+[.]\d+$ |
| </code></pre></div></div> |
| |
| <p>Engine elements may also specify fuzzy matches to avoid repetition, |
| and to reduce maintenance when the underlying platform is updated. |
| Tools should support a minimum of <code>></code>, <code>>=</code>, <code><</code> and <code><=</code>, for |
| example:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><engines> |
| <engine name="cordova" version=">=1.7.0" /> |
| <engine name="cordova" version="<1.8.1" /> |
| </engines> |
| </code></pre></div></div> |
| |
| <p>The <code><engine></code> tags also has default support for all of the main platforms Cordova exists on. |
| Specifying the <code>cordova</code> engine tag means that all versions of Cordova on any platform must |
| satisfy the engine version attribute. You may also list specific platforms and their versions |
| in order to override the catch-all <code>cordova</code> engine:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><engines> |
| <engine name="cordova" version=">=1.7.0" /> |
| <engine name="cordova-android" version=">=1.8.0" /> |
| <engine name="cordova-ios" version=">=1.7.1" /> |
| </engines> |
| </code></pre></div></div> |
| |
| <p>Here's a list of the default engines that the '<engine>' tag supports:</engine></p> |
| <ul> |
| <li>'cordova'</li> |
| <li>'cordova-plugman'</li> |
| <li>'cordova-amazon-fireos'</li> |
| <li>'cordova-android'</li> |
| <li>'cordova-ios'</li> |
| <li>'cordova-blackberry10'</li> |
| <li>'cordova-wp8'</li> |
| <li>'cordova-windows8'</li> |
| <li>'android-sdk' // returns the highest Android api level installed</li> |
| <li>'apple-xcode' // returns the xcode version</li> |
| <li>'apple-ios' // returns the highest iOS version installed</li> |
| <li>'apple-osx' // returns the OSX version</li> |
| <li>'blackberry-ndk' // returns the native blackberry SDK version</li> |
| </ul> |
| |
| <p>Specifying custom Apache Cordova-based frameworks should be listed under the engine tag like so:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><engines> |
| <engine name="my_custom_framework" version="1.0.0" platform="android" scriptSrc="path_to_my_custom_framework_version"/> |
| <engine name="another_framework" version=">0.2.0" platform="ios|android" scriptSrc="path_to_another_framework_version"/> |
| <engine name="even_more_framework" version=">=2.2.0" platform="*" scriptSrc="path_to_even_more_framework_version"/> |
| </engines> |
| </code></pre></div></div> |
| |
| <p>A custom Apache Cordova-based framework requires that an engine element includes the following attributes: |
| <code>name</code>, <code>version</code>, <code>scriptSrc</code>, and <code>platform</code>.</p> |
| |
| <ul> |
| <li> |
| <p><code>name</code> (required): A human-readable name for your custom framework.</p> |
| </li> |
| <li> |
| <p><code>version</code> (required): The version that your framework must have in order to install.</p> |
| </li> |
| <li> |
| <p><code>scriptSrc</code> (required): The script file that tells plugman what version of the custom framework is. |
| Ideally, this file should be within the top level directory of your plugin directory.</p> |
| </li> |
| <li> |
| <p><code>platform</code> (required): Which platforms that your framework supports. You may use the wildcard <code>*</code> |
| to say supported for all platforms, specify multiple with a pipe character like <code>android|ios|blackberry10</code> |
| or just a single platform like <code>android</code>.</p> |
| </li> |
| </ul> |
| |
| <p>plugman aborts with a non-zero code for any plugin whose target |
| project does not meet the engine's constraints.</p> |
| |
| <p>If no <code><engine></code> tags are specified, plugman attempts to install into |
| the specified cordova project directory blindly.</p> |
| |
| <h2><em>name</em> Element</h2> |
| |
| <p>A human-readable name for the plugin, whose text content contains the |
| name of the plugin. For example:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><name>Foo</name> |
| </code></pre></div></div> |
| |
| <p>This element does not (yet) handle localization.</p> |
| |
| <h2><em>description</em> Element</h2> |
| |
| <p>A human-readable description for the plugin. The text content of the element contains |
| the description of the plugin. An example:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><description>Foo plugin description</description> |
| </code></pre></div></div> |
| |
| <p>This element does not (yet) handle localization.</p> |
| |
| <h2><em>author</em> Element</h2> |
| |
| <p>Plugin author name. The text content of the element contains |
| the name of the plugin author. An example:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><author>Foo plugin description</author> |
| </code></pre></div></div> |
| |
| <h2><em>keywords</em> Element</h2> |
| |
| <p>Plugin keywords. The text content of the element contains comma separated keywords to describe the plugin. An example:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><keywords>foo,bar</keywords> |
| </code></pre></div></div> |
| |
| <h2><em>license</em> Element</h2> |
| |
| <p>Plugin license. The text content of the element contains the plugin license. An example:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><license>Apache 2.0 License</license> |
| </code></pre></div></div> |
| |
| <h2><em>asset</em> Element</h2> |
| |
| <p>One or more elements listing the files or directories to be copied |
| into a Cordova app's <code>www</code> directory. Examples:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><!-- a single file, to be copied in the root directory --> |
| <asset src="www/foo.js" target="foo.js" /> |
| <!-- a directory, also to be copied in the root directory --> |
| <asset src="www/foo" target="foo" /> |
| </code></pre></div></div> |
| |
| <p>All <code><asset></code> tags require both <code>src</code> and <code>target</code> attributes. |
| Web-only plugins contains mostly <code><asset></code> elements. Any <code><asset></code> |
| elements that are nested within <code><platform></code> elements specify |
| platform-specific web assets, as described below. Attributes include:</p> |
| |
| <ul> |
| <li> |
| <p><code>src</code> (required): |
| Where the file or directory is located in the plugin package, |
| relative to the <code>plugin.xml</code> document. If a file does not exist at |
| the specified <code>src</code> location, plugman stops and reverses the |
| installation process, issues a notification about the conflict, and |
| exits with a non-zero code.</p> |
| </li> |
| <li> |
| <p><code>target</code> (required):</p> |
| |
| <p>Where the file or directory should be located in the Cordova app, |
| relative to the <code>www</code> directory. |
| Assets can be targeted to subdirectories, for example:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code> <asset src="www/new-foo.js" target="js/experimental/foo.js" /> |
| </code></pre></div> </div> |
| |
| <p>creates the <code>js/experimental</code> directory within the <code>www</code> directory, |
| unless already present, then copies the <code>new-foo.js</code> file and |
| renames it <code>foo.js</code>. If a file already exists at the target |
| location, plugman stops and reverses the installation process, |
| issues a notification about the conflict, and exits with a non-zero |
| code.</p> |
| </li> |
| </ul> |
| |
| <h2><em>js-module</em> Element</h2> |
| |
| <p>Most plugins include one or more JavaScript files. Each <code><js-module></code> |
| tag corresponds to a JavaScript file, and prevents the plugin's users |
| from having to add a <code><script></code> tag for each file. While <code><asset></code> |
| tags simply copy a file from the plugin subdirectory into <code>www</code>, |
| <code><js-module></code> tags are much more sophisticated. They look like this:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><js-module src="socket.js" name="Socket"> |
| <clobbers target="chrome.socket" /> |
| </js-module> |
| </code></pre></div></div> |
| |
| <p>When installing a plugin with the example above, <code>socket.js</code> is copied |
| to <code>www/plugins/my.plugin.id/socket.js</code>, and added as an entry to |
| <code>www/cordova_plugins.js</code>. At load time, code in <code>cordova.js</code> uses XHR |
| to read each file and inject a <code><script></code> tag into HTML. It adds a |
| mapping to clobber or merge as appropriate, as described below.</p> |
| |
| <p><em>Do not</em> wrap the file with <code>cordova.define</code>, as it is added |
| automatically. The module is wrapped in a closure, with <code>module</code>, |
| <code>exports</code>, and <code>require</code> in scope, as is normal for AMD modules.</p> |
| |
| <p>Details for the <code><js-module></code> tag:</p> |
| |
| <ul> |
| <li> |
| <p>The <code>src</code> references a file in the plugin directory relative to the |
| <code>plugin.xml</code> file.</p> |
| </li> |
| <li> |
| <p>The <code>name</code> provides the last part of the module name. It can |
| generally be whatever you like, and it only matters if you want to |
| use <code>cordova.require</code> to import other parts of your plugins in your |
| JavaScript code. The module name for a <code><js-module></code> is your |
| plugin's <code>id</code> followed by the value of <code>name</code>. For the example |
| above, with an <code>id</code> of <code>chrome.socket</code>, the module name is |
| <code>chrome.socket.Socket</code>.</p> |
| </li> |
| <li> |
| <p>Three tags are allowed within <code><js-module></code>:</p> |
| |
| <ul> |
| <li> |
| <p><code><clobbers target="some.value"/></code> indicates that the |
| <code>module.exports</code> is inserted into the <code>window</code> object as |
| <code>window.some.value</code>. You can have as many <code><clobbers></code> as you |
| like. Any object not available on <code>window</code> is created.</p> |
| </li> |
| <li> |
| <p><code><merges target="some.value"/></code> indicates that the module |
| should be merged with any existing value at <code>window.some.value</code>. |
| If any key already exists, the module's version overrides the |
| original. You can have as many <code><merges></code> as you like. Any |
| object not available on <code>window</code> is created.</p> |
| </li> |
| <li> |
| <p><code><runs/></code> means that your code should be specified with |
| <code>cordova.require</code>, but not installed on the <code>window</code> |
| object. This is useful when initializing the module, attaching |
| event handlers or otherwise. You can only have up to one |
| <code><runs/></code> tag. Note that including a <code><runs/></code> with |
| <code><clobbers/></code> or <code><merges/></code> is redundant, since they also |
| <code>cordova.require</code> your module.</p> |
| </li> |
| <li> |
| <p>An empty <code><js-module></code> still loads and can be accessed in other |
| modules via <code>cordova.require</code>.</p> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| |
| <p>If <code>src</code> does not resolve to an existing file, plugman stops and |
| reverses the installation, issues a notification of the problem, and |
| exits with a non-zero code.</p> |
| |
| <p>Nesting <code><js-module></code> elements within <code><platform></code> declares |
| platform-specific JavaScript module bindings.</p> |
| |
| <h2><em>dependency</em> Element</h2> |
| |
| <p>The <code><dependency></code> tag allows you to specify other plugins on which the |
| current plugin depends. While future versions will access them from |
| plugin repositories, in the short term plugins are directly referenced |
| as URLs by <code><dependency></code> tags. They are formatted as follows:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><dependency id="com.plugin.id" url="https://github.com/myuser/someplugin" commit="428931ada3891801" subdir="some/path/here" /> |
| </code></pre></div></div> |
| |
| <ul> |
| <li> |
| <p><code>id</code>: provides the ID of the plugin. It should be globally unique, |
| and expressed in reverse-domain style. While neither of these |
| restrictions is currently enforced, they may be in the future.</p> |
| </li> |
| <li> |
| <p><code>url</code>: A URL for the plugin. This should reference a git repository, |
| which plugman attempts to clone.</p> |
| </li> |
| <li> |
| <p><code>commit</code>: This is any git reference understood by <code>git checkout</code>: a |
| branch or tag name (e.g., <code>master</code>, <code>0.3.1</code>), or a commit hash (e.g., |
| <code>975ddb228af811dd8bb37ed1dfd092a3d05295f9</code>).</p> |
| </li> |
| <li> |
| <p><code>subdir</code>: Specifies that the targeted plugin dependency exists as a |
| subdirectory of the git repository. This is helpful because it |
| allows the repository to contain several related plugins, each |
| specified individually.</p> |
| </li> |
| </ul> |
| |
| <p>In the future, version constraints will be introduced, and a plugin |
| repository will exist to support fetching by name instead of explicit |
| URLs.</p> |
| |
| <h3>Relative Dependency Paths</h3> |
| |
| <p>If you set the <code>url</code> of a <code><dependency></code> tag to <code>"."</code> and provide a |
| <code>subdir</code>, the dependent plugin is installed from the same local or |
| remote git repository as the parent plugin that specifies the |
| <code><dependency></code> tag.</p> |
| |
| <p>Note that the <code>subdir</code> always specifies a path relative to the <em>root</em> |
| of the git repository, not the parent plugin. This is true even if you |
| installed the plugin with a local path directly to it. Plugman finds |
| the root of the git repository and then finds the other plugin from |
| there.</p> |
| |
| <h2><em>platform</em> Element</h2> |
| |
| <p>The <code><platform></code> tag identifies platforms that have associated native |
| code or require modifications to their configuration files. Tools |
| using this specification can identify supported platforms and install |
| the code into Cordova projects.</p> |
| |
| <p>Plugins without <code><platform></code> tags are assumed to be JavaScript-only, |
| and therefore installable on any and all platforms.</p> |
| |
| <p>A sample platform tag:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><platform name="android"> |
| <!-- android-specific elements --> |
| </platform> |
| <platform name="ios"> |
| <!-- ios-specific elements --> |
| </platform> |
| </code></pre></div></div> |
| |
| <p>The required <code>name</code> attribute identifies a platform as supported, |
| associating the element's children with that platform.</p> |
| |
| <p>Platform names should be lowercase. Platform names, as arbitrarily |
| chosen, are listed:</p> |
| |
| <ul> |
| <li>amazon-fireos</li> |
| <li>android</li> |
| <li>blackberry10</li> |
| <li>ios</li> |
| <li>wp8</li> |
| <li>windows8</li> |
| </ul> |
| |
| <h2><em>source-file</em> Element</h2> |
| |
| <p>The <code><source-file></code> element identifies executable source code that |
| should be installed into a project. Examples:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><!-- android --> |
| <source-file src="src/android/Foo.java" |
| target-dir="src/com/alunny/foo" /> |
| <!-- ios --> |
| <source-file src="src/ios/CDVFoo.m" /> |
| <source-file src="src/ios/someLib.a" framework="true" /> |
| <source-file src="src/ios/someLib.a" compiler-flags="-fno-objc-arc" /> |
| </code></pre></div></div> |
| |
| <p>It supports the following attributes:</p> |
| |
| <ul> |
| <li> |
| <p><code>src</code> (required): |
| Location of the file relative to <code>plugin.xml</code>. If the <code>src</code> file |
| can't be found, plugman stops and reverses the installation, issues |
| a notification about the problem, and exits with a non-zero code.</p> |
| </li> |
| <li> |
| <p><code>target-dir</code>: |
| A directory into which the files should be copied, relative to the |
| root of the Cordova project. In practice, this is most important |
| for Java-based platforms, where a file in the <code>com.alunny.foo</code> |
| package must be located within the <code>com/alunny/foo</code> directory. For |
| platforms where the source directory is not important, this |
| attribute should be omitted.</p> |
| |
| <p>As with assets, if the <code>target</code> of a <code>source-file</code> would overwrite |
| an existing file, plugman stops and reverses the installation, |
| issues a notification about the problem, and exits with a non-zero |
| code.</p> |
| </li> |
| <li> |
| <p><code>framework</code> (iOS only): |
| If set to <code>true</code>, also adds the specified file as a framework to the |
| project.</p> |
| </li> |
| <li> |
| <p><code>compiler-flags</code> (iOS only): |
| If set, assigns the specified compiler flags for the particular |
| source file.</p> |
| </li> |
| </ul> |
| |
| <h2><em>config-file</em> Element</h2> |
| |
| <p>Identifies an XML-based configuration file to be modified, where in |
| that document the modification should take place, and what should be |
| modified.</p> |
| |
| <p>Two file types that have been tested for modification with this |
| element are <code>xml</code> and <code>plist</code> files.</p> |
| |
| <p>The <code>config-file</code> element only allows you to append new children to an |
| XML document tree. The children are XML literals to be inserted in the |
| target document.</p> |
| |
| <p>Example for XML:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><config-file target="AndroidManifest.xml" parent="/manifest/application"> |
| <activity android:name="com.foo.Foo" android:label="@string/app_name"> |
| <intent-filter> |
| </intent-filter> |
| </activity> |
| </config-file> |
| </code></pre></div></div> |
| |
| <p>Example for <code>plist</code>:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><config-file target="*-Info.plist" parent="CFBundleURLTypes"> |
| <array> |
| <dict> |
| <key>PackageName</key> |
| <string>$PACKAGE_NAME</string> |
| </dict> |
| </array> |
| </config-file> |
| </code></pre></div></div> |
| |
| <p>It supports the following attributes:</p> |
| |
| <ul> |
| <li> |
| <p><code>target</code>:</p> |
| |
| <p>The file to be modified, and the path relative to the root of the |
| Cordova project.</p> |
| |
| <p>The target can include wildcard (<code>*</code>) elements. In this case, |
| plugman recursively searches through the project directory structure |
| and uses the first match.</p> |
| |
| <p>On iOS, the location of configuration files relative to the project |
| directory root is not known, so specifying a target of <code>config.xml</code> |
| resolves to <code>cordova-ios-project/MyAppName/config.xml</code>.</p> |
| |
| <p>If the specified file does not exist, the tool ignores the |
| configuration change and continues installation.</p> |
| </li> |
| <li> |
| <p><code>parent</code>: An XPath selector referencing the parent of the elements |
| to be added to the config file. If you use absolute selectors, you |
| can use a wildcard (<code>*</code>) to specify the root element, |
| e.g., <code>/*/plugins</code>.</p> |
| |
| <p>For <code>plist</code> files, the <code>parent</code> determines under what parent key the |
| specified XML should be inserted.</p> |
| |
| <p>If the selector does not resolve to a child of the specified |
| document, the tool stops and reverses the installation process, |
| issues a warning, and exits with a non-zero code.</p> |
| </li> |
| <li> |
| <p><code>after</code>: A prioritized list of accepted siblings after which to add the XML snippet. Useful for specifying changes in files which require strict ordering of XML elements like <a href="http://msdn.microsoft.com/en-us/library/windowsphone/develop/ff769509%28v=vs.105%29.aspx#BKMK_EXTENSIONSelement">http://msdn.microsoft.com/en-us/library/windowsphone/develop/ff769509%28v=vs.105%29.aspx#BKMK_EXTENSIONSelement</a></p> |
| </li> |
| </ul> |
| |
| <p>The Windows platform supports two additional attributes (both optional) when affecting the meta-name <code>package.appxmanifest</code>:</p> |
| |
| <p>The <code>device-target</code> attribute indicates that the should only be included when building for the specified target device |
| type. Supported values are <code>win</code>, <code>phone</code>, or <code>all</code>.</p> |
| |
| <p>The <code>versions</code> attribute indicates that app manifests for specific Windows versions should only be altered for versions that match the |
| specified version string. Value can be any valid node semantic version range string.</p> |
| |
| <p>Examples of using these Windows specific attributes:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><config-file target="package.appxmanifest" parent="/Package/Capabilities" versions="<8.1.0"> |
| <Capability Name="picturesLibrary" /> |
| <DeviceCapability Name="webcam" /> |
| </config-file> |
| <config-file target="package.appxmanifest" parent="/Package/Capabilities" versions=">=8.1.0" device-target="phone"> |
| <DeviceCapability Name="webcam" /> |
| </config-file> |
| </code></pre></div></div> |
| |
| <p>The above example will set pre-8.1 platforms (Windows 8, specifically) to require the <code>webcam</code> device capability and the <code>picturesLibrary</code> general capability, and apply the <code>webcam</code> device capability only to Windows 8.1 projects that build for Windows Phone. Windows desktop 8.1 systems are unmodified.</p> |
| |
| <h2><em>plugins-plist</em> Element</h2> |
| |
| <p>This is <em>outdated</em> as it only applies to cordova-ios 2.2.0 and |
| below. Use the <code><config-file></code> tag for newer versions of Cordova.</p> |
| |
| <p>Example:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><config-file target="config.xml" parent="/widget/plugins"> |
| <feature name="ChildBrowser"> |
| <param name="ios-package" value="ChildBrowserCommand"/> |
| </feature> |
| </config-file> |
| </code></pre></div></div> |
| |
| <p>Specifies a key and value to append to the correct <code>AppInfo.plist</code> |
| file in an iOS Cordova project. For example:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><plugins-plist key="Foo" string="CDVFoo" /> |
| </code></pre></div></div> |
| |
| <h2><em>resource-file</em> and <em>header-file</em> Elements</h2> |
| |
| <p>Like source files, but specifically for platforms such as iOS that |
| distinguish between source files, headers, and resources. iOS Examples:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><resource-file src="CDVFoo.bundle" /> |
| <resource-file src="CDVFooViewController.xib" /> |
| <header-file src="CDVFoo.h" /> |
| </code></pre></div></div> |
| |
| <p>Android example:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><resource-file src="FooPluginStrings.xml" target="res/values/FooPluginStrings.xml" /> |
| </code></pre></div></div> |
| |
| <h2><em>lib-file</em> Element</h2> |
| |
| <p>Like source, resource, and header files, but specifically for |
| platforms such as BlackBerry 10 that use user-generated libraries. |
| Examples:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><lib-file src="src/BlackBerry10/native/device/libfoo.so" arch="device" /> |
| <lib-file src="src/BlackBerry10/native/simulator/libfoo.so" arch="simulator" /> |
| </code></pre></div></div> |
| |
| <p>Supported attributes:</p> |
| |
| <ul> |
| <li> |
| <p><code>src</code> (required): |
| The location of the file relative to <code>plugin.xml</code>. |
| If <code>src</code> can't be found, plugman stops and reverses the |
| installation, issues a warning about the problem, and exits with a |
| non-zero code.</p> |
| </li> |
| <li> |
| <p><code>arch</code>: The architecture for which the <code>.so</code> file has been built, |
| either <code>device</code> or <code>simulator</code>.</p> |
| </li> |
| </ul> |
| |
| <p>For the Windows platform, the <code><lib-file></code> element allows the inclusion of an <code><SDKReference></code> in the generated Windows |
| project files.</p> |
| |
| <p>Supported attributes:</p> |
| |
| <ul> |
| <li> |
| <p><code>src</code> (required): |
| The name of the SDK to include (which will be used as value of the <code>Include</code> attribute of the generated |
| <code><SDKReference></code> element).</p> |
| </li> |
| <li> |
| <p><code>arch</code>: Indicates that the <code><SDKReference></code> should only be included when building for the specified architecture. |
| Supported values are <code>x86</code>, <code>x64</code> or <code>ARM</code>.</p> |
| </li> |
| <li> |
| <p><code>device-target</code>: Indicates that the <code><SDKReference></code> should only be included when building for the specified target device |
| type. Supported values are <code>win</code> (or <code>windows</code>), <code>phone</code> or <code>all</code>.</p> |
| </li> |
| <li> |
| <p><code>versions</code>: Indicates that the <code><SDKReference></code> should only be included when building for versions that match the specified version |
| string. Value can be any valid node semantic version range string.</p> |
| </li> |
| </ul> |
| |
| <p>Examples:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><lib-file src="Microsoft.WinJS.2.0, Version=1.0" arch="x86" /> |
| <lib-file src="Microsoft.WinJS.2.0, Version=1.0" versions=">=8.1" /> |
| <lib-file src="Microsoft.WinJS.2.0, Version=1.0" target="phone" /> |
| <lib-file src="Microsoft.WinJS.2.0, Version=1.0" target="win" versions="8.0" arch="x86" /> |
| </code></pre></div></div> |
| |
| <h2><em>framework</em> Element</h2> |
| |
| <p>Identifies a framework (usually part of the OS/platform) on which the plugin depends.</p> |
| |
| <p>The optional <code>custom</code> attribute is a boolean indicating whether the framework is one that is included as part of your |
| plugin files (thus it is not a system framework).</p> |
| |
| <h3><em>framework</em> for iOS</h3> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><framework src="libsqlite3.dylib" /> |
| <framework src="social.framework" weak="true" /> |
| <framework src="relative/path/to/my.framework" custom="true" /> |
| </code></pre></div></div> |
| |
| <p>The optional <code>weak</code> attribute is a boolean indicating whether the |
| framework should be weakly linked. The default is <code>false</code>.</p> |
| |
| <h3><em>framework</em> for Android</h3> |
| |
| <p>On Android (as of cordova-android@4.0.0), <em>framework</em> tags are used to include Maven dependencies, or to include bundled library projects.</p> |
| |
| <p>Examples:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><!-- Depend on latest version of GCM from play services --> |
| <framework src="com.google.android.gms:play-services-gcm:+" /> |
| <!-- Depend on v21 of appcompat-v7 support library --> |
| <framework src="com.android.support:appcompat-v7:21+" /> |
| <!-- Depend on library project included in plugin --> |
| <framework src="relative/path/FeedbackLib" custom="true" /> |
| </code></pre></div></div> |
| |
| <p><em>framework</em> can also be used to have custom .gradle files sub-included into the main project's .gradle file:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><framework src="relative/path/rules.gradle" custom="true" type="gradleReference" /> |
| </code></pre></div></div> |
| |
| <p>For pre-android@4.0.0 (ANT-based projects):</p> |
| |
| <p>The optional <code>type</code> attribute is a string indicating the type of framework to add. Currently only <code>projectReference</code> is |
| supported and only for Windows. Using <code>custom='true'</code> and <code>type='projectReference'</code> will add a reference to the project |
| which will be added to the compile+link steps of the cordova project. This essentially is the only way currently that a |
| 'custom' framework can target multiple architectures as they are explicitly built as a dependency by the referencing |
| cordova application.</p> |
| |
| <p>The optional <code>parent</code> sets the relative path to the directory containing the |
| sub-project to which to add the reference. The default is <code>.</code>, i.e. the |
| application project. It allows to add references between sub projects like in this example:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><framework src="extras/android/support/v7/appcompat" custom="false" parent="FeedbackLib" /> |
| </code></pre></div></div> |
| |
| <h3><em>framework</em> for Windows</h3> |
| |
| <p>The Windows platform supports three additional attributes (all optional) to refine when the framework should be included:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><framework src="path/to/project/LibProj.csproj" custom="true" type="projectReference"/> |
| </code></pre></div></div> |
| |
| <p>The <code>arch</code> attribute indicates that the framework should only be included when building for the specified architecture. |
| Supported values are <code>x86</code>, <code>x64</code> or <code>ARM</code>.</p> |
| |
| <p>The <code>device-target</code> attribute indicates that the framework should only be included when building for the specified target device |
| type. Supported values are <code>win</code> (or <code>windows</code>), <code>phone</code> or <code>all</code>.</p> |
| |
| <p>The <code>versions</code> attribute indicates that the framework should only be included when building for versions that match the |
| specified version string. Value can be any valid node semantic version range string.</p> |
| |
| <p>Examples of using these Windows specific attributes:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><framework src="src/windows/example.dll" arch="x64" /> |
| <framework src="src/windows/example.dll" versions=">=8.0" /> |
| <framework src="src/windows/example.vcxproj" type="projectReference" target="win" /> |
| <framework src="src/windows/example.vcxproj" type="projectReference" target="all" versions="8.1" arch="x86" /> |
| </code></pre></div></div> |
| |
| <h2><em>info</em> Element</h2> |
| |
| <p>Additional information provided to users. This is useful when you |
| require extra steps that can't be easily automated or are beyond |
| plugman's scope. Examples:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><info> |
| You need to install __Google Play Services__ from the `Android Extras` section using the Android SDK manager (run `android`). |
| |
| You need to add the following line to the `local.properties`: |
| |
| android.library.reference.1=PATH_TO_ANDROID_SDK/sdk/extras/google/google_play_services/libproject/google-play-services_lib |
| </info> |
| </code></pre></div></div> |
| |
| <h2><em>hook</em> Element</h2> |
| |
| <p>Represents your custom script which will be called by Cordova when |
| certain action occurs (for example, after plugin is added or platform |
| prepare logic is invoked). This is useful when you need to extend |
| default Cordova functionality. See <a href="../guide/appdev/hooks/index.html">Hooks Guide</a> for more information.</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><hook type="after_plugin_install" src="scripts/afterPluginInstall.js" /> |
| </code></pre></div></div> |
| |
| <h2>Variables</h2> |
| |
| <p>In certain cases, a plugin may need to make configuration changes |
| dependent on the target application. For example, to register for C2DM |
| on Android, an app whose package id is <code>com.alunny.message</code> would |
| require a permission such as:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><uses-permission android:name="com.alunny.message.permission.C2D_MESSAGE"/> |
| </code></pre></div></div> |
| |
| <p>In such cases where the content inserted from the <code>plugin.xml</code> file is |
| not known ahead of time, variables can be indicated by a dollar-sign |
| followed by a series of capital letters, digits, or underscores. For |
| the above example, the <code>plugin.xml</code> file would include this tag:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><uses-permission android:name="$PACKAGE_NAME.permission.C2D_MESSAGE"/> |
| </code></pre></div></div> |
| |
| <p>plugman replaces variable references with the specified value, or the |
| empty string if not found. The value of the variable reference may be |
| detected (in this case, from the <code>AndroidManifest.xml</code> file) or |
| specified by the user of the tool; the exact process is dependent on |
| the particular tool.</p> |
| |
| <p>plugman can request users to specify a plugin's required |
| variables. For example, API keys for C2M and Google Maps can be |
| specified as a command-line argument:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>plugman --platform android --project /path/to/project --plugin name|git-url|path --variable API_KEY=!@CFATGWE%^WGSFDGSDFW$%^#$%YTHGsdfhsfhyer56734 |
| </code></pre></div></div> |
| |
| <p>To make the variable mandatory, the <code><platform></code> tag needs to contain |
| a <code><preference></code> tag. For example:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><preference name="API_KEY" /> |
| </code></pre></div></div> |
| |
| <p>plugman checks that these required preferences are passed in. If not, |
| it should warn the user how to pass the variable in and exit with a |
| non-zero code.</p> |
| |
| <p>Certain variable names should be reserved, as listed below.</p> |
| |
| <h2>$PACKAGE_NAME</h2> |
| |
| <p>The reverse-domain style unique identifier for the package, |
| corresponding to the <code>CFBundleIdentifier</code> on iOS or the <code>package</code> |
| attribute of the top-level <code>manifest</code> element in an |
| <code>AndroidManifest.xml</code> file.</p> |
| |
| |
| </div> |
| </div> |
| <div class="row"> |
| <div class="blue-divider"></div> |
| <footer> |
| <div class="container-fluid"> |
| <div class="row"> |
| <div class="col-sm-9"> |
| <h1>More Resources</h1> |
| <div class="row"> |
| <div class="col-sm-4"> |
| <h2>General</h2> |
| <ul class="nav"> |
| <li> |
| <a target="_blank" href="https://projects.apache.org/project.html?cordova">Apache Project Page</a> |
| </li> |
| <li> |
| <a href="https://www.apache.org/dyn/closer.cgi/cordova">Source Distribution</a> |
| </li> |
| <li> |
| <a target="_blank" href="https://www.apache.org/licenses">License</a> |
| </li> |
| <li> |
| <a href="/artwork">Artwork</a> |
| </li> |
| </ul> |
| </div> |
| <div class="col-sm-4"> |
| <h2>Development</h2> |
| <ul class="nav"> |
| <li><a target="_blank" href="https://github.com/apache?utf8=%E2%9C%93&q=cordova-">Source Code</a></li> |
| <li><a target="_blank" href="https://github.com/apache/cordova#filing-a-bug">Issue Tracker</a></li> |
| <li><a target="_blank" href="https://stackoverflow.com/questions/tagged/cordova">Stack Overflow</a></li> |
| <li><a href="/contact">Mailing List</a></li> |
| <li><a href="/contribute/nightly_builds.html">Nightly builds</a></li> |
| </ul> |
| </div> |
| <div class="col-sm-4"> |
| <h2>Apache Software Foundation</h2> |
| <ul class="nav"> |
| <li> |
| <a target="_blank" href="https://www.apache.org/">About ASF</a> |
| </li> |
| <li> |
| <a target="_blank" href="https://www.apache.org/events/current-event">Events</a> |
| </li> |
| <li> |
| <a target="_blank" href="https://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a> |
| </li> |
| <li> |
| <a target="_blank" href="https://www.apache.org/foundation/thanks.html">Thanks</a> |
| </li> |
| <li> |
| <a target="_blank" href="https://www.apache.org/security/">Security</a> |
| </li> |
| <li> |
| <a target="_blank" href="https://privacy.apache.org/policies/privacy-policy-public.html">Privacy policy</a> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="col-sm-3"> |
| <h1>Contribute</h1> |
| <p style="padding-top:20px"><strong>Help Cordova move forward!</strong></p> |
| <p>Report bugs, improve the docs, or contribute to the code.</p> |
| <a href="/contribute" class="btn btn-lg btn-primary"> |
| Learn More |
| </a> |
| <p style="padding-top:20px"> <a href="https://twitter.com/apachecordova" class="twitter-follow-button" data-show-count="false">Follow @apachecordova</a></p> |
| </div> |
| </div> |
| <p class="copyright_text"> |
| Copyright © 2024 <a href="https://apache.org">The Apache Software Foundation</a>, Licensed under the <a target="_blank" href="https://www.apache.org/licenses/">Apache License, Version 2.0</a>.<br/> |
| Apache and the Apache feather logos are <a target="_blank" href="https://www.apache.org/foundation/marks/list/">trademarks</a> of The Apache Software Foundation. |
| <br/> |
| <p>See the <a href="/attributions/">attributions page</a> for other copyright & trademark notices.</p> |
| </p> |
| |
| </div> |
| </footer> |
| |
| </div> |
| </div> |
| </div> |
| |
| <script defer type="text/javascript" src="/static/js/lib/toc.min.js"></script> |
| <script defer type="text/javascript" src="/static/js/docs.js"></script> |
| |
| <script defer type="text/javascript" src="/static/js/index.js"></script> |
| <script defer type="text/javascript" src="/static/js/twitter.js"></script> |
| </body> |
| </html> |