Mobile SDK Android

From ePrize Developers Wiki

Current revision

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:

• EPZAnalyticsService
• EPZBusProvider
• EPZPromoLibrary

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

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'

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.demo) - See note below
• App Name (e.g. MobileSDK 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" />

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

Configure the EPZPromoLibrary and Register with Event Bus

To use the EPZPromoLibrary , 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 final EPZPromoLibrary mLibrary = EPZPromoLibrary.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);
    
    // Configure library .
    try {
        mLibrary.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.
    }
}

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
• EPZString
• EPZWebViewFragment

com.eprize.mobile.eprizemobilesdk.events

• EPZAnalyticsEventTrackedEvent
• EPZClosePromoWebViewEvent
• EPZPromotionConfigurationFetchEvent
• EPZPromoWebViewEvent
• EPZPromoWebViewLifecycleEvent
• EPZWebViewCloseWindowEvent
• EPZWebViewCreateWindowEvent
• EPZWebViewOnPageFinishedEvent
• EPZWebViewOnPageStartedEvent