Native Mobile App Development Ecosystem

estrapadetubacityMobile - Wireless

Dec 10, 2013 (3 years and 7 months ago)

100 views
















Native Mobile App Development
Ecosystem







API documentation


1.0

PURPOSE

The purpose of this document is to briefly describe to programmers the prerequi
si
tes and APIs
for writing an app

with the appMobi ecosystem
.

This

document shou
ld allow a web

designer with a working knowledge of JavaScript and HTML
to create a mobile application for a variety of platforms such as the iPhone or
an
Android

device
.



2.0 PROGRAMMING PRER
EQUISITES



You must have an appMobi.com developer login in orde
r to develop apps with the
appMobi ecosystem. If you don’t have an account

yet
, get one at
www.appmobi.com/account.aspx



In order to test your application while you are developing it, you’ll need “test con
tainer”
software running on your device. If you don’t have a test container yet, follow the
instructions at
http://flycast.assets.s3.amazonaws.com/appmobi/appmobi_tc_
install_guide.pdf


2.1 APPMOBI BEST PRA
CTICES

Every appMobi app is essentially a minature web site that is deployed directly to the target
device. That mini
-
website must

always have

the following
:




an
index.html

home page




in its file structure,
a subdire
ctory named “
_appMobi




every page on the mini
-
site must reference
“_appMobi/appmobi.js
” through a script
tag.



every page tha
t needs to access the device API
's like accelerometer etc. must contain a
handler for the "
deviceready
" event





If your app has s
ubdirectories in its file structure, you can
only use relative paths

to
refer to the files, not root relative paths.
“../xxx.html
” is good,

/mydirectory/page.html
” will not work.





Every page of your app should reference

the appMobi API at


_appMobi/appM
obi.js




The initial page of your app is always “
index.html
”. If other pages link back to it, the
name must always be lowercase only.


Be aware that the test container is not able to open new browser windows as a conventional
web browser would.

REGISTER DE
VICE READY

Before your app makes any calls to

the a
ppMobi library, the library must be ready.

Add an
event listener for the "deviceready" event to determine when the AppMobi library is loaded.




<head>

<script type="text/javascript" charset="utf
-
8"
sr
c="_appMobi/appmobi.js"></script>

<script language="javascript" type="text/javascript">



document.addEventListener("deviceready",onDeviceReady,false);










function onDeviceReady()








{








...








}



</script></head>


USE

VIEW
PORT
TO SUPPORT DIFFERENT

SCREEN RESOLUTIONS

The mobile browsers appMobi supports offer

an HTML meta tag called
viewport

that can
be

used in the <head> section of your document
.


This tag can be extremely useful if you are targeting multiple display sizes
.
I
f you are
simultaneously supporting multiple devices like an iPad and a G1 with one app, design for a
large resolution (like the iPad's) and have the viewport automatically scale the app. The
viewport will scale best to device width so your layout shoul
d handle the slight vertical
discrepancy (extra viewable area) that will display on some devices. A full discussion of
viewport is beyond the scope of this document, but we highly recommend you look it up and
understand how it works.



<meta name="viewport
" content="width=device
-
width; user
-
scalable=0;" target
-
densitydpi="device
-
dpi"/>




3.0 APPMOBI
API
LIBRARY

The AppMobi libraries are a series of javascript objects that give HTML coders the ability to
access core device functions in HTML pages they writ
e themselves to run within the AppMobi
application.


There is one library for each platform (iPhone,

iPad,

Android, etc). appMobi

also
provides

a default test library for running the pages in a w
eb browser.




When an app is built targeting a particular p
latform, the platform
-
appropriate JavaS
cr
i
pt library
is packaged into the _
appMobi

directory of the bundle
,

overwriting the test library.


Make sure
to always reference
_appMobi/appMobi.js

when creating apps.




CLASS DIAGRAM




Here is a list of the AppM
obi javascript objects available in the libraries.



OBJECTS LIST:


3.1


NAVIGATOR.ACCELEROME
TER OBJECT



The
accelerometer

object is used to track the accelerometer on the device



Success and failure callback functions need to be defined in your javascr
ipt.



Successful data is returned as an object with the attributes “.x”, “.y”, and “.z”.



Values of accelerometer samples for each axis range from
-
1 to 1.





NOTE: iPhone and Android report accelerometer readings differently. This issue is known and is
b
eing fixed. The accelerometer readings on Android will be made to comply with the current
iPhone readings.

3.1.1



GETCURRENTACCELERATI
ON
([SUCCESS FUNCTION],
[ERROR FUNCTION])

This method asynchronously acquires the current acceleration.


The function ca
llbacks for
success and failure will be called asynchronously when the data values are acquired.


The
success function is called each time data is available and the error function is called when there
is an error getting acceleration data. This function g
ets the current values only and is not
recurring.


3.1.2



WATCHACCELERATION([S
UCCESS FUNCTION],[ER
ROR

FUNCTION],[OPTIONS])


This method will asynchronously acquire the acceleration repeatedly at a given interval.


By
default that interval is every 10000

milliseconds.


The options object includes an attribute
named “.frequency” which changes that millisecond interval.



The function callbacks for success and failure will be called asynchronously when the data
values are acquired.


The success function is
called each time data is available and the error
function is called when there is an error getting acceleration data.


Successful data is returned
as an object with the attributes “.x”, “.y”, and “.z”.



Returns:


W
atch timer object to be cleared with clea
rWatch

3.1.3



CLEARWATCH([WATCH TI
MER OBJECT])

This method stops the process started by watchAcceleration().



3.1.4



CODE SAMPLE FOR ACCE
LEROMETER

https://docs.google.com/a/flytunes.fm/View?docID=d86mm4f_79fmf2k8c8&revision=_latest







3.2

NAVIGATOR.APPMOBICAC
HE OBJECT

This object is intended to provide a similar feature to browser cookies and file caches.

For
cookies, the intention that you
would use setCookie to save string data in name
-
value pairs.
Data values may be retrieved from the AppMobiCookie global array described below.

Cookies persist between application runs AND cookie values are accessible from teh
AppMobiCookie's array as soon

the deviceready event is fired.

3.3.1



ADDTOMEDIACACHE([URL
])
(COMING SOON)

This command will get a file from the Internet and cache it locally on the device.


It can then be
referenced in a special directory named
_mediacache

off the root of the bund
le.


Once this
command is run, the
mediacacheadd

event is fired.



3.3.2




REMOVEFROMMEDIACACHE
([URL])
(COMING

SOON)


This command will remove a file from the local cache on the device.


Once this command is run
the
mediacacheremove

event.

3.3.3



SETC
OOKIE([NAME],[VALUE]
)

Call this
method to store
data that will persist from session to session.


The data can be
retrieved

from the AppMobiCookies object
.

Note: This is the only way to store data in a persistent way.

3.3.4


APPMOBICOOKIES GLOBA
L ARRAY

(READ ONLY)

The
AppMobiCookies

object is a javascript object that holds all the data saved by the
appMobiCache.setCookie command (see 3.3.3).

Cookies are referenced as parameters of the object.


Each cookie object has two parameters:

name

the name of t
he cookie

value

the data stored in the cookie

For example, to reference the value of the cookie named “mytest” use this syntax:




var x = AppMobiCookies.mytest.value;


3.5

NAVIGATOR.
APPMOBIPLAYER OBJECT

COMMANDS



These functions provide

a temporar
y alternative to the HTML5 video and audio tags.
They allow
playing of remote URL
s (not Media included in the
app
bundle).

On iPhone it is
HIGHLY

recommended that you use the HTML5 tags so that local media may also be played. We are
currently testing HTML
5 tags on other platforms.



3.5.3

APPMOBIPLAYER.LOADVI
DEO([URL])

This method will load a specified video from the web or the local bundle into a native player.


Valid video formats depend on the device that AppMobi is running on.


See Supported File
T
ypes for more information.



3.5.4

APPMOBIPLAYER.LOADAU
DIO([URL])

This method will load a specified audio file from the web or the local bundle into a native
player.


Valid audio formats depend on the device that AppMobi is running on.


See Supported
Fi
le Types for more information.



3.6


NAVIGATOR.APPMOBISTA
TS OBJECT

The appMobiStats object provides access to Google analytics.

In order for statistics to work
properly, you

must have specified your analytics account ID when creating this specific
appli
cation on the appMobi website.

3.6.1

LOGEVENT([EVENTSTRIN
G])
(NOT IMPLEMENTED ON
ANDROID YET)


The function will log events to your account for application analytics. It is generally suggested
that you log event
s

with a structure similiar to the followin
g.






navigator.appMobiStats.logEvent("/[app name].[app section].[app subsection].[event]");

For example: appMobi automatically logs certain usages for you. When you call loadVideo
(3.5.3), the following event will be logged: "/appMobi.video.[podcas
t name].start". When the
video podcast has finished playing a "/appMobi.video.[podcast name].stop" will be logged. This
kind of event lets you analyze how people are using your application.

3.9


NAVIGATOR.DEVICE OBJ
ECT

The
device

object provides access t
o information about the device itself through a series of
attributes and functions.



3.9.1

PLATFORM

The platform attribute will return a text string identifying the platform or device that AppMobi
is running on.


Valid values include:

iPhone

iPod touc
h

iPad

Android


3.9.2


UUID

The uuid attribute returns the device’s unique identification id.

3.9.3

VERSION

The deviceversion attribute returns the device’s current operating system version information.

3.9.4

HASWIFICONNECTION (N
OT IMPLEMENTED

ON ANDROID YET)

This attribute will be set to true if the device has an active wifi connection and false if it does
not.



3.9.5

INITIALORIENTATION

The in
it
i
alOrientation of the device can be read from this attribute.


It will return one of the
followi
ng values.




Orientation

Value

Portrait

0


Upside Down Portrait

180

Landscape Right

90

Landscape Left

-
90

3.9.6

MANAGEPOWER([SHOULDS
TAYON],[ONLYWHENPLUG
GEDIN])


(NOT IMPLEMENTED ON
ANDROID YET)

This function controls how the device behav
es in certain power states.


It is passed two Boolean
values.


If
shouldStayOn

is false, normal power management for the device applies.


If
shouldStayOn

is true and
onlywhenPluggedIn

is true, then the device will not go to sleep if the
device is plugged
in.


If
shouldStayOn

is true and
onlyWhenPluggedIn

is false, then the device
will never go to sleep.

3.9.7

SETAUTOROTATE([SHOUL
DAUTOROTATE])


(NOT IMPLEMENTED ON
ANDROID YET)

This function will control whether the device should automatically handle rot
ation or not based
on a Boolean value.

3.9.8

SETROTATEORIENTATION
([ORIENTATION])


(NOT IMPLEMENTED ON
ANDROID YET)

This function will lock the orientation of the device to either “landscape” or “portrait”
depending on whether one of those two specific
strings are passed to the function.


If the
current orientation is not the specified orientation, the device will lock in the specified
orientation only once the device is oriented in that position.






3.10 GEOLOCATION2 OB
JECT COMMANDS

This object is al
ternative to the gelocation object in HTML5. It is guaranteed to work on
appMobi supported platforms whereas the HTML5 version is not.

3.10.1

GETCURRENTPOSITION([
SUCCESS FUNCTION],[E
RROR
FUNCTION])





This com
mand asynchronously acquires the current position.


When data is available, the
success function is called.


If there is an error getting position data, the error function is called.






3.10.2

WATCHPOSITION([SUCCE
SS FUNCTION],[ERROR
FUNCTION],[OPTIONS])


This command asynchronously acquires the position repeatedly at a given interval.


By default
that interval is every 10000 milliseconds.


The options object may include an attribute named
“.frequency” which changes that millisecond interval.


When data i
s available, the success
function is called.


If there is an error getting position data, the error function is called.



Returns:
watch timer object to be cleared in clearWatch below.

3.10.3

CLEARWATCH([WATCH TI
MER OBJECT])

This method stops the process

started by watchPosition().






3.11 NAVIGATOR.NOTIF
ICATION OBJECT COMMA
NDS

The
notification

object allows the developer to alert the user using device
-
specific capabilities.



3.11.1

BEEP([TIMES TO BEEP]
)

This method will force the device to beep.


P
assing a numeric value will cause it to beep several
times in succession.


If no parameters are passed, the number of beeps defaults to 1.


Note: on
some devices (such as Droid), the “beep” is actually a wave file being played, and the default
wave file ma
y contains three beeps.

3.11.2

VIBRATE([MILLISECOND
S])

This method will force the device to vibrate for a specified number of milliseconds.


If no
parameters are passed, the number of milliseconds
defaults to

250.



3.11.3

BLINK([COUNT],[COLOR
])
-

(ONL
Y ON DEVICES WITH NO
TIFICATION LIGHT
I.E.
NOT

IPHONE)

This method will force the device to blink its notification light a number of times specified.


The
color value is a unsigned integer from 0
-
255 (0x000000


0xffffff).



3.11.4

ALERT([MESSAGE],[TIT
LE]
,[BUTTONTEXT])

This method will display a modal alert box.


The message, alert box title, and the text on the
confirm button are all defined by the parameters passed to this method.

3.12 APPMOBI EVENTS

The AppMobi library will throw the following events

in response to certain device changes.


These events can be captured by creating event listeners for them. For example:






document.addEventListener("[eventname]",on[Event],false);










function on[Event]()








{








...








}

3.12.1

DEVICEREADY()

This event will fire once all
appMobi

library information is loaded.


Look for this event to fire
before attempting any
appMobi

commands. See example below.






document.addEventListener("deviceready",onDeviceReady,false);










function onDeviceReady()








{








...








}

3.12.2

AUDIOCOMPLETE()

This event will fire once an audio file loaded using appMobiPlayer.loadAudio (see 3.5.4) is
complete.

3.12.3

AUDIOERROR()

This event fires when there is a
n unknown error calling the appMobiPlayer.loadAudio command
(see 3.5.4).



3.12.4

AUDIOSTART()

This event is fired when an audio file is started using the appMobiPlayer.playAudio command
(see 3.5.4).

3.12.5

AUDIOBUSY()


This event will fire if the ap
pMobiPlayer.loadAudio command is called but the device is already
using loadAudio or loadVideo.



3.12.6


VIDEOCOMPLETE()

This event will fire once a video loaded using appMobiPlayer.loadVideo (see 3.5.3) is complete.



3.12.7

VIDEOERROR()

This event
is fired when a video started using appMobiPlayer.playVideo encounters an error.



3.12.8

VIDEOSTART()

This event is fired when a video is started using the appMobiPlayer.playVideo command (see
3.5.3).

3.12.9

VIDEOBUSY()


This event will fire if the a
ppMobiPlayer.loadVideo command is called but the device is already
using loadAudio or loadVideo.



3.12.10

ORIENTATIONCHANGED([
CURRENTORIENTATION])


This event will fire whenever the current orientation of the device changes.


The parameter
currentOrienta
tion

will contain one of the following values:




Orientation

Value

Portrait

0 or 180

Landscape

90 or
-
90




Here is an example of how the event handler might be used:




var orientationChanged = function(currentOrient) {



try



{




//0=portrait, 180=portrait,
-
90 = landscape, 90 = landscape



if (currentOrient == 0 || currentOrient == 180)



{ // change to portrait layout }



if (currentOrient == 90 || currentOrient ==
-
90)



{ //change to landscape layo
ut


}



}



catch(e)



{



alert("error in orientationChanged: " +


e.description);



}




};




3.12.20

MEDIACACHEREMOVE (CO
MING SOON)

This event fires once a file is removed from the local file cache using the
appMobiCache.re
moveFromMediaCache command (see 3.3.2).




3.12.21

MEDIACACHEADD (COMIN
G SOON)

This event fires once a file is added to the local file cache using the
appMobiCache.addToMediaCache command (see 3.3.1).






This event is passed an event object that inclu
des the attributes
.success

,and
.url
.


The
.success

attribute will hold a Boolean value indicating whether or not the file was successfully cached,
and the
.url

attribute will contain the url of the file that was cached using
appMobiCache.addToMediaCache.



4.0 CUSTOM


IMAGES

The underlying application images that are provided by default may be changed or “skinned”.


To do so, simply add your own versions of the following files into the _
appMobi

subdirectory of
your application bundle.



Image

filename


I
mage purpose

splash_screen.png

The image to show as the application loads
. Note: This
image will not be seen in test containers, only on
completed production builds.





5.0 SUPPORTED FILE T
YPES

This matrix shows all the supported media types for parti
cular AppMobi platforms.




IPHONE

Video Formats

H.264, MPEG
-
4 in .mp4, .m4v, .mov

Audio Formats

AAC, MP3, M4a




ANDROID (DROID)

Video Formats

WMV, MPEG4, H.263, H.264.

Audio Formats

MP3, AAC, AAC+, eAAC+, OGG