Mobile SDK iOS
From ePrize Developers Wiki
OS Support
The HelloWorld Mobile SDK is built for iOS apps targeting iOS 6 and higher.
Version & Release Notes
SDK Version: 2.1
Release Notes:
- Performance and bug fixes
Key Concepts
Singleton Classes
The SDK includes a number of Singleton classes which you will not create instances of, but rather, can simply reference the shared Singleton property for each respective class. The Singleton classes/properties used in the SDK include:
Callback Blocks
Version 2.0 of this SDK includes a major shift in the callback logic used. Where version 1.0 used delegates as the primary method of implementing callbacks from the SDK, version 2.0 introduces blocks as the main callback method for the majority of public methods in all Singleton classes. As you will see in the class-specific documentation, there are block arguments for all methods which utilize blocks as the callback methods. This said, there are still instances of delegates and delegate methods, namely in the SDK's built-in view controllers.
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), and to instantiate the SDK's built-in web view controller (EPZPromoWebViewController). The array of keys is stored in the EPZPromoLibrary sharedLibrary 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.
Please note: It is highly recommended that you save the framework to a specific and static location on your computer (e.g. a location where you save other third-party SDKs and frameworks). This can allow you to better use the framework across multiple projects, if needed.
Include framework into your project
In your application’s project navigator, click on the General tab in your project’s target. Under “Embedded Binaries”, click the “+” button and select “Add Other” from the dialog box. Navigate to the HWMobileSDK.framework directory you saved from step 1 above, and click “Open”. The HWMobileSDK framework is now included in your project and ready to use.
Import framework as necessary
In any class file that needs to utilize the SDK, you will need to import the framework files. You can consult the various Class Documentation sections for more information about each of the classes included in the SDK.
Create App ID
In the Apple Developer Center, you will need to create an explicit App ID for your application.
Create Certificate & Export Private Key
Once you have created your App ID, you will need to create a certificate which you will need to link to the App ID created in the previous step. After you have generated and downloaded the certificate, make sure you double-click the downloaded file to add to Keychain Access. Then, in Keychain Access, find the new private key created, right-click it, and choose the "Export" option. Save the private key as a .p12 file.
Create Provisioning Profile
You will also need to make sure you set up a valid provisioning profile for your application in the Apple Developer Center, complete with the applicable App ID and certificates.
Submit Required Information to HelloWorld
Submit a plain text file that includes your App Bundle ID and App Name (see sample below). Submit this file to your HelloWorld account team or Producer.
- Sample Text File
App Bundle ID: com.helloworld.mobilesdk.pushdemo App Name: MobileSDK Push 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.
Set Client and Push Keys
In your AppDelegate.m file, set the clientKey property for the sharedLibrary. If you are integrating with the EPZPushNotificationService, you will also need to set the pushKey property for the sharedService, as well as call the registerForRemoteNotificationTypes: method on the shared UIApplication.
Recommendation: Set this in the application:didFinishLaunchingWithOptions: method.
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
...
// Set Client Key - Absolutely required to integrate with the SDK
[[EPZPromoLibrary sharedLibrary] setClientKey:@"your_client_key"];
// Set Push Key - Required if integrating with the SDK's Push Notification Service
[[EPZPushNotificationService sharedService] setPushKey:@"your_push_key"];
// Register for push notifications, if integrating with the SDK's Push Notification Service
if ([UIDevice currentDevice].systemVersion.floatValue >= 8.0) {
[[UIApplication sharedApplication] registerUserNotificationSettings:[UIUserNotificationSettings settingsForTypes:(UIUserNotificationTypeSound | UIUserNotificationTypeAlert | UIUserNotificationTypeBadge) categories:nil]];
[[UIApplication sharedApplication] registerForRemoteNotifications];
} else {
[[UIApplication sharedApplication] registerForRemoteNotificationTypes:(UIRemoteNotificationTypeSound|UIRemoteNotificationTypeBadge|UIRemoteNotificationTypeAlert)];
}
...
return YES;
}
If you have requested different Push Keys for development/testing and the final production release, you will need to set the appID value for the EPZPushNotificationService. It is advisable in such an instance to set your Push Key and App ID dynamically, as in the code sample below:
#ifdef DEBUG
[[EPZPushNotificationService sharedService] setPushKey:@"your_dev_push_key"];
[[EPZPushNotificationService sharedService] setAppID:@"com.helloworld.pushdemo.dev"];
#else
[[EPZPushNotificationService sharedService] setPushKey:@"your_prod_push_key"];
[[EPZPushNotificationService sharedService] setAppID:@"com.helloworld.pushdemo.prod"];
#endif
Fetch Promotion Configurations
When you want to fetch promotion configurations, you will need to pass in a block that will be triggered when the fetchPromotionConfigurations: method is complete. Since the same block callback is used for both success and error events, it is advisable to implement a conditional check for the error object in your callback block, like in the code sample below.
For more information on fetching promotion configurations, consult the fetchPromotionConfigurations: method documentation.
[[EPZPromoLibrary sharedLibrary] fetchPromotionConfigurations:^(NSArray *data, NSError *error) {
if (error) {
// Handle error as needed.
} else {
// Successfully retrieved promotion configurations.
}
}];
Launching and Closing 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, you need to create an instance of EPZPromoWebViewController and add it to your application, similar to the following code sample. Note that "config" makes use of the sharedLibrary to retrieve the EPZPromoConfiguration object, and the configuration's configKey is in turn used to initialize the EPZPromoWebViewController.
For more information, you can consult the documentation for EPZPromoWebViewController and EPZPromoWebViewControllerDelegate
// Get first promotion configuration object EPZPromoConfiguration *config = [[EPZPromoLibrary sharedLibrary] promotionConfigurationForKey:[[[EPZPromoLibrary sharedLibrary] promoKeys] objectAtIndex:0]]; // Create instance of the view controller EPZPromoWebViewController *pvc = [[EPZPromoWebViewController alloc] initWithPromoConfigKey:config.configKey options:nil]; // Set delegate pvc.delegate = self; // Present view controller [self presentViewController:pvc animated:YES completion:nil];
You will need to conform to the EPZPromoWebViewControllerDelegate protocol, in which one method is required to implement, as seen below. This method alerts the delegate when the user has clicked on the “Close” button in the EPZPromoWebViewController. When this method is called, you should take the necessary steps to hide and remove the instance of the view controller.
- (void) closePromoWebView:(EPZPromoWebViewController *)controller
{
[self dismissViewControllerAnimated:YES completion:nil];
// Add additional logic here, as necessary.
}
Subscribing and Unsubscribing a User with the EPZPushNotificationService
If you are integrating with the EPZPushNotificationService, you will also want to handle subscribing the user's device in the application:didRegisterForRemoteNotificationsWithDeviceToken: method, as seen in the following code sample. Note that the subscribeUserWithDeviceToken:callback: method is surrounded by a conditional check, and only called if the device is not already subscribed. While not necessary, it saves the need to call this method every time the application launches.
// AppDelegate.m
- (void) application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken
{
if (![EPZPushNotificationService sharedService].userIsSubscribed) {
[[EPZPushNotificationService sharedService] subscribeUserWithDeviceToken:deviceToken callback:^(NSError *error) {
if (error) {
// Error subscribing user. Handle error as needed.
} else {
// User successfully subscribed. Safe to call the fetchPushNotificationPreferences: method
}
}];
}
}
It is advisable to allow a user to unsubscribe from push notifications and the EPZPushNotificationService. As such, you may need to call the unsubscribeUser: method, as seen in the example below.
Note that, like the subscribe example above, the unsubscribeUser: method is surrounded by a conditional check, and only called if the user is subscribed.
if ([EPZPushNotificationService sharedService].userIsSubscribed) {
[[EPZPushNotificationService sharedService] unsubscribeUser:^(NSError *error) {
if (error) {
// Error unsubscribing user. Handle error as needed.
} else {
// User successfully unsubscribed.
}
}];
}
Fetch & Set Push Notification Preferences
If you are integrating with the 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 fetchPushNotificationPreferences: method, as in the example below. Note that since the block callback is used for both success and error events, it is advisable to implement a conditional check for the error object in your callback block.
[[EPZPushNotificationService sharedService] fetchPushNotificationPreferences:^(NSDictionary *data, NSError *error) {
if (error) {
// Handle error as needed.
} else {
// Successfully retrieved push notification preferences.
}
}];
Once a user's push notification preferences have been retrieved, you can make use of the SDK's built-in 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 will implement logic similar to creating and displaying an instance of the EPZPromoWebViewController, as documented above.
For more information, you can consult the EPZPushPreferencesViewController and EPZPushPreferencesViewControllerDelegate documentation pages.
// Create instance of the view controller EPZPushPreferencesViewController *pvc = [EPZPushPreferencesViewController pushPreferencesViewControllerWithOptions:nil]; // Set delegate pvc.delegate = self; // Present view controller [self presentViewController:pvc animated:YES completion:nil];
Save Push Preferences
If a user chooses to update their push notification preferences, you'll want to save them on behalf of the user. To do this, you can make use of the savePushNotificationPreferences: method, as seen in the example below.
For more information, you can consult the savePushNotificationPreferences: documentation.
[[EPZPushNotificationService sharedService] savePushNotificationPreferences:^(NSError *error) {
if (error) {
// Handle error as needed.
} else {
// Successfully saved push notification preferences.
}
}];
Handle Push Notification & Retrieve Notification Data
If you are integrating with the EPZPushNotificationService, you will want to implement logic in the application:didReceiveRemoteNotification: method to handle the notification.
For the initial notification payload, a very light set of data is included, which includes a unique remote payload ID value that is needed to retrieve the full set of notification data from the HelloWorld Push Notification Service. The code sample below shows an example of a simple implementation of handling and retrieving full notification data via the fetchAdditionalNotificationDataForPayloadID:callback: method. Like other methods, since the block callback is used for both success and error events, it is advisable to implement a conditional check for the error object in your callback block.
For more information on fetching and handling additional notification data, you can consult the documentation for the fetchAdditionalNotificationDataForPayloadID:callback: method.
Additionally, you can consult the documentation on the recordActionForPushNotificationID:withValue:forAction:callback: method, which offers the ability to record action(s) taken on a specific notification for reporting purposes.
- (void) application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
{
// Check notification userInfo for remote payload ID and fetch additional notification data, if found.
NSString *remotePayloadID = [[userInfo objectForKey:EPZ] objectForKey:EPZ_PUSH_KEY_PAYLOAD_ID];
if (remotePayloadID) {
[[EPZPushNotificationService sharedService] fetchAdditionalNotificationDataForPayloadID:remotePayloadId callback:^(NSDictionary *data, NSError *error) {
if (error) {
// Handle error as needed.
} else {
// Additional notification data successfully retrieved. Handle data 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.
