Phonegap SDK Introduction
Latest SDK Version: 1.0.4
Scope
If your mobile application is developed with Phonegap HTML5 cross-platform development tool, we provide a Phonegap - Cordova SDK that will allow you to use Boxcar Push Service.
Boxcar Phonegap SDK currently supports the following mobile operating systems:
- Android: Google Cloud Messaging (GCM).
- iOS: Apple Push Notification Service (APNS).
General information about API
All functions take single argument, object with properties recognized by each individual API point entry. Those functions will throw error when one or more of required parameters are missing. All result will be delivered asynchronously, by executing callback functions passed as arguments to API calls.
Arguments to all API calls can have ios: {...}
or android: {...}
sections, values
specified that way would overwrite general data from adequate platform section.
Application life cycle
Before any other operation can be performed, Boxcar API must be
initialized, this is performed by calling Boxcar.init()
.
After that application can register retrieve list of tags by using Boxcar.getTags()
or skip that step if interesting tags are already known.
To make device receive push notifications Boxcar.registerDevice()
must be called, after
that all new notifications are delivered to applications by executing onalert
callback
provided in that API call.
Starting new project using API
Make sure that on machine where build will be performed [Apache Cordova][http://cordova.apache.org/], and Android or/and IOS SDK installed.
As first step, we need to create new cordova project using:
1
cordova create /path/to/our-project our.domain.testapp1 "Test Application"
After that we need to switch to app directory:
1
cd /path/to/our-project
Next, we need to declare for what platforms we want build our application:
1
2
cordova platform add android
cordova platform add ios
Then we need to download plugin containing Boxcar SDK and it’s dependencies
1
cordova plugin add https://github.com/boxcar/boxcar-cordova-plugin
Packages for iOS platform can be only build with Xcode IDE, executing:
1
cordova prepare ios
will fill platform/ios
directory which can be opened in Xcode.
Developing for Android can also be done using IDE environment, first by preparing build directory:
1
cordova prepare android
and then creating IDE project from platfrom/android
directory, but this can also be performed from
CLI by executing
1
cordova build android
to build APK file, and calling
1
cordova run android
to install and start application on Android device.
API calls
Boxcar.init()
This method initializes internal structures, and archived notifications database
Arguments:
-
clientKey
(required) - Key used to access service, -
secret
- (required) - Secret value needed to access service -
server
- (required) - Url of push bridge server -
androidSenderID
- (required, android only) - Project number assigned to your application in Google Developers Console -
richUrlBase
- (required) - Url of server where html content of received pushes are available -
icon
- (optional, android only) - ID of android resource placed inres/drawable/
with icon that can be used to display in your notifications -
iconColor
- (optional, android only) - Color of notification icon background specified as#RRGGBB
Boxcar.registerDevice()
This method register device in push service, making it be able to receive new pushes
Arguments:
-
mode
(required) - String with “production” or “development” telling push service if production or development delivery channel should be used to register this device -
onsuccess
(required) - Callback function called when device was successfully registered in push service -
onerror
(required) - Callback function called when device registration was unsuccessful, it receives single String value is error description -
onalert
(required) - Callback function called when new push message was received, it receive object with properties initialized from notification content -
onnotificationclick
(required) - Callback function called when user clicked on notification UI generated from push. This event can be dispatched only for pushes received when app was in background, as for pushes received when app was active notification is not displayed. This function is called with single object argument with properties initialized from notification content -
tags
- List of strings with tags used to filter which notifications should be delivered -
udid
- Unique identifier of device where application is run -
alias
- Friendly name of device where application is run -
appVersion
- String with version of your application
Objects passed to onalert
and onnotificationclick
callbacks have those fields:
-
id
- unique identifier of push notification -
time
- time in milliseconds since epoch of when this message was received, this value can be converted to Date object by callingnew Date(msg.time)
-
sound
- string identifier of sound which should be played with notification -
badge
- number of unread messages on server -
body
- body of push notification -
richPush
- boolean value telling if this push includes html formated content -
url
- url to html content include in this push -
seen
- boolean value telling ifmarkAsReceived
was used for this push notification id -
extras
- object containing values defined as “Extra Variables” in push console
Boxcar.unregisterDevice()
Unregister device from push notifications
Arguments:
-
onsuccess
(required) - Callback function called when operation was successfully completed -
onerror
(required) - Callback function, it’s called when error happen, receives single String with error message
Boxcar.getTags()
This method retrieves list of tags assigned to push notification channel from server
Arguments:
-
onsuccess
(required) - Callback function called when list of tags was retrieved, it receives one argument, list of strings with all tags assigned on server -
onerror
(required) - Callback function, it’s called on error with single String with error message
Boxcar.markAsReceived()
Inform push service that push message was seen by user. This also makes message info returned
for further Boxcar.getReceivedMessages()
to have seen
attribute set to true
Arguments:
-
onsuccess
(required) - Callback function called when operation was successfully completed -
onerror
(required) - Callback function, it’s called when error happen, receives single String with error message -
id
(required) - String identifier of push notification to mark as received
Boxcar.resetBadge()
Reset count of notificaitons to zero
Arguments:
-
onsuccess
(required) - Callback function called when operation was successfully completed -
onerror
(required) - Callback function, it’s called when error happen, receives single String with error message
Boxcar.getReceivedMessages()
Retrieves list of received messages from device storage. Messages are delivered from newest to oldest.
Arguments:
-
onsuccess
(required) - Callback function called when operation was successfully completed, this function receives single argument with list of notifications object described inBoxcar.registerDevice()
-
onerror
(required) - Callback function, it’s called when error happen, receivessingle String with error message -
before
- Number with timestamp, it will make this function return only messages newer than date from timestamp -
limit
- Maximum number of messages which should be returned