Promotions SDK

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

Release Notes:

• Integration with push notifications
  • Subscribe and unsubscribe from push notifications
  • Fetch, set, and save push notification preferences for specific users (including built-in Push Preferences view controller)
  • Record actions for specific push notifications
• Analytics tracking events
  • Queue analytics events to be tracked with the SDK’s Analytics Service, complete with custom data, if desired
• Web View Event Handling
  • Improved integration with web pages loaded into the built-in web view controller, using the HelloWorld MobileSDK JavaScript bridge, allowing correctly-configured events fired off from a web page to bubble up through the SDK and dispatched to the parent app.
• Improved event dispatching
  • Listeners in Singleton classes replaced with events dispatched via the new EPZBusProvider class

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:

• EPZAnalyticsService
• EPZBusProvider
• EPZPromoLibrary
• EPZPushNotificationService

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.

Additionally, the SDK offers the ability to integrate push notifications into your application, including the ability for users to customize the types of notifications they would like to receive.

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

1. Copy the "HelloWorld_MobileSDK-X.X.aar" into your projects "libs" folder, where "X.X" represents the latest version of the library.
2. 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'

dependencies {
    compile "com.eprize.mobile.eprizemobilesdk:HelloWorld_MobileSDK:$mSdkVersion@aar"
    compile 'com.squareup:otto:1.3.7' // MobileSDK dependency
    compile 'com.google.android.gms:play-services:7.5.0' // MobileSDK dependency
    compile 'com.google.code.gson:gson:2.2.4' //MobileSDK dependency
}

where "$mSdkVersion" corresponds to the version of the library used.

Eclipse Project Setup

In order to utilize the SDK, you'll need to link to it in your project properties.

1. Import the EPrizeMobileSDK project into Eclipse.
2. Right-click on your Android application project and select "Properties"
3. Select "Android" in the left side navigation
4. Under the "Library" section of the dialog window, click "Add..." and select EPrizeMobileSDK.

dexOptions {
    preDexLibraries = false
}

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.

Set up and provide necessary files for Push Notifications

If you are integrating with the SDK’s Push Notification Service, you will need to follow the appropriate steps to set up your application to use push notifications, both for Development and Production.

Create Project

In the Google Developers Console, you will need to create a project for your app. The project needs to have Google Cloud Messaging for Android enabled in the "APIs" section of the project. You will also need to create a Server Key in the "Credentials" section of the project, making sure to enter an IP address of 0.0.0.0/0 to ensure Google Cloud Messaging accepts all servers.

Important: You'll also need the Project Number of this project for use when configuring the SDK's EPZPushNotificationService. In the code samples on this and other pages, this project number is referenced by the constant GCM_SENDER_ID.

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)
• API Key (e.g. AIzaSyDtlog60M2lxHPAgBci3FU3CiWAlDNR0w8)
• Push Key (e.g. push_dev_multi)

Important Note:

If you have requested using a different Push Key for development/testing than you are for your final production release, you will need to use a unique App Package for each. The app package does not need to be your exact package name, as it is just used as a unique identifier for your app in the Push Notification Service back-end. As such, simply adding ".dev" to the end of this value will suffice for using in your development/testing. Just be sure to make note of this when submitting the above information to your HelloWorld account team or Producer.

In this case, you will need to be sure you include the EPZConstants.CONFIG_KEY_APP_ID key/value pair when you call the configure method for the EPZPushNotificationService.

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

• EPZAnalyticsService
• EPZBroadcastReceiver
• EPZBusProvider
• EPZConstants
• EPZIntentService
• EPZPreferenceItem
• EPZPromoConfiguration
• EPZPromoLibrary
• EPZPromoWebViewController
• EPZPushNotificationService
• EPZPushPreferencesViewController
• EPZString
• EPZWebViewFragment

com.eprize.mobile.eprizemobilesdk.events

• EPZAnalyticsEventTrackedEvent
• EPZClosePromoWebViewEvent
• EPZPromotionConfigurationFetchEvent
• EPZPromoWebViewEvent
• EPZPromoWebViewLifecycleEvent
• EPZPushActionEvent
• EPZPushNotificationDataEvent
• EPZPushPreferenceItemsChangedEvent
• EPZPushPreferencesFetchEvent
• EPZPushPreferencesSaveEvent
• EPZPushPreferencesViewLifecycleEvent
• EPZPushSubscribeEvent
• EPZPushUnsubscribeEvent
• EPZWebViewCloseWindowEvent
• EPZWebViewCreateWindowEvent
• EPZWebViewOnPageFinishedEvent
• EPZWebViewOnPageStartedEvent