Mobile SDK Android
From ePrize Developers Wiki
OS Support
The HelloWorld Mobile SDK is built for Android apps targeting API level 14 and higher.
Version & Release Notes
SDK Version: 2.0.6
Release Notes:
- Updates to dependent librarys
- Switch to Retrofit + RxJava
Key Concepts
Singleton Classes
The SDK includes a number of Singleton classes which you will not create instances of, but rather, can simply reference via the class' getInstance() method. The Singleton classes used in the SDK include:
Additionally, the SDK includes a class named EPZConstants, which is a simple storage class for constants defined for use in the SDK, and as a convenience for applications using the SDK, so they can make use of the constants as needed (e.g. to avoid typos in string values, to use when defining map keys for configuration options, etc).
Event Dispatching
Version 2.0 of this SDK includes a major shift in the callback logic used for events. Where version 1.0 used listeners as the primary method of implementing callbacks from the SDK, version 2.0 introduces the use of the Event Bus by Otto, which the SDK uses to post events. Your app simply needs to register with the EPZBusProvider and subscribe to whichever events are applicable for your needs.
Configuration Keys
The SDK uses a concept of configuration keys to access data about promotions and instantiate certain views. Each active promotion will have an associated configuration key. When the list of active promotions is retrieved, you will have access to an array of these configuration keys. You will use the keys to get access to specific promotion configurations (EPZPromoConfiguration). The array of keys is stored in the EPZPromoLibrary instance for access anywhere in your application.
Getting Started
The SDK is designed to be an easy and practical way to retrieve a list of active promotions your organization is running with HelloWorld, Inc. Once you retrieve a list of active promotions, you can use the SDK to launch a given promotion using an instance of the SDK's built-in web view controller, where the specified promotion will be loaded into a customizable web view and presented to the user - all while remaining in your mobile application.
Obtain the EPrizeMobileSDK
Please contact your account team or Producer to obtain your copy of the SDK.
Add EPrizeMobileSDK to your project's references
Gradle Project Setup
- Copy the "HelloWorld_MobileSDK-X.X.aar" into your projects "libs" folder, where "X.X" represents the latest version of the library.
- Make sure your build.gradle file for your project's main module includes the following in addition to the standard Android application Gradle file setup:
repositories {
mavenCentral()
// add this for use with MobileSDK
flatDir {
dirs 'libs'
}
}
def mSdkVersion = '2.0'
android {
compileSdkVersion 24
buildToolsVersion '27.0.3'
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
}
dependencies {
impllementation "com.eprize.mobile.eprizemobilesdk:HelloWorld_MobileSDK:$mSdkVersion@aar"
implementation 'com.squareup:otto:1.3.8' // MobileSDK dependency
implementation 'com.google.code.gson:gson:2.8.5' // MobileSDK dependency
implementation 'com.squareup.retrofit2:retrofit:2.4.0' // MobileSDK dependency
implementation 'com.squareup.retrofit2:converter-gson:2.4.0' // MobileSDK dependency
implementation 'com.squareup.okhttp3:logging-interceptor:3.11.0' // MobileSDK dependency
implementation 'com.squareup.retrofit2:adapter-rxjava2:2.4.0' // MobileSDK dependency
implementation 'io.reactivex.rxjava2:rxandroid:2.0.2' // MobileSDK dependency
implementation "io.reactivex.rxjava2:rxjava:2.1.16" // MobileSDK dependency
}
where "$mSdkVersion" corresponds to the version of the library used.
Import SDK classes as necessary
In any class file that needs to utilize the SDK, you will need to import the necessary files. You can consult the Class Documentation section below for more information about each of the classes included in the SDK.
Submit Required Information to HelloWorld
Once you have your project set up in the Google Developers Console as specified above, you will need to submit the following app information to your HelloWorld account team or Producer:
- App Package (e.g. com.helloworld.mobilesdk.android.pushdemo) - See note below
- App Name (e.g. MobileSDK Push Demo App)
Sample Integration
The following section outlines steps to get up and running with the EPrizeMobileSDK in your app. These steps provide small code snippets that you can use as reference in your own project. If you need more information about any of the classes, properties, and/or methods used in any of these snippets, please consult the applicable class documentation provided.
Update your app's Manifest file
To be able to utilize this SDK, you will need to make a few updates to your app's manifest file.
Set up permissions (if not already included):
<uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <permission android:name="com.your.package.value.permission.C2D_MESSAGE" android:protectionLevel="signature" /> <uses-permission android:name="com.your.package.value.permission.C2D_MESSAGE" /> <uses-permission android:name="android.permission.GET_ACCOUNTS" /> <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" /> <uses-permission android:name="com.google.android.c2dm.permission.REGISTRATION" /> <uses-permission android:name="android.permission.WAKE_LOCK" />
Include the SDK's built-in activities in the list of activities:
<activity android:name="com.eprize.mobile.eprizemobilesdk.EPZPromoWebViewController"
android:configChanges="orientation|keyboardHidden|screenSize" />
<activity android:name="com.eprize.mobile.eprizemobilesdk.EPZPushPreferencesViewController"
android:configChanges="orientation|keyboardHidden|screenSize" />
And include the receiver and service tags, either using the SDK's EPZBroadcastReceiver and EPZIntentService, or your own BroadcastReceiver and IntentService (which need to extend EPZBroadcastReceiver and EPZIntentService, respectively).
<receiver android:name="com.eprize.mobile.eprizemobilesdk.EPZBroadcastReceiver"
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="com.your.package.value"/>
</intent-filter>
</receiver>
<service android:name="com.eprize.mobile.eprizemobilesdk.EPZIntentService"/>
You'll also need to ensure you include the GMS meta-data tag.
<meta-data
android:name="com.google.android.gms.version"
android:value="@integer/google_play_services_version" />
Configure the EPZPromoLibrary and EPZPushNotificationService and Register with Event Bus
To use the EPZPromoLibrary and EPZPushNotificationService classes, you need to configure them to your needs. You will create a Map (String, Object) that you will pass in to the class' configure() method. You will also need to set up the register and unregister methods with the EPZBusProvider instance in preparation for subscribing to events.
The code sample below includes only the required key/value pairs for the configuration options Map, which utilize constant values found in the EPZConstants class. There are a handful of other key/value pairs you can configure, which are outlined further in the Class Documentation for each class, respectively.
private static final String CLIENT_KEY_PUBLIC = "dev_multi";
private static final String PUSH_KEY_PUBLIC = "push_dev_multi";
private static final String GCM_SENDER_ID = "334651628650";
private final EPZPromoLibrary mLibrary = EPZPromoLibrary.getInstance();
private final EPZPushNotificationService mPushService = EPZPushNotificationService.getInstance();
private final Bus mBus = EPZBusProvider.getInstance();
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
...
// Register with EPZBusProvider so we can subscribe to EPZ events.
mBus.register(this);
// Set configuration options.
Map<String, Object> configOptions = new HashMap<String, Object>();
configOptions.put(EPZConstants.CONFIG_KEY_CLIENT_KEY, CLIENT_KEY_PUBLIC);
configOptions.put(EPZConstants.CONFIG_KEY_APP_CONTEXT, this);
configOptions.put(EPZConstants.CONFIG_KEY_GCM_SENDER_ID, GCM_SENDER_ID);
configOptions.put(EPZConstants.CONFIG_KEY_PUSH_KEY, PUSH_KEY_PUBLIC);
// Configure library and push service.
try {
mLibrary.configure(configOptions);
mPushService.configure(configOptions);
} catch (Exception configException) {
// Handle exception as needed.
}
}
@Override
protected void onDestroy() {
super.onDestroy();
mBus.unregister(this);
}
Fetch Promotion Configurations and Subscribe to Events
Once you have configured the EPZPromoLibrary, you are safe to fetch the promotion configurations via the fetchPromotionConfigurations() method.
mLibrary.fetchPromotionConfigurations();
You will also need to set up a @Subscribe method to handle the EPZPromotionConfigurationFetchEvent dispatched on completion of fetching the configurations.
@Subscribe
public void handlePromotionConfigurationFetchEvent(EPZPromotionConfigurationFetchEvent event) {
if (event.error == null) {
// Successfully retrieved promotion configurations.
} else {
// There was an error fetching configurations - handle as needed.
}
}
Launching a Promotion
If you have at least one active promotion configuration to which you give an accompanying call-to-action, you’ll need a way to display the promotion site in your app. To do so, get a reference to one of the EPZPromoConfiguration objects and call one of the launch methods in the EPZPromoLibrary.
If you do not wish to use the SDK's built-in EPZPromoWebViewController, you can use the SDK's EPZWebViewFragment in your own Activity. For more information on using your own Activity, visit the EPZWebViewFragment page.
if (mLibrary.getPromoKeys() != null && mLibrary.getPromoKeys().length > 0) {
EPZPromoConfiguration firstConfig = mLibrary.promotionConfigurationForKey(mLibrary.getPromoKeys()[0]);
mLibrary.launchPromotionForKey(firstConfig.getConfigKey());
}
If you would like to handle any web view or lifecycle events, you can set up a @Subscribe method for the EPZPromoWebViewEvent and/or the EPZPromoWebViewLifecycleEvent.
@Subscribe
public void handlePromoWebViewEvent(EPZPromoWebViewEvent event) {
// Handle the event fired from the web view here as needed. Event name found via event.eventName
}
@Subscribe
public void handlePromoWebViewLifecycleEvent(EPZPromoWebViewLifecycleEvent event) {
// Handle lifecycle events as needed. Event name found via event.eventName
if (event.error != null) {
// Handle error as needed.
}
}
Subscribing and Unsubscribing a User with the EPZPushNotificationService
If you are integrating with the EPZPushNotificationService, you will also want to handle subscribing the user's device. Note that in the code sample below, the subscribe call is surrounded by a recommended conditional to check whether or not the push service is supported on the device running the application, and whether or not the device is already subscribed.
if (mPushService.isSupported(this)) {
if (!mPushService.userIsSubscribed()) {
mPushService.subscribeUserDevice();
}
} else {
// Google Play Services unavailable - Push notifications cannot be used on this device.
}
To handle the subscribe event, set up a @Subscribe method for the EPZPushSubscribeEvent:
@Subscribe
public void handlePushSubscribeEvent(EPZPushSubscribeEvent event) {
if (event.error != null) {
// Handle error as needed
} else {
// Successfully subscribed user.
}
}
It is advisable to allow a user to unsubscribe from push notifications and the EPZPushNotificationService, as seen in the example below.
if (mPushService.userIsSubscribed()) {
mPushService.unsubscribeUser();
}
To handle the unsubscribe event, set up a @Subscribe method for the EPZPushUnsubscribeEvent:
@Subscribe
public void handlePushUnsubscribeEvent(EPZPushUnsubscribeEvent event) {
if (event.error != null) {
// Handle error as needed
} else {
// Successfully unsubscribed user.
}
}
Fetch & Set Push Notification Preferences
If you are integrating with the EPZPushNotificationService, you will likely want to fetch a user's push notification preferences, and provide them with the ability to fine-tune which types of notifications they receive.
To fetch a user's push preferences, you will call the fetchPushNotificationPreferences() method, as in the example below.
if (mPushService.userIsSubscribed()) {
mPushService.fetchPushNotificationPreferences();
}
To handle the event once push preference fetching is complete, set up a @Subscribe method for the EPZPushPreferencesFetchEvent:
@Subscribe
public void handlePushPreferencesFetchEvent(EPZPushPreferencesFetchEvent event) {
if (event.error != null) {
// Handle error as needed
} else {
// Successfully retrieved push preferences.
// Note: event.preferences returned is the value of property:
// mPushService.getPushNotificationPreferences(), which is an array list of EPZPreferenceItem objects
// This data is returned for convenience, and may not be necessary for you to do anything with,
// unless you plan on creating your own custom Activity for allowing users to set their
// push preferences (i.e. not using the SDK's built-in EPZPushPreferencesViewController).
}
}
Once a user's push notification preferences have been retrieved, you can make use of the SDK's built-in EPZPushPreferencesViewController to display the user's preferences, and allow them to toggle individual notifications on and off as desired.
To use the SDK's built-in view controller, you can call the EPZPushNotificationService's launchPushPreferencesActivity() method:
mPushService.launchPushPreferencesActivity(this);
If desired, you can set up a @Subscribe method for the EPZPushPreferencesViewLifecycleEvent to respond to EPZPushPreferencesViewController lifecycle events.
Note that in the code sample below, we have set up an auto-save call when the view closes so the user's preferences will be saved automatically.
public void handlePushPreferencesViewLifecycleEvent(EPZPushPreferencesViewLifecycleEvent event) {
// Handle lifecycle events as needed. Event name found via event.eventName
if (event.error != null) {
// Handle error as needed.
} else {
if (event.eventName.equals(EPZConstants.LIFECYCLE_EVENT_CLOSE)) {
if (mPushService.getPushNotificationPreferences() != null) {
mPushService.savePushNotificationPreferences();
}
}
}
}
Additionally, you can set up a @Subscribe method for the EPZPushPreferenceItemsChangedEvent, which is triggered when an individual preference item changes.
@Subscribe
public void handlePushPreferenceItemsChangedEvent(EPZPushPreferenceItemsChangedEvent event) {
// If you want to do anything with the preference item(s) changed, you can target
// event.data, which is a Map of data associated with the event. The key for each item in
// the map is the EPZPreferenceItem preference ID value, and the value is the boolean
// value for the preference.
}
Save Push Preferences
If a user chooses to update their push notification preferences, you'll want to save them on behalf of the user (as seen above). To do this, you can make use of the savePushNotificationPreferences() method, as seen in the example below.
if (mPushService.getPushNotificationPreferences() != null) {
mPushService.savePushNotificationPreferences();
}
Additionally, you can set up a @Subscribe method for the EPZPushPreferencesSaveEvent, which is dispatched upon completion of the save method.
@Subscribe
public void handlePushPreferencesSaveEvent(EPZPushPreferencesSaveEvent event) {
if (event.error != null) {
// Handle error as needed.
} else {
// Successfully saved preferences.
}
}
Handle Push Notification & Retrieve Notification Data
The SDK's EPZBroadcastReceiver includes all necessary logic to receive and handle a notification. This class can easily be extended for greater flexibility and customization for your application. For more information, consult the EPZBroadcastReceiver documentation.
Class Documentation
The SDK includes a number of available classes, whose specific documentation pages can be accessed by clicking one of the links below.
com.eprize.mobile.eprizemobilesdk
com.eprize.mobile.eprizemobilesdk.events
- EPZAnalyticsEventTrackedEvent
- EPZClosePromoWebViewEvent
- EPZPromotionConfigurationFetchEvent
- EPZPromoWebViewEvent
- EPZPromoWebViewLifecycleEvent
- EPZPushActionEvent
- EPZPushNotificationDataEvent
- EPZPushPreferenceItemsChangedEvent
- EPZPushPreferencesFetchEvent
- EPZPushPreferencesSaveEvent
- EPZPushPreferencesViewLifecycleEvent
- EPZPushSubscribeEvent
- EPZPushUnsubscribeEvent
- EPZWebViewCloseWindowEvent
- EPZWebViewCreateWindowEvent
- EPZWebViewOnPageFinishedEvent
- EPZWebViewOnPageStartedEvent
