|
|
| Line 1: |
Line 1: |
| - | == OS Support == | + | == Summary == |
| | | | |
| - | The [[Mobile_SDK|HelloWorld Mobile SDK]] is built for Android apps targeting <b>API level 14 and higher. </b> | + | The HelloWorld Mobile 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. |
| | | | |
| - | == Version & Release Notes ==
| + | Additionally, version 2.0 of the SDK introduces support for our new Push Notification Service, allowing you the ability to subscribe users to receive push notifications, and allows for the ability for users to fine-tune which types of notifications they will receive via the SDK's built-in push preferences view controller. |
| | | | |
| - | <b>SDK Version:</b> 2.0
| + | == Sample Client Keys for Testing == |
| | | | |
| - | <b>Release Notes:</b>
| + | As you will see in the OS-specific documentation, you will need to configure the HelloWorld Mobile SDK with your public client key in order to retrieve a list of active promotions. Since your organization may not have any active promotions available when developing and integrating the SDK into your mobile app, we have provided three sample client keys: |
| | | | |
| - | * Integration with push notifications
| + | <ul> |
| - | ** Subscribe and unsubscribe from push notifications
| + | <li><b>dev_none</b> <i>(no active promotions)</i></li> |
| - | ** Fetch, set, and save push notification preferences for specific users (including built-in Push Preferences view controller)
| + | <li><b>dev_one</b> <i>(one active promotion)</i></li> |
| - | ** Record actions for specific push notifications
| + | <li><b>dev_multi</b> <i>(more than one active promotion)</i></li> |
| - | * Analytics tracking events
| + | </ul> |
| - | ** 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
| + | |
| | | | |
| - | <div style="margin: 20px 0px; padding:20px; background:#ffd; border:1px solid #ddc;"><i><b>Note on naming:</b> You will notice that the SDK uses the historical company name “ePrize” in the framework name, and “EPZ” for the class namespace. Future releases of the SDK may include updates to these names and namespaces to reflect the new company name, HelloWorld, which was introduced in 2014. </i></div>
| + | While developing, we recommend that you test with all three client keys in an effort to ensure your app is able to handle all of the different scenarios you could encounter when retrieving the list of active promotions: no active promotions, one active promotion, and more than one active promotion. |
| | | | |
| | + | <div style="margin: 20px 0px; padding:20px; background:#ffd; border:1px solid #ddc;"><b>Important Note:</b><br />If you use these sample client keys for testing, be sure to replace it with <span style="text-decoration:underline;">your actual client key</span> before exporting the final release build of your app.</div> |
| | | | |
| - | == Key Concepts == | + | == Documentation == |
| | | | |
| - | === Singleton Classes ===
| + | Presently, HelloWorld offers this SDK for the following operating systems: |
| - | 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:
| + | |
| - | * [[Mobile_SDK_Android:_EPZAnalyticsService|EPZAnalyticsService]]
| + | |
| - | * [[Mobile_SDK_Android:_EPZBusProvider|EPZBusProvider]]
| + | |
| - | * [[Mobile_SDK_Android:_EPZPromoLibrary|EPZPromoLibrary]]
| + | |
| - | * [[Mobile_SDK_Android:_EPZPushNotificationService|EPZPushNotificationService]]
| + | |
| | | | |
| - | Additionally, the SDK includes a class named [[Mobile_SDK_Android:_EPZConstants|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).
| + | <ul> |
| | + | <li>[[Mobile_SDK_iOS|iOS]]</li> |
| | + | <li>[[Mobile_SDK_Android|Android]]</li> |
| | + | </ul> |
| | | | |
| - | === Event Dispatching === | + | == License Agreement == |
| - | 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 [http://square.github.io/otto/ Otto], which the SDK uses to post events. Your app simply needs to register with the [[Mobile_SDK_Android:_EPZBusProvider|EPZBusProvider]] and subscribe to whichever events are applicable for your needs.
| + | |
| | | | |
| - | === Configuration Keys ===
| + | <ul> |
| - | 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 ([[Mobile_SDK_Android:_EPZPromoConfiguration|EPZPromoConfiguration]]). The array of keys is stored in the [[Mobile_SDK_Android:_EPZPromoLibrary|EPZPromoLibrary]] instance for access anywhere in your application.
| + | <li>[http://www.helloworld.com/assets/mobile/HelloWorld%20Mobile%20SDK%20License%20Agreement.pdf Mobile SDK License Agreement]</li> |
| - | | + | </ul> |
| - | | + | |
| - | == 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.
| + | |
| - | | + | |
| - | <div style="margin: 20px 0px; padding:20px; background:#ffd; border:1px solid #ddc;"><i><b>Please note:</b> Using this SDK requires a valid client key provided by HelloWorld. If you wish to integrate with the SDK’s Push Notification Service, you will also need a valid push key. If you do not have a client key and/or push key, please contact your account team or Producer. </i></div> | + | |
| - | | + | |
| - | === 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 ====
| + | |
| - | <ol>
| + | |
| - | <li>Copy the "HelloWorld_MobileSDK-X.X.aar" into your projects "libs" folder, where "X.X" represents the latest version of the library.</li> | + | |
| - | <li>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: </li>
| + | |
| - | <pre>
| + | |
| - | 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
| + | |
| - | }
| + | |
| - | </pre>
| + | |
| - | where "$mSdkVersion" corresponds to the version of the library used.
| + | |
| - | </ol>
| + | |
| - | | + | |
| - | ==== Eclipse Project Setup ====
| + | |
| - | In order to utilize the SDK, you'll need to link to it in your project properties.
| + | |
| - | <ol>
| + | |
| - | <li>Import the EPrizeMobileSDK project into Eclipse.</li>
| + | |
| - | <li>Right-click on your Android application project and select "Properties"</li>
| + | |
| - | <li>Select "Android" in the left side navigation</li>
| + | |
| - | <li>Under the "Library" section of the dialog window, click "Add..." and select EPrizeMobileSDK.</li>
| + | |
| - | </ol>
| + | |
| - | | + | |
| - | <div style="margin: 20px 0px; padding:20px; background:#ffd; border:1px solid #ddc;">
| + | |
| - | When including the SDK into a gradle project, there's most likely going to be included library redundancy. To patch this issue, you can add the following under the Android portion of the gradle file:
| + | |
| - | <pre>
| + | |
| - | dexOptions {
| + | |
| - | preDexLibraries = false
| + | |
| - | }
| + | |
| - | </pre>
| + | |
| - | | + | |
| - | Alternatively, you can fix the issue by not compiling redundant libraries.
| + | |
| - | </div>
| + | |
| - | | + | |
| - | === 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|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.
| + | |
| - | | + | |
| - | <b>Important:</b> You'll also need the Project Number of this project for use when configuring the SDK's [[Mobile_SDK_Android:_EPZPushNotificationService|EPZPushNotificationService]]. In the code samples on this and other pages, this project number is referenced by the constant <b>GCM_SENDER_ID</b>.
| + | |
| - | | + | |
| - | ==== Submit Required Information to HelloWorld ====
| + | |
| - | | + | |
| - | Once you have your project set up in the Google Developers Console as specified above, you will need to <b>submit the following app information to your HelloWorld account team or Producer</b>:
| + | |
| - | | + | |
| - | * App Package <i>(e.g. com.helloworld.mobilesdk.android.pushdemo) <b>- See note below</b></i>
| + | |
| - | * App Name <i>(e.g. MobileSDK Push Demo App)</i>
| + | |
| - | * API Key <i>(e.g. AIzaSyDtlog60M2lxHPAgBci3FU3CiWAlDNR0w8)</i>
| + | |
| - | * Push Key <i>(e.g. push_dev_multi)</i>
| + | |
| - | | + | |
| - | <blockquote style="background:#ffd; border:1px solid #ddc; padding:20px;"><i><b>Important Note:</b>
| + | |
| - | <br /><br />
| + | |
| - | 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 <b>does not</b> 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.
| + | |
| - | <br /><br />
| + | |
| - | In this case, you will need to be sure you include the <b>EPZConstants.CONFIG_KEY_APP_ID</b> key/value pair when you call the [[Mobile_SDK_Android:_EPZPushNotificationService#configure|configure]] method for the [[Mobile_SDK_Android:_EPZPushNotificationService|EPZPushNotificationService]].</i></blockquote>
| + | |
| - | | + | |
| - | == 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):
| + | |
| - | | + | |
| - | <pre>
| + | |
| - | <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" />
| + | |
| - | </pre>
| + | |
| - | | + | |
| - | Include the SDK's built-in activities in the list of activities:
| + | |
| - | | + | |
| - | <pre>
| + | |
| - | <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" />
| + | |
| - | </pre>
| + | |
| - | | + | |
| - | <div style="margin: 20px 0px; padding:20px; background:#ffd; border:1px solid #ddc;"><i><b>Important Note:</b> 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.</i></div>
| + | |
| - | | + | |
| - | And include the receiver and service tags, either using the SDK's [[Mobile_SDK_Android:_EPZBroadcastReceiver|EPZBroadcastReceiver]] and [[Mobile_SDK_Android:_EPZIntentService|EPZIntentService]], or your own BroadcastReceiver and IntentService (which need to extend [[Mobile_SDK_Android:_EPZBroadcastReceiver|EPZBroadcastReceiver]] and [[Mobile_SDK_Android:_EPZIntentService|EPZIntentService]], respectively).
| + | |
| - | | + | |
| - | <pre> | + | |
| - | <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"/>
| + | |
| - | </pre>
| + | |
| - | | + | |
| - | You'll also need to ensure you include the GMS meta-data tag.
| + | |
| - | | + | |
| - | <pre>
| + | |
| - | <meta-data
| + | |
| - | android:name="com.google.android.gms.version"
| + | |
| - | android:value="@integer/google_play_services_version" />
| + | |
| - | </pre>
| + | |
| - | | + | |
| - | === Configure the EPZPromoLibrary and EPZPushNotificationService and Register with Event Bus ===
| + | |
| - | | + | |
| - | To use the [[Mobile_SDK_Android:_EPZPromoLibrary|EPZPromoLibrary]] and [[Mobile_SDK_Android:_EPZPushNotificationService|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 [[Mobile_SDK_Android:_EPZBusProvider|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 [[Mobile_SDK_Android:_EPZConstants|EPZConstants]] class. There are a handful of other key/value pairs you can configure, which are outlined further in the [[#Class_Documentation|Class Documentation]] for each class, respectively.
| + | |
| - | | + | |
| - | <pre>
| + | |
| - | 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);
| + | |
| - | }
| + | |
| - | </pre>
| + | |
| - | | + | |
| - | | + | |
| - | === Fetch Promotion Configurations and Subscribe to Events ===
| + | |
| - | | + | |
| - | Once you have configured the [[Mobile_SDK_Android:_EPZPromoLibrary|EPZPromoLibrary]], you are safe to fetch the promotion configurations via the [[Mobile_SDK_Android:_EPZPromoLibrary#fetchPromotionConfigurations|fetchPromotionConfigurations()]] method.
| + | |
| - | | + | |
| - | <pre>
| + | |
| - | mLibrary.fetchPromotionConfigurations();
| + | |
| - | </pre>
| + | |
| - | | + | |
| - | You will also need to set up a @Subscribe method to handle the [[Mobile_SDK_Android:_EPZPromotionConfigurationFetchEvent|EPZPromotionConfigurationFetchEvent]] dispatched on completion of fetching the configurations.
| + | |
| - | | + | |
| - | <pre>
| + | |
| - | @Subscribe
| + | |
| - | public void handlePromotionConfigurationFetchEvent(EPZPromotionConfigurationFetchEvent event) {
| + | |
| - | if (event.error == null) {
| + | |
| - | // Successfully retrieved promotion configurations.
| + | |
| - | } else {
| + | |
| - | // There was an error fetching configurations - handle as needed.
| + | |
| - | }
| + | |
| - | }
| + | |
| - | </pre>
| + | |
| - | | + | |
| - | | + | |
| - | === 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 [[Mobile_SDK_Android:_EPZPromoConfiguration|EPZPromoConfiguration]] objects and call one of the launch methods in the [[Mobile_SDK_Android:_EPZPromoLibrary|EPZPromoLibrary]].
| + | |
| - | | + | |
| - | <blockquote style="background:#ffd; border:1px solid #ddc; padding:20px;">If you do not wish to use the SDK's built-in [[Mobile_SDK_Android:_EPZPromoWebViewController|EPZPromoWebViewController]], you can use the SDK's [[Mobile_SDK_Android:_EPZWebViewFragment|EPZWebViewFragment]] in your own Activity. For more information on using your own Activity, visit the [[Mobile_SDK_Android:_EPZWebViewFragment|EPZWebViewFragment]] page.</blockquote>
| + | |
| - | | + | |
| - | <pre>
| + | |
| - | if (mLibrary.getPromoKeys() != null && mLibrary.getPromoKeys().length > 0) {
| + | |
| - | EPZPromoConfiguration firstConfig = mLibrary.promotionConfigurationForKey(mLibrary.getPromoKeys()[0]);
| + | |
| - | mLibrary.launchPromotionForKey(firstConfig.getConfigKey());
| + | |
| - | }
| + | |
| - | </pre>
| + | |
| - | | + | |
| - | If you would like to handle any web view or lifecycle events, you can set up a @Subscribe method for the [[Mobile_SDK_Android:_EPZPromoWebViewEvent|EPZPromoWebViewEvent]] and/or the [[Mobile_SDK_Android:_EPZPromoWebViewLifecycleEvent|EPZPromoWebViewLifecycleEvent]].
| + | |
| - | | + | |
| - | <pre>
| + | |
| - | @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.
| + | |
| - | }
| + | |
| - | }
| + | |
| - | </pre>
| + | |
| - | | + | |
| - | === Subscribing and Unsubscribing a User with the EPZPushNotificationService ===
| + | |
| - | | + | |
| - | If you are integrating with the [[Mobile_SDK_Android:_EPZPushNotificationService|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.
| + | |
| - | | + | |
| - | <pre>
| + | |
| - | if (mPushService.isSupported(this)) {
| + | |
| - | if (!mPushService.userIsSubscribed()) {
| + | |
| - | mPushService.subscribeUserDevice();
| + | |
| - | }
| + | |
| - | } else {
| + | |
| - | // Google Play Services unavailable - Push notifications cannot be used on this device.
| + | |
| - | }
| + | |
| - | </pre>
| + | |
| - | | + | |
| - | To handle the subscribe event, set up a @Subscribe method for the [[Mobile_SDK_Android:_EPZPushSubscribeEvent|EPZPushSubscribeEvent]]:
| + | |
| - | | + | |
| - | <pre>
| + | |
| - | @Subscribe
| + | |
| - | public void handlePushSubscribeEvent(EPZPushSubscribeEvent event) {
| + | |
| - | if (event.error != null) {
| + | |
| - | // Handle error as needed
| + | |
| - | } else {
| + | |
| - | // Successfully subscribed user.
| + | |
| - | }
| + | |
| - | }
| + | |
| - | </pre>
| + | |
| - | | + | |
| - | It is advisable to allow a user to unsubscribe from push notifications and the [[Mobile_SDK_Android:_EPZPushNotificationService|EPZPushNotificationService]], as seen in the example below.
| + | |
| - | | + | |
| - | <pre>
| + | |
| - | if (mPushService.userIsSubscribed()) {
| + | |
| - | mPushService.unsubscribeUser();
| + | |
| - | }
| + | |
| - | </pre>
| + | |
| - | | + | |
| - | To handle the unsubscribe event, set up a @Subscribe method for the [[Mobile_SDK_Android:_EPZPushUnsubscribeEvent|EPZPushUnsubscribeEvent]]:
| + | |
| - | | + | |
| - | <pre>
| + | |
| - | @Subscribe
| + | |
| - | public void handlePushUnsubscribeEvent(EPZPushUnsubscribeEvent event) {
| + | |
| - | if (event.error != null) {
| + | |
| - | // Handle error as needed
| + | |
| - | } else {
| + | |
| - | // Successfully unsubscribed user.
| + | |
| - | }
| + | |
| - | }
| + | |
| - | </pre>
| + | |
| - | | + | |
| - | | + | |
| - | === Fetch & Set Push Notification Preferences ===
| + | |
| - | | + | |
| - | If you are integrating with the [[Mobile_SDK_Android:_EPZPushNotificationService|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 [[Mobile_SDK_Android:_EPZPushNotificationService#fetchPushNotificationPreferences|fetchPushNotificationPreferences()]] method, as in the example below.
| + | |
| - | | + | |
| - | <pre>
| + | |
| - | if (mPushService.userIsSubscribed()) {
| + | |
| - | mPushService.fetchPushNotificationPreferences();
| + | |
| - | }
| + | |
| - | </pre>
| + | |
| - | | + | |
| - | To handle the event once push preference fetching is complete, set up a @Subscribe method for the [[Mobile_SDK_Android:_EPZPushPreferencesFetchEvent|EPZPushPreferencesFetchEvent]]:
| + | |
| - | | + | |
| - | <pre>
| + | |
| - | @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).
| + | |
| - | }
| + | |
| - | }
| + | |
| - | </pre>
| + | |
| - | | + | |
| - | Once a user's push notification preferences have been retrieved, you can make use of the SDK's built-in [[Mobile_SDK_Android:_EPZPushPreferencesViewController|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 [[Mobile_SDK_Android:_EPZPushNotificationService|EPZPushNotificationService]]'s [[Mobile_SDK_Android:_EPZPushNotificationService#launchPushPreferencesActivity|launchPushPreferencesActivity()]] method:
| + | |
| - | | + | |
| - | <pre>
| + | |
| - | mPushService.launchPushPreferencesActivity(this);
| + | |
| - | </pre>
| + | |
| - | | + | |
| - | If desired, you can set up a @Subscribe method for the [[Mobile_SDK_Android:_EPZPushPreferencesViewLifecycleEvent|EPZPushPreferencesViewLifecycleEvent]] to respond to [[Mobile_SDK_Android:_EPZPushPreferencesViewController|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.
| + | |
| - | | + | |
| - | <pre>
| + | |
| - | 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();
| + | |
| - | }
| + | |
| - | }
| + | |
| - | }
| + | |
| - | }
| + | |
| - | </pre>
| + | |
| - | | + | |
| - | Additionally, you can set up a @Subscribe method for the [[Mobile_SDK_Android:_EPZPushPreferenceItemsChangedEvent|EPZPushPreferenceItemsChangedEvent]], which is triggered when an individual preference item changes.
| + | |
| - | | + | |
| - | <pre>
| + | |
| - | @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.
| + | |
| - | }
| + | |
| - | </pre>
| + | |
| - | | + | |
| - | === 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 [[Mobile_SDK_Android:_EPZPushNotificationService#savePushNotificationPreferences|savePushNotificationPreferences()]] method, as seen in the example below.
| + | |
| - | | + | |
| - | <pre>
| + | |
| - | if (mPushService.getPushNotificationPreferences() != null) {
| + | |
| - | mPushService.savePushNotificationPreferences();
| + | |
| - | }
| + | |
| - | </pre>
| + | |
| - | | + | |
| - | Additionally, you can set up a @Subscribe method for the [[Mobile_SDK_Android:_EPZPushPreferencesSaveEvent|EPZPushPreferencesSaveEvent]], which is dispatched upon completion of the save method.
| + | |
| - | | + | |
| - | <pre>
| + | |
| - | @Subscribe
| + | |
| - | public void handlePushPreferencesSaveEvent(EPZPushPreferencesSaveEvent event) {
| + | |
| - | if (event.error != null) {
| + | |
| - | // Handle error as needed.
| + | |
| - | } else {
| + | |
| - | // Successfully saved preferences.
| + | |
| - | }
| + | |
| - | }
| + | |
| - | </pre>
| + | |
| - | | + | |
| - | === Handle Push Notification & Retrieve Notification Data ===
| + | |
| - | | + | |
| - | The SDK's [[Mobile_SDK_Android:_EPZBroadcastReceiver|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 [[Mobile_SDK_Android:_EPZBroadcastReceiver|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.
| + | |
| - | | + | |
| - | <b>com.eprize.mobile.eprizemobilesdk</b>
| + | |
| - | :* [[Mobile_SDK_Android:_EPZAnalyticsService|EPZAnalyticsService]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZBroadcastReceiver|EPZBroadcastReceiver]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZBusProvider|EPZBusProvider]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZConstants|EPZConstants]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZIntentService|EPZIntentService]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZPreferenceItem|EPZPreferenceItem]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZPromoConfiguration|EPZPromoConfiguration]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZPromoLibrary|EPZPromoLibrary]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZPromoWebViewController|EPZPromoWebViewController]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZPushNotificationService|EPZPushNotificationService]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZPushPreferencesViewController|EPZPushPreferencesViewController]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZString|EPZString]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZWebViewFragment|EPZWebViewFragment]]
| + | |
| - | | + | |
| - | <b>com.eprize.mobile.eprizemobilesdk.events</b>
| + | |
| - | :* [[Mobile_SDK_Android:_EPZAnalyticsEventTrackedEvent|EPZAnalyticsEventTrackedEvent]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZClosePromoWebViewEvent|EPZClosePromoWebViewEvent]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZPromotionConfigurationFetchEvent|EPZPromotionConfigurationFetchEvent]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZPromoWebViewEvent|EPZPromoWebViewEvent]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZPromoWebViewLifecycleEvent|EPZPromoWebViewLifecycleEvent]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZPushActionEvent|EPZPushActionEvent]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZPushNotificationDataEvent|EPZPushNotificationDataEvent]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZPushPreferenceItemsChangedEvent|EPZPushPreferenceItemsChangedEvent]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZPushPreferencesFetchEvent|EPZPushPreferencesFetchEvent]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZPushPreferencesSaveEvent|EPZPushPreferencesSaveEvent]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZPushPreferencesViewLifecycleEvent|EPZPushPreferencesViewLifecycleEvent]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZPushSubscribeEvent|EPZPushSubscribeEvent]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZPushUnsubscribeEvent|EPZPushUnsubscribeEvent]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZWebViewCloseWindowEvent|EPZWebViewCloseWindowEvent]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZWebViewCreateWindowEvent|EPZWebViewCreateWindowEvent]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZWebViewOnPageFinishedEvent|EPZWebViewOnPageFinishedEvent]]
| + | |
| - | :* [[Mobile_SDK_Android:_EPZWebViewOnPageStartedEvent|EPZWebViewOnPageStartedEvent]]
| + | |
The HelloWorld Mobile 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, version 2.0 of the SDK introduces support for our new Push Notification Service, allowing you the ability to subscribe users to receive push notifications, and allows for the ability for users to fine-tune which types of notifications they will receive via the SDK's built-in push preferences view controller.
As you will see in the OS-specific documentation, you will need to configure the HelloWorld Mobile SDK with your public client key in order to retrieve a list of active promotions. Since your organization may not have any active promotions available when developing and integrating the SDK into your mobile app, we have provided three sample client keys:
While developing, we recommend that you test with all three client keys in an effort to ensure your app is able to handle all of the different scenarios you could encounter when retrieving the list of active promotions: no active promotions, one active promotion, and more than one active promotion.
