Mobile SDK Android
From ePrize Developers Wiki
Contents |
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 add calls-to-action (buttons, ads, etc.) in your mobile application 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 web view and presented to the user - all while remaining in your application.
Please note: Using this SDK requires a valid client key for ePrize Inc.'s Configuration Service. For more information on the Configuration Service, please refer to the ePrize Configuration Service documentation page.
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: Download the EPrizeMobileSDK
[Insert link to zipped library project here]
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.
- Import the EPrizeMobileSDK project into Eclipse.
- Right-click on your Android application project and select "Properties"
- Select "Android" in the left side navigation
- 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);
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.
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.
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.
