Download Android Gravy SDK Guide

Android Gravy SDK Guide | timeRAZOR Inc. Android Gravy SDK Guide
Code Version: 1.0.0.5 Android Gravy SDK Guide | timeRAZOR Inc. Content
Table of Figures ...................................................................................................................................................................................... 3 Preamble .................................................................................................................................................................................................... 4 How to use this document. ................................................................................................................................................................ 4 Getting Started ........................................................................................................................................................................................ 5 Minimum Requirements: ............................................................................................................................................................... 5 What you will need: ......................................................................................................................................................................... 5 Prepare Your Project ............................................................................................................................................................................ 5 Add to Project Source: .................................................................................................................................................................... 5 manifest.xml -­‐ General: ............................................................................................................................................................... 5 SDK Permission .......................................................................................................................................................................... 6 Gravy Service ............................................................................................................................................................................... 6 FragmentActivity ......................................................................................................................................................................... 6 Meta Data – SDK Key .............................................................................................................................................................. 6 Permissions – Google Play Services ............................................................................................................................... 6 General Permissions ................................................................................................................................................................. 6 manifest.xml – Google Messaging: ......................................................................................................................................... 6 Meta Data - GCM/Notification .............................................................................................................................................. 6 Notification Receiver ................................................................................................................................................................. 7 GCM/Notifications Permissions ........................................................................................................................................... 7 Use Gravy SDK -­‐ How-­‐to ..................................................................................................................................................................... 7 Key Classes ........................................................................................................................................................................................... 7 GravyService ................................................................................................................................................................................. 7 GravyClientManager ................................................................................................................................................................. 7 GravyClientManager Exposed Features ........................................................................................................................ 8 Communicating with Gravy SDK .................................................................................................................................................. 10 Broadcast Receiver IntentFilter Action ................................................................................................................................ 10 Requests, Response Listeners, Receivers ..................................................................................................................... 11 Core Access Points ................................................................................................................................................................ 11 Built in IntentFilter Action Suffix ............................................................................................................................................ 12 //{code & snippets} ........................................................................................................................................................................... 15 2 Code Version: 1.0.0.5 Android Gravy SDK Guide | timeRAZOR Inc. Table of Figures
Table 1 GravyClientManager Exposed Features ................................................................................................................ 9 Table 2 Core Communication Access Points ..................................................................................................................... 12 Table 3 Built-in IntentFilter Action Suffixes .......................................................................................................................... 12 Table 4 Broadcast Returned Objects .......................................................................................................................................... 13 3 Code Version: 1.0.0.5 Android Gravy SDK Guide | timeRAZOR Inc. Preamble
This document covers the TimeRazor Inc. Android SDK implementation of the following products;
•
TimeRazor GOLD SDK.
•
TimeRazor Content API SDK.
•
TimeRazor White Label UI SDK.
The document describes the features available to the several flavors of the SDK. Depending on the flavor of
your implementation, some features will not be available. It is therefore key your manifest and properties
configuration adhere to the specifications outlined in this document and your specific distribution.
How to use this document.
The documents is designed as a guide for multiple flavors an the TimeRAZOR Android SDK. Each flavor or
combination is packaged as a distribution. There are foundation setup requirements for the SDK in general.
There are also requirements specific to each distribution. Finally, wthin each distribution there are optional
requirements we call features.
To assist in identifying the relevant components to your flavor and distribution, this document employs icons at
the relevant segways. General foundation parameters, requirements and guidelines will not require a
specialized icon.
Icon
Guide Description
G TimeRazor GOLD SDK
W TimeRazor White Label UI SDK
C *? TimeRazor Content API SDK
Optional – “*?” Represents an optional feature for example GCM.
4 Code Version: 1.0.0.5 Android Gravy SDK Guide | timeRAZOR Inc. Getting Started
The quickest way to get started is to download our sample app. While this application doesn’t do much
productively, it provides a template to see specifically how and where to wire the SDK into your application. It
also provides you with the necessary build and project settings.
Minimum Requirements:
•
Android Gravy SDK library jar.
•
Android Gravy SDK Stub Project.
•
Android Manifest Mimimum 2.3.3 (API 10).
•
Minimum Compile/Build SDK 3.0 (API 11).
•
Google Play Services.
•
Android Support Library v4.
What you will need:
•
Gravy SDK API Key for either Sandbox or Production Environments.
Prepare Your Project
Add to Project Source:
1. Add Gravy SDK Stub Project as a project source to your current project.
2. Add Gravy SDK library jar to your project’s lib folder.
The SDK requires several key components be registered in your applications manifest.xml. These
include permissions, services and receivers for notifications. The following outlines those sections.
manifest.xml - General:
Distribution Flavor <!-- DISTRO_CONTENT | DISTRO_GOLD | DISTRO_CONTENT_GOLD_WHITE_LABEL | DISTRO_CONTENT_GOLD
| DISTRO_CONTENT_WHITE_LABEL -->
<meta-­‐data android:name="=" com.timerazor.gravysdk.distro" android:value="DISTRO_CONTENT_GOLD_WHITE_LABEL" /> Server Target Environment <!—Boolean: true for Sandbox, false Production -->
5 Code Version: 1.0.0.5 Android Gravy SDK Guide | timeRAZOR Inc. <meta-­‐data android:name="="com.timerazor.gravysdk.SANDBOX " android:value="true/false" /> SDK Permission
<!--gravy sdk required permissions-->
<permission android:name="com.timerazor.gravysdk.{YOUR_PACKAGE_NAME}.SERVICE_PERMISSION"
android:protectionLevel="signature"/>
<uses-permission
android:name="com.timerazor.gravysdk.{YOUR_PACKAGE_NAME}.SERVICE_PERMISSION"/> Please remember to include the permissions for Google play services as per the above link.
Gravy Service
<!-­‐-­‐gravy sdk service-­‐-­‐> <service android:name="com.timerazor.gravysdk.client.GravyService" /> FragmentActivity
<!—A FragmentUIBase implemented FragmentActivity that provided by your app. String representation of the full class name-­‐-­‐> <service android:name=" com.timerazor.gravysdk.FragmentActivity" android:value="{YOUR_IMPLEMENTATION_OF_ FragmentUIBase}" /> Meta Data – SDK Key
<!-­‐-­‐gravy sdk meta data-­‐-­‐> <meta-­‐data android:name="com.timerazor.gravysdk.apiKey" android:value="{YOUR_Gravy_SDK_API_KEY}" /> Permissions – Google Play Services
<!-­‐Play Services -­‐-­‐> <uses-­‐permission android:name="android.permission.GET_ACCOUNTS"/> <uses-­‐permission android:name="android.permission.WAKE_LOCK"/> General Permissions
<!-­‐-­‐ Permissions -­‐-­‐> <uses-­‐permission android:name="android.permission.READ_PHONE_STATE"/> <uses-­‐permission android:name="android.permission.INTERNET"/> <uses-­‐permission android:name="android.permission.ACCESS_NETWORK_STATE"/> <uses-­‐permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/> <uses-­‐permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
manifest.xml – Google Messaging:
Meta Data - GCM/Notification
<!—GCM/Notification meta data-­‐-­‐> <meta-­‐data android:name="com.timerazor.gravysdk.senderId" android:value="key-­‐ {YOUR_GCM_SENDER_ID}" /> 6 Code Version: 1.0.0.5 Android Gravy SDK Guide | timeRAZOR Inc. Please note the Sender ID is preceded by the prefix “key-“. THIS IS REQUIRED.
Notification Receiver
<!-­‐-­‐Notification receiver-­‐-­‐> <receiver android:name="com.timerazor.gravysdk.notification.GcmWakefulBroadcastReceiver" android:permission="com.google.android.c2dm.permission.SEND" > <intent-­‐filter> <action android:name="com.google.android.c2dm.intent.RECEIVE"/> <action android:name="com.google.android.c2dm.intent.REGISTRATION" /> <category android:name={YOUR_PACKAGE_NAME} /> </intent-­‐filter> </receiver> GCM/Notifications Permissions
<!-­‐-­‐ C2DM/GCM Related Permissions -­‐-­‐> <permission android:name="{YOUR_PACKAGE_NAME}.permission.C2D_MESSAGE" android:protectionLevel="signature"/> <uses-­‐permission android:name="{YOUR_PACKAGE_NAME}.permission.C2D_MESSAGE"/> <uses-­‐permission android:name="com.google.android.c2dm.permission.RECEIVE"/> <uses-­‐permission android:name="android.permission.GET_ACCOUNTS"/> <uses-­‐permission android:name="android.permission.WAKE_LOCK"/> You are now ready to use the Gravy SDK.
Use Gravy SDK - How-to
The SDK provides multiple points of access with a view to align closely with Android’s best practices.
To that end, our core functionality is routed through our GravyService.class that was added to your
manifest definition. This service works in tandem with the GravyClientManager instance.
Key Classes
GravyService
You can directly access the service in two ways:
1. startService().
2. bindService(). - GravyServiceBinder
GravyClientManager
You can access the client manager by:
7 Code Version: 1.0.0.5 Android Gravy SDK Guide | timeRAZOR Inc. 1. Calling it’s getInstance() directly.
2. Acquiring said instance from the GravyService you obtained via bindService();
The SDK is designed with several defaults but also provides a property class, GravyClientProperties,
which is a parameter for your client manager getInstance method. You may initialize or update the
SDK Client properties in following ways:
•
GravyClientManager.getInstance(Context, gravyClientProperties).
•
GravyClientManager.setGravyClientProperties(gravyClientProperties).
•
GravyClientManager.setGravyClientPropertiesViaService (gravyClientProperties).
•
Send the properties file directly to GravyService instance:
Intent intent = new Intent(context, GravyService.class); intent.putExtra(SDKConstants.Extra.GRAVY_PROPERTIES_KEY, gravyClientProperties); context.startService(intent);
It is strongly recommended you utilize the property object to get the most from the SDK including
adding general security permissions you may wish to apply.
GravyClientManager Exposed Features
The client manager instance is your window into the SDK. This features exposed depend on your
distribution are in Table 1 GravyClientManager Exposed Features
Feature Exposed
Accessor
Description
Register with Gravy Server
registerDevice ()
Registers with Gravy Server
registerDeviceWithUserIdentifier()
Register to receive Location Updates
GravyClientProperties.
Registers your app to be updated
from the SDK
setReceiveLocationBroadcastUpd
when Location Changes occur.
atesFromSDK()
Send Location updates from your
simulateLocation ()
code to the SDK
Send location updates from your
app the Gravy SDK.
Access and modify User Profile data
getGravyUser ();
from the SDK’s persistent storage
deleteGravyUser ();
(database and Shared Preferences)
getGravyDevice();
Data access.
deleteGravyDevice();
getMessages();
deleteMessages();
Register Your applications current
GravyClientProperties.
Setting to tell the SDK to track app
8 Code Version: 1.0.0.5 Android Gravy SDK Guide | timeRAZOR Inc. Feature Exposed
Accessor
Description
foreground state.
setAllowSDKToDetermineAppFore
State. Tracking is accomplished
groundStatus()
though onPause/onResume calls to
applyAppState();
applyAppState();
Set Activity Context that allows the
setActivityContext();
SDK to interact directly with your
App’s UI to display dialogs.
GCM Register for Google Cloud
registerForGravyNotifications ()
Messaging.
Register for GCM and Gravy
Services Notification
Register to receive Notification
Updates from the SDK.
C Content responses return the raw JSON data and must be parsed by your application. Information
on the object structure is available at the Gravy Content API Documentation.
Content List ofMoods
getMoods
Retrieves a list of Gravy Moods.
Content List Channels
getChannels()
Retreives a list of Gravy Channels
A Content Single Channel
getChannelDetailWithId()
Retreives Channel data which is
essentially a list of abbreviated
event objects.
Content List of Events
getEvents()
Retreives a list of events matching
the request parameters.
Content List of Venue Events
getPopularEvents()
Retreives a list of Popular Events
matching the request parameters.
Content List of Popular category
getVenueEvents()
Events
Retreives a list of Events matching
the request parameters for a
Venue.
A Content Single Event
getEventDetailWithId()
Retreives a an Event Detail object
matching the supplied Id
Table 1 GravyClientManager Exposed Features
All request methods do not return directly but instead take a RequestWrapper object that may contain
your registered listener and/or receiver IntentFilter action that will be used to broadcast the result
back to your application receiver with the correct permission restrictions.
9 Code Version: 1.0.0.5 Android Gravy SDK Guide | timeRAZOR Inc. Communicating with Gravy SDK
Gravy Android SDK provides multiple options to best fit your current App architecture. For most
requests to the SDK, the API supports a registered listener and/or broadcast receiver IntentFilter
Action. For the latter, a permission IS REQUIRED for the receiver of that broadcast
[Context.registerReceiver(receiver, permission) OR via XML in the App’s Manifest]. In addition,
permissions may be assigned to each request; on demand. This is important as ALL SDK
broadcasts follow the Context.sendBroadcast(Intent, permission) pattern.
If no permissions are provided, the broadcast will be done with the default permission you registered
in the Manifest above. The API has built in broadcast receiver IntentFilter actions that your app can
listen for as well as those you may provide during a request (on demand).
Broadcast Receiver IntentFilter Action
Owing to the flexibility of broadcast receivers and IntentFilter actions within the SDK, a specific
nomenclature has been established to separate the following:
A. SDK IntentFilter Actions – Internally defined broadcast IntentFilter actions built into the SDK
for your consumption (Table 3 Built-in IntentFilter Action Suffixes).
B. User IntentFilter Actions – Those you may define and pass to the SDK. For on demand
IntentFilter actions that you specify at run time, only provide the SUFFIX (explained later). A
standard prefix will be incorporated into the complete IntentFilter action. However, you must
register for the complete action (prefix + suffix).
A) SDK IntentFilter Actions - Built-in actions you opt to Register/Listen.
Broadcast actions built into the SDK follow the following format:
SDK_PACKAGE_NAME.YOUR_PACKAGE_NAME.ACTION_SUFFIX.
IntentFilter action prefix
IntentFilter action suffix
The suffixes are defined within the documentation. If you wish to register for any of these built-in
broadcasts, just follow the format above. The suffixes are listed at the end of this document (Table 3
10 Code Version: 1.0.0.5 Android Gravy SDK Guide | timeRAZOR Inc. Built-in IntentFilter Action Suffixes). Remember to register your receiver with the appropriate
permission.
B) User IntentFilter Actions – You define, register for and pass per request
These actions take a reverse approach in the package name order. In an effort to ensure none of
your broadcasts are interrupted, REFRAIN from utilizing the SDK_PACKAGE_NAME in ANY of your
App’s Intent Filter actions outside of SDK interaction requests. The format is as follows.
YOUR_PACKAGE_NAME. SDK_PACKAGE_NAME.ACTION_SUFFIX.
IntentFilter action prefix
IntentFilter action suffix
Please note that the complete IntentFilter action for a broadcast you define is hidden from you and
must conform to the above format. The API only expose the ACTION_SUFFIX to your client
application. After providing this suffix, the package names are concatenated as prefixes. Remember
to register for the complete IntentFilter action (prefix+suffix).
Requests, Response Listeners, Receivers
The SDK utilize Response objects, Listeners and Receivers to keep your App updated with the state
of each action or request. This ensures you are able to verify prerequisites and use those callbacks to
take the next step to update your App.
It is strongly recommended you follow the IPC options where they are exposed in the SDK. This will
ensure that you are not relying on objects that are no longer valid owing to the fact your
Activity/Service has been killed.
Core Access Points
How To
Class type & Access
Description
ClientReceiverActionFactory – singleton.
Exposes the built-in Intent Filter
actions via getReceiverAction(int
Get built in Intent Filter
Actions
type). Use this path to register for
intent filters at run time. For Manifest
registraition follow the structure (A)
above in conjunction with the outlined
suffixes.
11 Code Version: 1.0.0.5 Android Gravy SDK Guide | timeRAZOR Inc. How To
Class type & Access
Description
Specify generalized
GravyClientProperties.
Use to set general values and pass to
parameters for the SDK.
Create a listener
GravyClientManager or GravyService
GravyListener - parent listener interface.
Provides a Callback mechanism for
Implement any of the available
implementing any or all interfaces as
GravyListeners and obtain a
you deem necessary.
RequestWrapper with RequestFactory.
getRequestWrapper(type, GravyListener).
RequestFactory – singleton.
Generate Request
getRequestWrapper().
Use to generate a request. Requests
cannot be created by any other
means.
Specify Intent Filter Action
on demand per request.
Specify receiverPermission
BaseRequest.
Returns the current request object for
assignReceiverActionSuffix()
chaining.
GravyRequest. setReceiverPermission()
Assigns a permission for broadcasting
on demand
the results of this request.
Table 2 Core Communication Access Points
Built in IntentFilter Action Suffix
ClientReceiverActionFactory - Type
Suffix String Value
PLAY_SERVICES_CONNECTION
“PLAY_SERVICES_CONNECTION”
PLAY_SERVICES_RESPONSE_DIALOG
“PLAY_SERVICES_SHOW_ERROR_DIALOG”
GRAVY_NOTIFICATION
“BROADCAST_SUFFIX_NOTIFICATION”
APP_FOREGROUND_STATE
“BROADCAST_SUFFIX_FOREGROUND_STATE”
GRAVY_LOCATION_UPDATE
“BROADCAST_SUFFIX_DEVICE_LOCATION”
GRAVY_USER_PROFILE
“BROADCAST_SUFFIX_USER_PROFILE”
GRAVY_DEVICE_PROFILE
“BROADCAST_SUFFIX_DEVICE_PROFILE”
GRAVY_MESSAGE
“BROADCAST_SUFFIX_GRAVYMESSAGE”
GRAVY_GCM_REGISTRATION
BROADCAST_SUFFIX_GCM_REGISTRATION
GRAVY_SDK_REGISTRATION
BROADCAST_SUFFIX_SDK_REGISTRATION
Additional built-in filters exist and their suffix are defined in SDKonstants.ExternalBroadcastSuffix
and can be accessed via the ClientReceiverActionFactory.
Table 3 Built-in IntentFilter Action Suffixes
Broadcasts to your client application will ideally have a single object identified by the same key. The object is almost always a Parcelable object but varies depending on the the Action being received. 12 Code Version: 1.0.0.5 Android Gravy SDK Guide | timeRAZOR Inc. The main Key for Broadcasts from the SDK is the string: SDKConstants.Extra.GRAVY_BROADCAST_KEY. Use this string to get broadcast data utilizing intent.getExtras().get?(key). SDK broadcasts are composed of the necessary responses to your request. Similar to our GravyListeners, the SDKConstants.Extra.GRAVY_BROADCAST_KEY returns a ParcelableState object with the relevant Request and Response data. Unwrapping the ParcelableState Object This special object implements Parcelable and is the main response mechanism back to your App. Its members and their purpose are listed in the JavaDocs documentation, however, here are a few highlights. • baseResponse: is a response object of either GravyResponse or GravyDataResponse. • responseRawData: for Content related requests and any other requests where the JSON raw data is requested. This option is currently only available for Content API requests. • intentBundle. This bundle provides the SDK with a means to return additional bundle information back to your app. If not specified, you may never utilize this option. • Additional members that are needed to communicate various responses and states to your application utilizing this Parcel. Table 4 Broadcast Returned Objects ClientReceiverActionFactory - Type
Returned Key Value
com.timerazor.gravysdk.client. ParcelableState –
PLAY_SERVICES_CONNECTION
playServicesStatus of type PLAY_SERVICES_DISCONNECTED,
PLAY_SERVICES_CONNECTED,
PLAY_SERVICES_CONNECTION_FAILED
com.timerazor.gravysdk.client. ParcelableState –
playServicesCode of
PLAY_SERVICES_RESPONSE_DIALOG
PLAY_SERVICES_REQUEST_CODE_RESOLVE_ERR for failed
results with resolution or “other” failed result without resolution
reported by Google. See Google Play Services Tutorial for
ConnectionResult. hasResolution().
com.timerazor.gravysdk.client. ParcelableState –
sdkNotificationAction of type NOTIFICATION_DEFAULT_ACTION,
NOTIFICATION_NEGATIVE_ACTION
GRAVY_NOTIFICATION
NOTIFICATION_POSITIVE_ACTION
NOTIFICATION_INTENT_ACTION
NOTIFICATION_DIALOG_ACTION
Optional intentBundle – holds the intent with the notification data.
APP_FOREGROUND_STATE
com.timerazor.gravysdk.client. ParcelableState [Boolean
13 Code Version: 1.0.0.5 ClientReceiverActionFactory - Type
Android Gravy SDK Guide | timeRAZOR Inc. Returned Key Value
isAppInForeground]
GRAVY_LOCATION_UPDATE
GRAVY_USER_PROFILE
GRAVY_DEVICE_PROFILE
GRAVY_MESSAGE
GRAVY_LOCATION_UPDATE_SERVER_RESULTS
com.timerazor.gravysdk.client. ParcelableState
intentBundle – holds the intent with the location data
com.timerazor.gravysdk.client. ParcelableState
intentBundle – holds the intent with the user profile data
com.timerazor.gravysdk.client. ParcelableState
intentBundle – holds the intent with the device data
com.timerazor.gravysdk.client. ParcelableState
intentBundle – holds the intent with the message data
com.timerazor.gravysdk.client. ParcelableState
com.timerazor.gravysdk.client. GravyUpdateLocationRequest
GRAVY_GCM_REGISTRATION
GRAVY_SDK_REGISTRATION
Additional Considerations: • If your app requires notification support by the SDK, the following are needed.
o Google Cloud Messaging API Key for your App.
GCM o Google Cloud Messaging Sender ID.
14