Mobile SDK Android: EPZPromoLibrary
From ePrize Developers Wiki
Contents |
Overview
The EPZPromoLibrary class is a Singleton class that provides the necessary logic to connect to the HelloWorld 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();
Public Methods
getInstance
public static synchronized EPZPromoLibrary getInstance()
Returns
EPZPromoLibrary singleton library instance.
configure
public void configure(Map<String, Object> options) throws Exception
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:
- EPZConstants.CONFIG_KEY_CLIENT_KEY (String) required
Your client key - EPZConstants.CONFIG_KEY_APP_CONTEXT (Context) required
A Context of the application package. - EPZConstants.CONFIG_KEY_TOOLBAR_BACKGROUND (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. - EPZConstants.CONFIG_KEY_CLOSE_BUTTON (Button)
The close button for the web view toolbar, used to close the activity.
Default: White X icon - EPZConstants.CONFIG_KEY_BACK_BUTTON (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. - EPZConstants.CONFIG_KEY_FORWARD_BUTTON (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. - EPZConstants.CONFIG_KEY_REFRESH_BUTTON (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. - EPZConstants.CONFIG_KEY_LOADING_ICON (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. - EPZConstants.CONFIG_KEY_TOOLBAR_DIVIDER (int)
A resource id for the web view toolbar dividers.
Default: Dark hairline with soft white right border. - EPZConstants.CONFIG_KEY_DIVIDER_VISIBILITY (int)
A View constant to specify the visibility of the web view toolbar dividers (e.g. View.VISIBLE)
Default: View.INVISIBLE
- EPZConstants.CONFIG_KEY_CLIENT_KEY (String) required
Throws
Exception if any required configuration parameters are not specified.
promotionConfigurationForKey
public EPZPromoConfiguration promotionConfigurationForKey(String key)
Parameters
key A String value of a configuration key
Returns
EPZPromoConfiguration object for the specified configuration key passed in, or null if an invalid configuration key is used.
fetchPromotionConfigurations
public void fetchPromotionConfigurations()
Retrieves a list of promotion configurations. This method makes an asynchronous request to retrieve a list of promotion configuration keys, using the clientKey value set when configuring the library.
This method will publish a EPZPromotionConfigurationFetchEvent to the EPZBusProvider, which your application can subscribe to and react accordingly. Note that when subscribing to and handling this event, you should always perform a conditional check to see whether or not the 'error' property is null, and perform your next code decisions accordingly.
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.
The EPZPromoWebViewController will publish the EPZPromoWebViewLifecycleEvent to the EPZBusProvider, which your application can subscribe to and react accordingly. Note that when subscribing to and handling this event, you should always perform a conditional check to see whether or not the error property is null, and perform your next code decisions accordingly.
Additionally, the EPZPromoWebViewController may also publish the EPZPromoWebViewEvent to the EPZBusProvider, which your application can subscribe to and react accordingly. This event is published when the EPZPromoWebViewController catches an event from the web page it has loaded.
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.
The EPZPromoWebViewController will publish the EPZPromoWebViewLifecycleEvent to the EPZBusProvider, which your application can subscribe to and react accordingly. Note that when subscribing to and handling this event, you should always perform a conditional check to see whether or not the error property is null, and perform your next code decisions accordingly.
Additionally, the EPZPromoWebViewController may also publish the EPZPromoWebViewEvent to the EPZBusProvider, which your application can subscribe to and react accordingly. This event is published when the EPZPromoWebViewController catches an event from the web page it has loaded.
Parameters
url The URL to load into the activity's web view.
getClientKey
public String getClientKey()
Returns
String 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
Context 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 SparseArray<EPZPromoConfiguration> getPromoConfigurations()
Returns
SparseArray of promotion configurations, as instances of EPZPromoConfiguration objects.
getPromoKeys
public String[] getPromoKeys()
Returns
String[] of promotion configuration keys.
getConfigurationsCursor
public Cursor getConfigurationsCursor()
Returns
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.
