Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
rootCore SDK (Android)


Version 1.3.1112

This is Phunware's Android SDK README for the Core module. Visit for more details and to sign up.


  • Android SDK 2.2+ (API level 8) or above
  • Android Target
  • Android Support v4 18.0.+
  • Gson 2.2.4
  • OkHttp 1.6.0
  • okhttp-urlconnection 1.6.0
  • Retrofit 1.6.0


MaaS Core documentation is included in the Documents folder in the repository as both HTML and as a .jar. You can also find the latest documentation here: Core API Reference (iOS)


MaaS Core is designed to have as little impact on developers as possible. It is also a necessary requirement for all other MaaS SDKs.

MaaS Core helps to gather data for analytical purposes and also maintains a session throughout an app. A session is the duration that a user interacts with an app and it's used to uniquely identify analytical data. There are only two steps to setup set up and maintain sessions in any app. Application : application keys need to be registered, then sessions can be started and stopped.

Session Setup and Usage

Update Android Manifest

The MaaS Core relies on a few settings in order to communicate with the MaaS server. The first is the Internet permission, the second is a service that runs network communication communications asynchronously . The and the third helps to uniquely identify the device.

Code Block
<!-- Necessarynecessary for MaaS Core to communicate with the MaaS server -->
<uses-permission android:name="android.permission.INTERNET" />

    	<!-- other definitions -->

    	<!-- Necessarynecessary for MaaS Core to communicate with the MaaS server -->
    	<service android:name="com.phunware.core.internal.CoreService" />

    	<!-- Necessarynecessary to generate a UDID -->
    	<service android:name="com.OpenUDID.OpenUDID_service">
            			<action android:name="com.openudid.GETUDID" />
</application> application>

Optional Setup

There are optional configurations that can be set in the AndroidManifest`AndroidManifest.xmlxml`. These may be safely left unconfigured.

The first is a permission ACCESS`ACCESS_NETWORK_STATESTATE`. This permission allows access to the network state (connected, disconnected, etc.). This  This SDK uses it to determine if there is a network connection before sending analytic events. If there is none connected, then  then the events are queued up to be sent when a connection is available.

Code Block
<!-- Optional: If used, this will check result in making network calls being made more efficiently. -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- Optional: Set this permission in order to get more detailed analytics. -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

<!-- Optional: Set these following permissions to to get location data in analytics reports -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

Additionally, there is a CoreReceiver `CoreReceiver` that can be used. Currently, this is only used to receive connectivity change events. This  This is also used to help send analytic events more efficiently.

Code Block
<!-- Usedused by MaaS Core for efficient analytic caching and flushing. -->
<receiver android:name="com.phunware.core.internal.CoreReceiver">
        <action android:name="" />
</receiver> receiver>

Although the CoreReceiver and ACCESSthe `CoreReceiver` and `ACCESS_NETWORK_STATE permission STATE` permission do similar things, they are still unique and it is beneficial to use them simultaneously. The receiver will get updates when connectivity changes. However, every other BroadcastReceiver that is definied other `BroadcastReceiver` that is defined with that intent filter will as well, so the update may not be instantaneous. Connectivity could drop, so checking if a connection is available may be a faster and more reliable method. The CoreReceiver will The `CoreReceiver` will also send any queued-up analytic events once connection is restored.

Install Modules

Each MaaS module requires the MaaS Core SDK to run. In order to use any extra modules, they must first be installed into the Core SDK. This is done in code with one line and should be done in the application’s onCreate method:

Code Block
public void onCreate() {
    /* Otherother code */
    PwCoreSession.getInstance().installModules(PwAlertsModule.getInstance(), ...);
    /* Otherother code */

Register API Keys

Create a class that extends Application `Application` and register the Application `Application` class in the AndroidManifest`AndroidManifest.xmlxml` file. This  This should be called *after* a call to install additional modules. Register  Register the access, signature and encryption key in the Application’s onCreate `Application’s onCreate` method:

Code Block
public void onCreate() {
    /* Otherother code */
    /* Installinstall additional modules */

    /* Otherother code */

Defining Keys in the Manifest (Optional)

Code Block
public void onCreate() {
     * Alternatively, register keys when the keys are defined
     * in the manifest under metadata tags.

The metadata `meta-data` tags must be defined inside of the application `application` tag.

Code Block
<meta-data android:name="META_DATA_APPLICATION_ID" android:value="@string/app_id" />
<meta-data android:name="META_DATA_ACCESS_KEY" android:value="@string/access_key" />
<meta-data android:name="META_DATA_SIGNATURE_KEY" android:value="@string/signature_key" />
<meta-data android:name="META_DATA_ENCRYPTION_KEY" android:value="@string/encrypt_key" />

Application ID

You can find your application key in the MaaS portal.

Access Key

The Access Key access key is a unique key that identifies the client making the request. You can find your access key in the MaaS portal.

Signature Key

The Signature Key signature key is a unique key that is used to sign requests. The signature is used to check both request authorization and data integrity. You can find your signature key in the MaaS portal.

Encryption Key

The encryption key is used to encrypt and decrypt data that is exchanged between the client and the server. You can find your encryption key in the MaaS portal.

Activities: Start and Stop Session

A session is active once it is started and inactive when it has been stopped. A  A session will expire after two minutes (i.e. "expiration timeout") unless it is started again before thenrestarted prior.


To start the session in an Activity`Activity`, get the PwCoreSession `PwCoreSession` instance and call activityStartSession`activityStartSession(activity)`. The  The passed-in Activity `Activity` should be the current activity. This should This should be called in the activities onStart `onStart` method. This will ensure the session is properly created before fragments can fragments can be attached to the activity.

Code Block
public void onStart() {
    /* Otherother code */
    /* Otherother code */


To stop the session in an Activity`Activity`, get the PwCoreSession `PwCoreSession` instance and call activityStopSession`activityStopSession(activity)`. The  The passed-in Activity `Activity` should be the current activity. This should This should be called in the activities onStop `onStop` method.

Code Block
public void onStop() {
    /* Otherother code */
    /* Otherother code */

Calling activityStopSession`activityStopSession(context)` will stop the session. However, if activityStartSession`activityStartSession(context) is called ` is called before the expiration timeout is reached, then the session will be resumed. (This is how a session persists between activity transitions.)

Analytical Data

Various types of analytical data are collected and sent to the MaaS server for usage. Most  Most are available without any extra permissions:

  1. App Session IdID
  2. App Version Name
  3. App Version Code
  4. App Access Key
  5. Android Build Version
  6. Android OS
  7. Screen Size
  8. Screen Density
  9. Screen DPI
  10. Carrier
  11. Device OpenGL Version
  12. Device Sensors (Accelerometer, Proximity Monitor, etc.)
  13. Device Language
  14. *Device MAC Address
  15. *Device Wi-Fi Info
  16. *Device SSID
  17. *Device IP
  18. **Device User Agent
  19. Device Make
  20. Device Model
  21. Device IdID
  22. Timestamp
  23. Timezone


Requires ACCESS

 Requires `ACCESS_WIFI_


STATE` Permission

In order to get data for the MAC Address, Wi-Fi Info, SSID and IP data, the permission for ACCESS`ACCESS_WIFI_STATE needs to STATE` will need to be included in the manifest. If it is not included, then the data simply will not be collected.

** Requires




STATE` Permission
In order to get the device User Agent, the permission for ACCESS`ACCESS_NETWORK_STATE needs STATE` will need to be included in the manifest.
If it is not included, then the data simply will not be collected.

Verify Manifest

PwCoreModule `PwCoreModule` has a convenience method to check if the manifest for the Core SDK is set up properly. This should only be only be used for development and testing, not in production. 

Call the method with the line PwCoreModule`PwCoreModule.validateManifestCoreSetup(context)`. The passed-in context should be the application the application context. If there is an error, then an IllegalStateException `IllegalStateException` will be thrown with an error message on what couldnregarding what couldn't be found.

Compiling with ProGuard

If you use ProGuard in your app, be sure to include the following lines in your ProGuard configuration:

Code Block
-keep class * implements android.os.Parcelable { 
	    public static final android.os.Parcelable$Creator *; 

Integrating with Google Play Services API

Google Play Services API offers many features that your app can use. Go to the GooglePlayServicesIntegration sample app to see how MaaS SDKs utilize the API.


To view logs from the MaaS SDKs, use PwLog`PwLog.setShowDebug(true);`. The logs are all turned off by default.


MaaS Core uses the following third-party components.:

RetrofitType-safe REST client for Android and Java by Square, Inc.Apache 2.0
GSONA Java library to convert JSON to Java objects and vice-versa. Apache 2.0


Table of Contents