Mobile SDK iOS

From ePrize Developers Wiki

Current revision

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:

• [EPZAnalyticsService sharedService]
• [EPZPromoLibrary sharedLibrary]

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.demo
App Name: 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.

Set Client Key

In your AppDelegate.m file, set the clientKey property for the sharedLibrary.

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"];
    ...
    return YES;
}

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.
}

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
• EPZString
• EPZWebView
• EPZWebViewDelegate