= Android Developer Guidelines =
[[TOC]]

We have 3 different Android clients written in Java:
* Japan client
* OpenGeoSMS
* OpenDataKit Collect

It is also possible now to write applications in Python, which would provide the benefit of being easier for the core developers to maintain & could potentially reuse libraries, like the DAL:
* http://code.google.com/p/python-for-android/
 * http://www.linuxjournal.com/article/10940
== Japan Client ==
Uses REST services to talk to Sahana back-end.

Available in Japanese only.

Only works with the code used for the [wiki:Deployments/Japan2011 Japan Deployment].

* Download: https://play.google.com/store/apps/details?id=org.sahanafoundation.sahana
* Code: http://bazaar.launchpad.net/~sahana-eden-jp/sahana-eden/sahanaAndroid/files
 * Function Names & Comments are in English.
 * Dev docs in Japanese: http://www.sahana.jp/development/sahana-android
  * but could be translated if there is interest.
* Japan-customised Sahana: http://bazaar.launchpad.net/~sahana-eden-jp/sahana-eden/iwate/files
* Demo: http://japan.sahanafoundation.org/android_backend/

== OpenGeoSMS ==
See [wiki:BluePrint/Messaging/OpenGeoSMS BluePrint/Messaging/OpenGeoSMS]

== ODK Collect ==
An Android XForms client

=== Download Code  ===
Install yet another SCM tool, [http://mercurial.selenic.com/downloads/ HG Mercurial]
 * defaults will suffice during setup

Get a local copy of ODK collect by checking out from Google Code.

Currently the best version to get is the [http://code.google.com/r/vinbitr-odk-collect/source/list NCSU branch]:
{{{
hg clone https://vinbitr-odk-collect.googlecode.com/hg/ vinbitr-odk-collect
}}}

This includes:
 * [http://code.google.com/p/opendatakit/source/list?repo=collect ODK Collect trunk] (as of Dec 16th)
 * [http://code.google.com/r/jaxtrx-edenodkcollect/ jaxdroid changes] essential for Sahana
 * Support for selecting Images from Media Library
 * Support for Wireless Location fix

There is another version which includes support for SMS Form Submission
 * ''link pending''

=== Build ===
 1. Install [http://java.sun.com/javase/downloads/widget/jdk6.jsp Java JDK]
 2. Install [http://developer.android.com/sdk/index.html Android SDK]
  * Download some platforms using the SDK Manager
 3. Install ANT, a cross platform Java build automation tool.
  * Download and extract Ant (1.8.1 at time of writing): http://ant.apache.org/bindownload.cgi
  * Create 'ANT_HOME' environment variable.
  * Add '%ANT_HOME%\bin' directory to 'PATH' environment variable (Windows syntax).
 4. Install [http://www.eclipse.org/downloads/ Eclipse] (tested with 3.6.1)
 5. Install [http://developer.android.com/sdk/eclipse-adt.html Android plugin]
 6. Import project into Eclipse (project name should avoid spaces)
 7. Right-click on folder & 'Build Project'

To deploy you'll need to create a self signed keystore and use the .apk packaging wizard (Right-click on project, menu Android tools, Export Signed Application Package), or use the configured Sahana Eden application downloadable from Android Market, enable accept self signed certificates to work with Sahana Eden demo site.

=== Editing Code ===
Follow the Build instructions above.

Can Run or Debug in the [http://developer.android.com/guide/developing/tools/emulator.html Emulator]

Right-click on the project & select properties | Android to check the API revision used.
 * Base ODK Trunk can run on basic Android 1.5: API 3
 * [http://developer.android.com/reference/android/telephony/SmsManager.html SMS functionality] requires Android 1.6: API 4
  * Does it fail gracefully on older API? (does compile at least still)

==== Branding ====
See [http://code.google.com/r/jaxtrx-edenodkcollect/source/detail?r=88a389069d961e777405ae34a55991e8a3d2f438 jaxdroid's branch]:
 * Edit {{{/res/values/strings.xml}}}
{{{
<string name="app_name">Sahana Eden</string>
<string name="default_server">https://demo.eden.sahanafoundation.org/eden/xforms</string>
<string name="main_menu_details">Magnifying human resources with technology</string>
<string name="main_menu_message">Sahana Eden</string>
}}}

==== Testing ====
Can use Curl to submit the XForms to the server to easily be able to step though in Eclipse without needing to have a Public IP reach your PC or use the emulator.
{{{
curl --basic -u username@domain.com:password -F xml_submission_file=@xform.txt http://127.0.0.1:8000/eden/xforms/submission
}}}

==== SMS Structure ====
XForms sent via SMS are split into Multi-Part messages with a sequence header. This header is currently a custom 5-digit unique identifier for that particular form submission.  That sequence information and unique identifier are prepended to the each part of the multi-part SMS transmission by the modified ODK Collect branch's SMS form submission code.  It will look something like this:
 * (1/3)(12345)<?xml version='1.0' ?><pr_person>...
 * (2/3)(12345)last_name>...
 * (3/3)(12345)-08</date_of_birth></pr_person>

The unique identifier -- here, 12345 -- is actually significantly more random than that.

These messages are then reassembled by the {{{tropo()}}} function in {{{controllers/msg.py}}} which calls {{{concatSMS(lastMessage, fromaddress)}}}. The reason the tropo() controller method calls concatSMS() with each new part of a multi-part message is that the messages may arrive out of order.  However, when the concatSMS() method detects that all message parts of that XForms submission have been received, it will stitch those messages together (while removing the prepend), and submit them to parserdooth() as for normal messages.
=== References ===
 * ANT samples
  * http://code.google.com/p/autoandroid/wiki/AndroidAnt
  * http://www.disgruntledrats.com/?p=27

----
BluePrintMobileClient

UserGuidelinesMobile