Mobile SDK iOS

From ePrize Developers Wiki

Revision as of 15:20, 7 November 2014

OS Support

The HelloWorld Mobile SDK is built for iOS apps targeting iOS 6 and higher.

Version & Release Notes

SDK Version: 2.0

Release Notes:

• Integration with push notifications
  • Subscribe and unsubscribe from push notifications
  • Fetch, set, and save push notification preferences for specific users (including built-in Push Preferences view controller)
  • Record actions for specific push notifications
• Analytics tracking events
  • 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
  • Delegate (and methods) in Singleton classes replaced with block callbacks

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:

• [EPZAnalyticsService sharedService]
• [EPZPromoLibrary sharedLibrary]
• [EPZPushNotificationService sharedService]

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.

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.

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 Build Phases tab in your project’s target. Under “Link Binary With Libraries”, click the “+” button and select “Add Other” from the dialog box. Navigate to the EPrizeMobileSDK.framework directory you saved from step 1 above, and click “Open”. The EPrizeMobileSDK 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.

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 App ID

In the Apple Developer Center, you will need to create an explicit App ID for your application. You will need to make sure that you enable the Push Notifications service under the "App Services" section of the App ID generation process.

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.

Create a PEM File

Once you have your Certificate and private key as a .p12 file, you need to convert them into a more usable format. To do this, launch Terminal, navigate to the directory where both files are saved, and follow the steps below. (Note: The filenames used in the code snippets may differ depending on whether you are using the development or production certificate, depending on what you named your private key .p12 file, and what you would like to name your PEM files.)

Convert the .cer file into a .pem file

openssl x509 -in aps_development.cer -inform der -out MyDevCert.pem

Convert private key .p12 file into a .pem file

openssl pkcs12 -nocerts -out MyDevKey.pem -in MyDevKey.p12 -nodes

Combine certificate and key files into one .pem file

cat MyDevCert.pem MyDevKey.pem > MyCombinedDevCertAndKey.pem

Submit Required Information to HelloWorld

Once you have the combined PEM file as specified above, create an archive ZIP file of the PEM file along with a plain text file that includes your App Bundle ID, App Name, and Push Key (see sample below). Submit this ZIP file to your HelloWorld account team or Producer.

Sample Text File

App Bundle ID: com.helloworld.mobilesdk.pushdemo
App Name: MobileSDK Push Demo App
Push Key: push_dev_multi

Important Note:

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 Bundle ID for each. The app bundle ID value is used as a unique identifier for your app in the Push Notification Service back-end. As such, using the same bundle ID value for development/testing and the final production app will cause issues with sending push notifications to devices that are using your application. In this case, you will need to submit the above information for both versions of your 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.

• EPZAnalyticsService
• EPZConstants
• EPZPromoConfiguration
• EPZPromoLibrary
• EPZPromoWebViewController
• EPZPromoWebViewControllerDelegate
• EPZPushNotificationService
• EPZPushPreferenceItem
• EPZPushPreferencesViewController
• EPZPushPreferencesViewControllerDelegate
• EPZString
• EPZWebView
• EPZWebViewDelegate