Mobile SDK Android

From ePrize Developers Wiki

Revision as of 19:09, 8 January 2014

OS Support

The ePrize Mobile SDK is built for Android apps targeting API level 9 and higher.

Getting Started

The ePrize Mobile SDK is designed to be an easy and practical way to retrieve a list of active promotions your organization is running with ePrize, 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.

Key Concepts

Shared Library
This SDK has a class named EPZPromoLibrary, which is a Singleton class that is the workhorse of the SDK. Since it is a Singleton, you will not create instances of it, but rather, will simply reference it via the class's getInstance() method.

Configuration Keys
This SDK uses a concept of configuration keys to access data and instantiate views. Each active promotion that your organization has with ePrize 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), which you can use to launch a promotion right inside of your app. The array of keys is stored in the library's instance for access anywhere in your application.

Step 1: Obtain the EPrizeMobileSDK

Please contact your account team or Producer to obtain your copy of the ePrize Mobile SDK.

Step 2: Add EPrizeMobileSDK Library to your Project's References

In order to utilize the EPrizeMobileSDK, 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.

Step 3: 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 EPrizeMobileSDK Class Documentation section below for more information about each of the classes included in the SDK.

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" />

Include EPZPromoWebViewController activity in the list of activities:

<activity android:name="com.eprize.mobile.eprizemobilesdk.EPZPromoWebViewController"
          android:configChanges="orientation|keyboardHidden|screenSize"></activity>

Important Note: It is highly recommended that you set the android:configChanges attribute as specified above. This will ensure that the activity is not completely destroyed and re-created when the device's orientation changes, or when the keyboard is hidden. If this is not done, and the activity is destroyed and re-created, the user will lose their place in the promotion they are visiting, and be returned to the promo's home page, resulting in an unpleasant user experience. Additionally, if you wish to lock the activity's orientation to match your app, you can set the android:screenOrientation attribute accordingly.

Configure the EPZPromoLibrary, Set its Listener, & Fetch Promotion Configurations

To use the EPZPromoLibrary, you need to configure it to your needs. You will create a Map (String, Object) that you will pass in to the library's configure() method. There are 2 required key/value pairs that must be specified in this Map: clientKey (String), and appContext (Context). There are a handful of other key/value pairs you can configure, which are outlined further in the EPZPromoLibrary documentation. Note that an exception will be thrown if either the clientKey or appContext key/value pairs are invalid.

You will also need to set the listener so you can implement the callback methods that are called on promotion retrieval success and failure.

Once you have configured the library, you are safe to fetch the promotion configurations via the fetchPromotionConfigurations() method.

Important Note: It is highly recommended that you configure the SDK as early as possible in your app's main activity, so it will be configured and ready when you need it.

Implement Applicable Callback Methods

In order to receive access to the library's callback methods, you need to implement EPZListener and its applicable methods. Wherever you choose to integrate the retrieval of configuration data, you will need to implement the promotionConfigurationsRetrieved() and promotionConfigurationsFailedWithError() methods. Per the naming of each method, these methods are called when the promotion configurations are successfully or unsuccessfully retrieved, respectively.

Hint: Use a final variable to reference EPZPromoLibrary

If you're referencing the shared library more than once, it makes sense to create a final variable you can use to shorten your code a bit. Then, any time you need to reference the library, you can just reference it via the variable:

private final EPZPromoLibrary library = EPZPromoLibrary.getInstance();

Full Code Sample

Below is a full code sample of importing, configuring, and implementing the EPrizeMobileSDK, based on the steps outlined above. Note that this sample is a bare-bones app, and only applicable code is shown for the sake of brevity and clarity.

package com.eprize.mobile.testproject;

import java.util.HashMap;
import java.util.Map;

import android.app.Activity;
import android.os.Bundle;
import android.view.Menu;

import com.eprize.mobile.eprizemobilesdk.EPZPromoLibrary;
import com.eprize.mobile.eprizemobilesdk.EPZPromoLibrary.EPZListener;

public class MainActivity extends Activity implements EPZListener {

        private final EPZPromoLibrary library = EPZPromoLibrary.getInstance();

        @Override
        protected void onCreate(Bundle savedInstanceState) {
                super.onCreate(savedInstanceState);
                setContentView(R.layout.activity_main);
                
                // Create configuration map
                Map<String, Object> configOptions = new HashMap<String, Object>();
                configOptions.put("clientKey", "your_client_key");
                configOptions.put("appContext", this);
                
                // Call configure method
                try {
                    library.configure(configOptions);
                } catch (Exception configException) {
                    // Handle exception
                }
                
                // Set library listener
                library.setListener(this);

                // Fetch promotion configurations
                try {
                    library.fetchPromotionConfigurations();
                } catch (Exception fetchException) {
                    // Handle exception
                }
        }

	@Override
	public void promotionConfigurationsRetrieved(String[] promoKeys) {
		// promoKeys is an array of promotion configuration keys.
                // Use this array as needed to display a promotion, list
                // of promotions, or other call-to-action as needed.
	}

	@Override
	public void promotionConfigurationsFailedWithError(Exception error) {
		// Handle exception
	}

}

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 in your app. To do this, you can simply call the library's launchPromotionForKey() method. This method will create a new activity with a web view and toolbar, and present it automatically, loaded with the given promotion.

String key = library.getPromoKeys()[0];
library.launchPromotionForKey(key);

Alternatively, you can call the library's launchWebViewWithURL() method, passing in a URL to load into the web view instance. This method, like the one above, will create a new activity with a web view and toolbar, and present it automatically, loaded with the given URL.

String customURL = "http://www.eprize.com/";
library.launchWebViewWithURL(customURL);

Class Documentation: EPZPromoLibrary

Overview

The EPZPromoLibrary class is a Singleton class that provides the necessary logic to connect to the ePrize servers. It is the workhorse of the SDK, providing the methods to retrieve and store the full list of promotion configurations.

Since this class is a Singleton, you will not create an instance of it. Rather, you will simply reference it via the getInstance() method in order to access the data stored within the class, and methods to be called from the class.

For instance, to access the array of promotion configuration keys:

EPZPromoLibrary.getInstance().getPromoKeys();

...or to fetch promotion configurations:

EPZPromoLibrary.getInstance().fetchPromotionConfigurations();

Constants

• VERSION (float): The version of the SDK.
• NO_CLIENT_KEY_SET (String): Message attached to configuration exception when no client key is set.
• NO_APP_CONTEXT_SET (String): Message attached to configuration exception when no app context is set.

Public Methods

getInstance

public static synchronized getInstance()

Returns
The singleton library instance.

configure

public void configure(Map<String, Object> options)

Configures the library with options set in the "options" argument. This method must be called before retrieving promotions via the fetchPromotionConfigurations() method.

Parameters
options A map of options used for configuration. Valid options (and their value type) are listed below:

• clientKey (String)  required
  Your client key
• appContext (Context)  required
  A Context of the application package implementing EPZListener.
• toolbarBackground (int)
  A resource id for the web view toolbar background, which should be able to repeat horizontally to stretch and fill the width of the window. The toolbar is shown at the bottom of the web view activity.
  Default: Dark charcoal gray gradient with soft gloss effect.
• closeButton (Button)
  The close button for the web view toolbar, used to close the activity.
  Default: White X icon
• backButton (Button)
  The back button for the web view toolbar, used to navigate back in the web view history (when applicable).
  Default: White left-facing arrow.
• forwardButton (Button)
  The forward button for the web view toolbar, used to navigate forward in the web view history (when applicable).
  Default: White right-facing arrow.
• refreshButton (Button)
  The refresh button for the web view toolbar, used to refresh the web view. This button's visibility is swapped with the loading icon when a web view is loading content.
  Default: White refresh icon.
• loadingIcon (ViewGroup)
  The loading icon for the web view toolbar, used when the web view is loading content. This icon's visibility is swapped with the refresh button after the web view is done loading.
  Default: White spin wing animation.
• toolbarDivider (int)
  A resource id for the web view toolbar dividers.
  Default: Dark hairline with soft white right border.
• dividerVisibility (int)
  A View constant to specify the visibility of the web view toolbar dividers (e.g. View.VISIBLE)
  Default: View.INVISIBLE

promotionConfigurationForKey

public EPZPromoConfiguration promotionConfigurationForKey(String key)

Returns an EPZPromoConfiguration object for the specified configuration key passed in, or null if an invalid configuration key is used.

fetchPromotionConfigurations

public void fetchPromotionConfigurations() throws Exception

Retrieves a list of promotion configurations from the ePrize servers. This method makes an asynchronous request to retrieve a list of promotion configuration keys, using the clientKey value set when configuring the library.

Throws
An exception, if no client key or app context have been set in the library's configure() method.

launchPromotionForKey

public void launchPromotionForKey(String key)

Creates and displays a new EPZPromoWebViewController activity, with the promotion for the specified configuration key loaded into the web view. If the promotion's configuration object has the getOpenInNativeBrowser() value set to true, the device's native browser will be launched rather than using the built-in EPZPromoWebViewController.

Parameters
key A promotion configuration key.

launchWebViewWithURL

public void launchWebViewWithURL(String url)

Creates and displays a new EPZPromoWebViewController activity, with the specified URL loaded into the web view.

Parameters
url The URL to load into the web view.

setListener

public void setListener(EPZListener targetListener)

Sets the listener for the library. The listener that is set must implement the implementation methods.

Parameters
targetListener The listener that implements EPZListener.

getClientKey

public String getClientKey()

Returns the client key value. This is a convenience method to read and return the value of the client key that was set in the configure() method. Note that there is no way to set the client key outside of the configure() method.

getAppContext

public Context getAppContext()

Returns the app context. This is a convenience method to read and return the value of the app context that was set in the configure() method. Note that there is no way to set the app context outside of the configure() method.

getPromotionConfigurations

public Map<Integer, EPZPromoConfiguration> getPromoConfigurations()

Returns a map of promotion configurations, as instances of EPZPromoConfiguration objects.

getPromoKeys

public String[] getPromoKeys()

Returns an array of promotion configuration keys.

getConfigurationsCursor

public Cursor getConfigurationsCursor()

A convenience method that returns a cursor with all configurations. This method may prove to be helpful if you are building a list of all configurations to present to a user, where you can use this Cursor along with a CursorAdapter to set your list adapter. Alternatively, you can create a cursor or similar object manually by looping through all promo configuration keys and retrieving configurations via the promotionConfigurationForKey method.

EPZListener Implementation Methods

promotionConfigurationsRetrieved

public abstract void promotionConfigurationsRetrieved(String[] promoKeys)

Called when promotion configurations are successfully retrieved.

Returns
An array of promotion configuration keys.

Note: This array may be empty, if no current promotions are found for the specified client key. You will be responsible for incorporating logic to determine array length, and add functionality to your app to handle the various scenarios of array length.

promotionConfigurationsFailedWithError

public abstract void promotionConfigurationsFailedWithError(Exception error)

Called when promotion configurations were not successfully retrieved.

Returns
An exception, which contains details on the error.

Note: If the error is due to a lack of Internet connectivity, you will need to take appropriate actions to attempt to retrieve promotion configurations again, as the SDK does not automatically attempt to do so.

webViewDidFireEvent

public abstract void webViewDidFireEvent(String eventName, JSONObject data)

Called when when the SDK's web view catches an event from the web page.

Returns
An event name (String), and a JSONObject of data passed along with the event (may be null).

Note: This method is not presently implemented or called from anywhere within the SDK, but is in place for future releases that will allow full support for website-to-SDK communication.

promoWebViewDidClose

public abstract void promoWebViewDidClose()

Called when when the SDK's web view closes.

pushPreferencesViewDidClose

public abstract void pushPreferencesViewDidClose()

Called when when the SDK's push preference view controller closes.

Note: This method is not presently in use, but is in place for future releases including push notification support.

Class Documentation: EPZPromoConfiguration

Overview

The EPZPromoConfiguration class stores all necessary information specific to a promotion. You can use an instance of this class to gain access to all of the applicable pieces of information you’ll need for reference, display, and functionality.

Public Methods

getConfigKey

public String getConfigKey()

Returns the configuration's key. This key is used to pass in to various methods, such as the EPZPromoLibrary launchPromotionForKey() method.

getConfigType

public String getConfigType()

Returns the promotion’s configuration type. As of version 1.0, the only value for this property is “mobileSdkV1”. This property serves little value outside of the core SDK logic.

getDisplayURL

public String getDisplayURL()

Returns the promotion’s URL, targeted for display. For instance, if a promotion uses a vanity URL, the vanity URL can be the value for this property. Similarly, if a promotion URL has query parameters attached to the URL that are not intended for display, this value may crop off the parameters, resulting in a URL that is more pleasing to the eye.

getEndpointURL

public String getEndpointURL()

Returns the promotion’s full URL. Unlike the display URL, this value may include additional URL information such as query parameters, or a URL that is masked by a vanity URL.

getPromoTitle

public String getPromoTitle()

Returns the promotion's title.

getAssetURLs

public Map<String, String> getAssetURLs()

Returns a Map of the promotion’s asset URLs, as configured in the ePrize Configuration Service.

Important Note: There are no set or default key values for this property, as all asset URLs are the responsibility of the party who configures the promotion in the ePrize Configuration Service. As such, if you choose to use asset URLs, it is recommended to do conditional checks for the existence of any map keys you attempt to use, to avoid null values and/or crashes.

getOpenInNativeBrowser

public Boolean getOpenInNativeBrowser()

Returns a flag alerting whether the site is intended to launch in a device’s native browser. If true, the promotion will launch in the device's native browser rather than in the built-in EPZPromoWebViewController. This logic is handled automatically by the SDK in the launchPromotionForKey() method.

getEndDate

public Date getEndDate()

Returns the promotion’s end date. If you would like to know and/or display the end date for a promotion, you can use this property to get the value, and then use it as necessary.

getLaunchDate

public Date getLaunchDate()

Returns the promotion’s launch date. If you would like to know and/or display the launch date for a promotion, you can use this property to get the value, and then use it as necessary.