Core API Audit

Good software, like a garden, needs maintenance. The Cordova Core API has a few weeds that need pulling!

Accelerometer

• deprecated for http://dev.w3.org/geo/api/spec-source-orientation.html

Related issues:

• Move tests to follow orientationchange spec? https://issues.apache.org/jira/browse/CB-286

Camera

Related issues still outstanding:

• Select multiple photos from the gallery (currently one is maximum). CB-1215

Capture

• deprecated for http://www.w3.org/TR/media-capture-api/

Related issues still outstanding:

• Save to gallery after recording. CB-1371

Compass

leave be but is this not covered by deviceorientation?

Connection

• deprecated, now has 'bandwidth' attribute (way better?) http://dvcs.w3.org/hg/dap/raw-file/tip/network-api/Overview.html

Contacts

• March, 2013 Contacts Manager API http://www.w3.org/TR/2013/WD-contacts-manager-api-20130307/

• http://dvcs.w3.org/hg/dap/raw-file/tip/contacts/Overview.html

• http://www.w3.org/TR/contacts-api/

• native picker

Related issues still outstanding:

• What to do when you try to remove a contact that does not exist? CB-1143

• Adding ability to specify sorting options. CB-346

• Adding ability to delete specific contact fields. CB-144

Device

• deprecated and move this gunk to cordova global (perhaps this belongs to capabilities api?)

Mailing list decided to move to async api and unify.

Events

• deprecate battery stuff for its own plugin; leave the rest be

We may wish to consider implementing: http://www.html5rocks.com/en/tutorials/pagevisibility/intro/ for pause,resume,etc

File

normalize paths:

• Normalize return paths from capture API: CB-837

Geo

leave be

Media

requires further audit (jesse doing this) (use html5 audio and/or normalize apis / add volume event) https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html

Also relevant is CB-1681 - media.getCurrentPosition(time) and media.seekTo(time) have different units.

Network

Move from navigator.network.connection -> navigator.connection. Re-work online/offline events to fire on window and document.body as per spec.

Notification

• deprecated completely. alert/confirm in standard browser API, vibrate move to http://www.w3.org/TR/vibration/, kill beep

*Definitions*:

• - *Local Notifications*
  • - System timers/alarms that can be set up to fire [periodically] in order to poke your app with some intent - No UI requirements, I think, just a "wake from sleep" feature

  - *StatusBar Notifications*

  • - That awesome bar at the top: you can set up an icon, supply ticker-text, and/or configure drop down notification window items - Notifications may use sound/vibration/flashing lights to attract the attention of user when phone isn't in use - Users clicking notification window items will poke your app with some intent - Lots of features, vary between systems
  - *Push Notifications*
  • - External cloud services send messages to your device in response to some server action/stimulus - Once a push arrives, action should likely be some combination of Local/StatusBar Notifications, but there are system limitations

*Goals*:

• - Identify whats possible on each platform (initially android/ios) - Unify the api across platforms (as much as possible) - Use w3c spec for when possible:

  • - http://www.w3.org/TR/notifications/ - http://www.w3.org/TR/eventsource/ (or maybe not this one..)

  - Organize plugin documentation, and write up a single unified guide describing the various pieces and provide simple example - Potentially: prepare for move to core plugin, though that is not a direct goal

*Current state of the world: *(s/the world/phonegap-plugins/)

*iOS*

• - *LocalNotifications* - Needs documentation fixup

  • - 6 months since proper update, but the code looks fine (at first glance)

  - *PushNotifications* - Seems well maintained (Max Ogden +more)

  • - Inspired by UA implementation (below) but seems to have a more robust api - Note from Max: no need for explicit notification api when app is in background but do when app is in foreground
  - *UAPushNotifications*

  - Urban Airship (http://urbanairship.com/)

  • - We have no local implementation, just a TODO in repro, but found

    external: https://github.com/urbanairship/phonegap-ua-push - May be sufficient to just update our readme to point to that repo?

  - *StatusBarNotifier*

  • - Seems to just change the top text of the *webview* status bar, so

    this plugin seems to not be a StatusBar notification as I defined above, more like an app "title" bar, so plugin seems misnamed. - Depends on 3rdparty plugin: https://github.com/frankdilo/FDStatusBarNotifierView - ios6 only, apparently?

  - *NotificationEx* - Not interesting, seems to just implement features that were removed

  • from old cordova version

*Android*

• - *LocalNotification* - Docs claim similar api to iOS version, but looks different (at first

  • glance) - Can't see how to register a callback (at first glance) -- so how is this useful? Generic wakeup? - 8 months since proper update, and the code looks like it needs work
  - *Push Notification* - There is no push notification plugin in the phonegap-plugin repo..
  • - However, Max Ogden pointed me to external: GCM-Cordova (Google

    Cloud Messaging) https://github.com/marknutter/GCM-Cordova

    • - GCM replaces C2DM as supported android push messaging service
    - Api is different than ios push plugin - Also Note from Max: you have to explicitly add things to the status bar as opposed to iOS where push notifications automatically get

displayed

• in the UI [for background apps I assume]

• - *StatusBarNotification* - Braden recently worked to clean this up to use w3c spec etc

  • - I haven't scanned through it to see how much functionality it supports

*Open Questions*:

• - StatusBar Notifications: Intended for background services to notify a user to start some action (instead of just doing the action without users' explicit intent) -- so what does this mean for iOS without background services? - Are StatusBar notifications ever useful in foreground? Is that against some design principle? Leave that decision to the app developer? (fwiw: w3c spec seems to be a little vague, but no where does it say that notifications are to be used only while in background) - Push Notifications on ios: Can we intercept these when app is not in foreground, or must we just rely on default system behavior?

*Prioritizing Steps Forward:*

1. StatusBar Notifications on iOS (w3c spec)

2. Push Notifications on android
3. Push Notifications on iOS (minor fixup/polyfill hopefully)
4. Local Notifications on android

Storage

• deprecate, the w3c doesnt want to support nor should we. file api and idb should care for all these use cases

Related issues:

• Enabling Storage on cordova-mac: https://issues.apache.org/jira/browse/CB-456