Mobile SDK iOS

From ePrize Developers Wiki

Revision as of 14:03, 1 May 2013

OS Support

The ePrize Mobile SDK is built for iOS apps targeting iOS 5 and higher.

Getting Started

The ePrize Mobile SDK is designed to be an easy and practical way to retrieve a list of active promotions your organization is running with ePrize, 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.

Key Concepts

Shared Library
This SDK has a class named EPZPromoLibrary, which is a Singleton class that is the workhorse of the SDK. Since it is a Singleton, you will not create instances of it, but rather, will simply reference the sharedLibrary property. As you will see in the code samples, this results in some extra length being added to the lines of code. However, since it is a Singleton, it is shared across your application, so you will never need to create instances of it.

Configuration Keys
This SDK uses a concept of configuration keys to access data and instantiate views. Each active promotion that your organization has with ePrize 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 promo views (EPZPromoWebViewController). The array of keys is stored in the EPZPromoLibrary sharedLibrary for access anywhere in your application.  

Step 1: Obtain the EPrizeMobileSDK

Please contact your account team or Producer to obtain your copy of the ePrize Mobile 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.

Step 2: 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.

Step 3: 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 EPrizeMobileSDK Class Documentation section below for more information about each of the classes included in the SDK.

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.

Step 1: Set Client Key

In your AppDelegate.m file, import the EPrizeMobileSDK and set the client key property for the shared library.

Recommendation: Set this in the application:didFinishLaunchingWithOptions: method.

#import <EPrizeMobileSDK/EPrizeMobileSDK.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    self.window = [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]];

    // Set Client Key - Absolutely required to make calls to retrieve configurations
    [[EPZPromoLibrary sharedLibrary] setClientKey:@"your_client_key"];

    self.viewController = [[ViewController alloc] initWithNibName:@"ViewController" bundle:nil];
    self.window.rootViewController = self.viewController;
    [self.window makeKeyAndVisible];
    return YES;
}

Step 2: Conform to Applicable Delegate Protocols

Wherever you choose to integrate the retrieval of configuration data and present a promotion using the SDK’s built-in web view controller, you will need to conform to the EPZPromoLibraryDelegate and EPZPromoWebViewControllerDelegate protocols, respectively.

#import <EPrizeMobileSDK/EPrizeMobileSDK.h>

@interface ViewController : UIViewController 
<EPZPromoLibraryDelegate, EPZPromoWebViewControllerDelegate>

Step 3: Set Delegate and Fetch Promotion Configurations

When you want to fetch promotion configurations, you will need to set the sharedLibrary delegate and call the fetchPromotionConfigurations method. Additionally, you’ll need to implement the required protocol method promotionConfigurationsRetrieved:, and optionally, the promotionConfigurationsFailedWithError: method.

#import <EPrizeMobileSDK/EPrizeMobileSDK.h>

@implementation ViewController

- (void)viewDidLoad
{
    [super viewDidLoad];
    
    [[EPZPromoLibrary sharedLibrary] setDelegate:self];
    [[EPZPromoLibrary sharedLibrary] fetchPromotionConfigurations];
}
- (void) promotionConfigurationsRetrieved:(NSArray *)promoKeys
{
    // promoKeys is an array of promotion configuration keys.
    // Use this array as needed to display a promotion, list
    // of promotions, or other call-to-action as needed.
}
- (void) promotionConfigurationsFailedWithError:(NSError *)error
{
    // The error param will contain info about the error so 
    // you can handle appropriately.
}

Step 4: 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 make an instance of EPZPromoWebViewController, initializing it with a configuration key. Then set a transition style, set it’s delegate to self, and present it.

(Note: In the code snippet below, “config” is an instance of EPZPromoConfiguration, and utilizes the shared library’s promotionConfigurationForKey: method, as well as referencing the sharedLibrary to get one of the keys from the promoKeys property. For more information on these classes and how to use them, see the class reference documentation for each. For more information on the concept of configuration keys, see Key Concepts section in the Getting Started guide.)

EPZPromoConfiguration *config = [[EPZPromoLibrary sharedLibrary] promotionConfigurationForKey:[[[EPZPromoLibrary sharedLibrary] promoKeys] objectAtIndex:0]];

EPZPromoWebViewController *pvc = [[EPZPromoWebViewController alloc] initWithPromoConfigKey:config.configKey options:nil];

pvc.modalTransitionStyle = UIModalTransitionStyleCoverVertical;

pvc.delegate = self;

[self presentViewController:pvc animated:YES completion:nil];

The EPZPromoWebViewController includes a required delegate method, closePromoView:, which is shown below. It alerts the delegate when the user has clicked on the “Close” button in the web view controller. When this method is called, you should take the necessary steps to hide and remove the instance of EPZPromoWebViewController.

- (void) closePromoView:(EPZPromoWebViewController *)controller
{
    [self dismissViewControllerAnimated:YES completion:nil];
    // Add additional logic here, as necessary.
}

Class Documentation: EPZPromoLibrary

Overview

The EPZPromoLibrary class is a Singleton class that provides the necessary logic to connect to the ePrize servers. It is the workhorse of the SDK, providing the methods to retrieve and store the full list of promotion configurations.

Since this class is a Singleton, you will not create an instance of it. Rather, you will simply reference the sharedLibrary property to access the data (properties) stored within the class, and methods to be called from the class.

For example, to set the client key property:

[[EPZPromoLibrary sharedLibrary] setClientKey: @"your_key_here”];

...or to fetch promotion configurations:

[[EPZPromoLibrary sharedLibrary] fetchPromotionConfigurations];

Tasks

Getting the Shared Library Instance
+ sharedLibrary

Setting and Getting the Delegate
   delegate property

Retrieving Promotion Information
- fetchPromotionConfigurations
- promotionConfigurationForKey:
  promoConfigurations property
  promoKeys property

Launching a Promotion (in device's native browser)
- launchPromotionForKey:

Accessing the Client Key
  clientKey property

SDK Information
  version property

Properties

delegate

The receiver's delegate.

@property (nonatomic, assign) id <[[#Class_Documentation:_EPZPromoLibraryDelegate_Protocol_Reference|EPZPromoLibraryDelegate]]> delegate

Discussion
The delegate is sent messages when server data actions are fired. See EPZPromoLibraryDelegate Protocol Reference for methods this delegate implements.

Availability
Available in version 1.0 and later.

Declared In
EPZPromoLibrary.h

clientKey

The client key used by your application.

@property (nonatomic, copy) NSString *clientKey

Discussion
The client key is used to retrieve the list of promotion configurations from the ePrize servers. This value should be set in your App Delegate (in the application:didFinishLaunchingWithOptions: method, for instance) so it is ready to use anywhere in your code.

Availability
Available in version 1.0 and later.

Declared In
EPZPromoLibrary.h

promoConfigurations

A dictionary of promotion configurations. (read-only)

@property (nonatomic, readonly) NSDictionary *promoConfigurations

Discussion
This property provides a quick and full list of EPZPromoConfiguration objects, each keyed with its configuration’s configKey value. It is a more verbose alternative to the promoKeys property, which simply provides a list of configuration keys.

Availability
Available in version 1.0 and later.

Declared In
EPZPromoLibrary.h

promoKeys

An array of promotion configuration keys. (read-only)

@property (nonatomic, readonly) NSArray *promoKeys

Discussion
This property provides a quick list of configuration keys available. It is a smaller alternative to the promoConfigurations property, which provides a more verbose set of data.

Availability
Available in version 1.0 and later.

Declared In
EPZPromoLibrary.h

version

The version of the EPrizeMobileSDK. (read-only)

@property (nonatomic, readonly) float version

Discussion
This is a convenience property that returns the version number of the EPrizeMobileSDK framework you are using.

Availability
Available in version 1.0 and later.

Declared In
EPZPromoLibrary.h

Class Methods

sharedLibrary

Returns the singleton library instance.

+ ([[#Class_Documentation:_EPZPromoLibrary|EPZPromoLibrary]] *)sharedLibrary

Availability
Available in version 1.0 and later.

Declared In
EPZPromoLibrary.h

Instance Methods

promotionConfigurationForKey:

Returns an instance of the EPZPromoConfiguration object, which contains information relevant to a promotion.

- ([[#Class_Documentation:_EPZPromoConfiguration|EPZPromoConfiguration]] *)promotionConfigurationForKey:(NSString *)key

Parameters
key
One of the configuration keys that is stored in the promoKeys property.

Discussion
This method lets you get an EPZPromoConfiguration object with the key specified as a parameter. It is an easy convenience method to use to get access to a promotion’s configuration data. For more information on the EPZPromoConfiguration object, see the documentation for EPZPromoConfiguration.

Availability
Available in version 1.0 and later.

Declared In
EPZPromoLibrary.h

fetchPromotionConfigurations

Retrieves a list of promotion configurations from the ePrize servers.

- (void)fetchPromotionConfigurations

Discussion
This method makes an asynchronous request to retrieve a list of promotion configuration keys, using the clientKey property value (which should be set in your App Delegate so it is ready to use when needed). Upon completion of the request, one of the EPZPromoLibraryDelegate methods will be called, alerting the delegate of either success or error.

Availability
Available in version 1.0 and later.

Declared In
EPZPromoLibrary.h

launchPromotionForKey:

Calls the openURL method on the parent app’s UIApplication sharedApplication instance.

- (void)launchPromotionForKey:(NSString *)key

Parameters
key
One of the configuration keys that is stored in the promoKeys property.

Discussion
This is a convenience method to easily launch a promotion for a given key, using the device’s default web browser.

Note: It is recommended that you do not use this method, but rather create an instance of EPZPromoWebViewController and this view to your app so the promotion will be viewed while staying in your app. As a safeguard, this method will not complete if the promotion configuration for the specified key has an openInNativeBrowser value of NO.

Availability
Available in version 1.0 and later.

Declared In
EPZPromoLibrary.h

Class Documentation: EPZPromoLibraryDelegate Protocol Reference

Overview

The EPZPromoLibraryDelegate protocol defines methods that a delegate of EPZPromoLibrary can implement to handle actions pertaining to interactions with the class methods.

Tasks

Retrieving Content
- promotionConfigurationsRetrieved: required method
- promotionConfigurationsFailedWithError: optional method

Instance Methods

promotionConfigurationsRetrieved:

Returns a list of promotion configuration keys after successful retrieval.

- (void) promotionConfigurationsRetrieved:(NSArray *)promoKeys

Parameters
promoKeys

Discussion
The delegate responds to the callback method from a successful NSURLConnection to retrieve configuration data.

Availability
Available in version 1.0 and later.

Declared In
EPZPromoLibrary.h

promotionConfigurationsFailedWithError:

Called if retrieving a list of promotion configurations was unsuccessful due to an error.

- (void) promotionConfigurationsFailedWithError:(NSError *)error

Parameters
error

Discussion
The delegate responds to the callback method from an unsuccessful NSURLConnection to retrieve configuration data.

Availability
Available in version 1.0 and later.

Declared In
EPZPromoLibrary.h

Class Documentation: EPZPromoConfiguration

Overview

The EPZPromoConfiguration class stores all necessary information specific to a promotion. You can use an instance of this class to gain access to all of the applicable pieces of information you’ll need for reference, display, and functionality. All properties of this class are read-only.

Note: There is a method named initWithKey:data: which is not meant to be used outside of the core SDK logic, and thus, is not documented below.

Tasks

Getting Promotion Configuration Information
  configKey property
  configType property
  displayURL property
  endpointURL property
  promoTitle property
  assetURLs property
  openInNativeBrowser property
  endDate property
  launchDate property

Properties

configKey

The promotion’s configuration key. (read-only)

@property (nonatomic, readonly) NSString *configKey

Discussion
This property provides a reference to the promotion’s configuration key, which is used in the initialization function of EPZPromoWebViewController. This key is also the same key used to store the EPZPromoConfiguration object in the EPZPromoLibrary promoConfigurations object.

Availability
Available in version 1.0 and later.

Declared In
EPZPromoConfiguration.h

configType

The promotion’s configuration type. (read-only)

@property (nonatomic, readonly) NSString *configType

Discussion
This property provides a reference to the promotion’s configuration type. As of version 1.0, the only value for this property is “mobileSdkV1”. This property serves little value outside of the core SDK logic.

Availability
Available in version 1.0 and later.

Declared In
EPZPromoConfiguration.h

displayURL

The promotion’s URL, formatted for display. (read-only)

@property (nonatomic, readonly) NSString *displayURL

Discussion
This property provides a reference to the promotion’s URL, targeted for display. For instance, if a promotion uses a vanity URL, the vanity URL can be the value for this property. Similarly, if a promotion URL has query parameters attached to the URL that are not intended for display, this value may crop off the parameters, resulting in a URL that is more pleasing to the eye.

Availability
Available in version 1.0 and later.

Declared In
EPZPromoConfiguration.h

endpointURL

The promotion’s full URL. (read-only)

@property (nonatomic, readonly) NSString *endpointURL

Discussion
This property provides a reference to the promotion’s full URL. Unlike the displayURL property, this value may include additional URL information such as query parameters, or a URL that is masked by a vanity URL.

Important Note: This is the value that is loaded into the EPZPromoWebViewController.

Availability
Available in version 1.0 and later.

Declared In
EPZPromoConfiguration.h

promoTitle

The promotion’s title. (read-only)

@property (nonatomic, readonly) NSString *promoTitle

Discussion
This property provides a reference to the promotion’s title.

Availability
Available in version 1.0 and later.

Declared In
EPZPromoConfiguration.h

assetURLs

A list of the promotion’s asset URLs. (read-only)

@property (nonatomic, readonly) NSDictionary *assetURLs

Discussion
This property provides a reference to the promotion’s asset URLs, as configured in the ePrize Configuration Service.

Important Note: There are no set or default key values for this property, as all asset URLs are the responsibility of the party who configures the promotion in the ePrize Configuration Service. As such, if you choose to use asset URLs, it is recommended to do conditional checks for the existence of any dictionary keys you attempt to use, to avoid null values and/or crashes.

Availability
Available in version 1.0 and later.

Declared In
EPZPromoConfiguration.h

openInNativeBrowser

A flag alerting whether the site is intended to launch in a device’s native browser. (read-only)

@property (nonatomic, readonly) BOOL *openInNativeBrowser

Discussion
This property provides a flag to alert you whether the promotion is intended to launch in a device’s native browser. You can check this value before launching a promotion in your app, and if it is set to YES, you can use the EPZPromoLibrary method launchPromotionForKey:, which will open the promotion’s URL in the device’s native browser, rather than in the built-in SDK web view.

Note: In the interest of giving complete control to your application, the SDK does not automatically open a promotion, either in the native browser or by launching an instance of EPZPromoWebViewController. You are responsible for triggering a promotion to be opened by one of these two means.

Availability
Available in version 1.0 and later.

Declared In
EPZPromoConfiguration.h

endDate

The promotion’s end date. (read-only)

@property (nonatomic, readonly) NSDate *endDate

Discussion
This property provides a reference to the promotion’s end date. If you would like to know and/or display the end date for a promotion, you can use this property to get the value, and then use it as necessary.

Availability
Available in version 1.0 and later.

Declared In
EPZPromoConfiguration.h

launchDate

The promotion’s launch date. (read-only)

@property (nonatomic, readonly) NSDate *launchDate

Discussion
This property provides a reference to the promotion’s launch date. If you would like to know and/or display the launch date for a promotion, you can use this property to get the value, and then use it as necessary.

Availability
Available in version 1.0 and later.

Declared In
EPZPromoConfiguration.h

Class Documentation: EPZPromoWebViewController

Overview

The EPZPromoWebViewController class controls the SDK’s built-in web view. To use, you will need to create an instance of this class, and initialize with a promotion configuration key.

Creating a View
To create an instance of EPZPromoWebViewController and add it to your application, you can use code like the following. Note that “config” makes use of the sharedLibrary for both retrieval of a configuration object, and the configuration key used to retrieve this configuration object.

EPZPromoConfiguration *config = [[EPZPromoLibrary sharedLibrary] promotionConfigurationForKey:[[[EPZPromoLibrary sharedLibrary] promoKeys] objectAtIndex:0]];

EPZPromoWebViewController *pvc = [[EPZPromoWebViewController alloc] initWithPromoConfigKey:config.configKey options:nil];

pvc.modalTransitionStyle = UIModalTransitionStyleCoverVertical;

pvc.delegate = self;

[self presentViewController:pvc animated:YES completion:nil];

Tasks

Setting and Getting the Delegate
  delegate property

Initializing
- initWithPromoConfigKey:options:

Properties

delegate

The receiver's delegate.

@property (nonatomic, assign) id <[[#Class_Reference:_EPZPromoWebViewControllerDelegate_Protocol_Reference|EPZPromoWebViewControllerDelegate]]> delegate

Discussion
The delegate is sent messages when the view is created, as well as when it is targeted to close. See EPZPromoWebViewControllerDelegate Protocol Reference for methods this delegate implements.

Availability
Available in version 1.0 and later.

Declared In
EPZPromoWebViewController.h

Instance Methods

initWithPromoConfigKey:options:

Initializes and returns a newly allocated view object with the specified items from the options.

- (id) initWithPromoConfigKey:(NSString *)key options:(NSDictionary *)options

Parameters
key

options

Discussion
This method initializes and returns an instance of EPZPromoWebViewController. Once initialized, this view loads the endpointURL value for the specified promotion configuration key into an instance of UIWebView. The toolbar and its enclosed elements provide the user ways to close the view, refresh a web page, and navigate back and forward in the web page (when applicable).

This view is designed to fill the entire screen of the application, and has appropriate logic to allow for filling the screen even when the device is rotated.

Note: There is intentionally no visible address bar in this view, thus preventing a user from navigating away from the intended web page (and its own internal web links).

Availability
Available in version 1.0 and later.

Declared In
EPZPromoWebViewController.h

Class Reference: EPZPromoWebViewControllerDelegate Protocol Reference

Overview

The EPZPromoWebViewControllerDelegate protocol defines methods that a delegate of EPZPromoWebViewController can implement to handle actions pertaining to interactions with the class methods.

Tasks

Retrieving Content
- closePromoView: required method
- promoViewCreated: optional method

Instance Methods

closePromoView:

Dispatched when the view’s “Close” button is pressed.

- (void) closePromoView:([[#Class_Documentation:_EPZPromoWebViewController|EPZPromoWebViewController]] *)controller

Parameters
controller

Discussion
The delegate responds to a user clicking on the view’s “Close” button, alerting the delegate to take actions to remove the view from the hierarchy.

Availability
Available in version 1.0 and later.

Declared In
EPZPromoWebViewController.h

promoViewCreated:

Called when the EPZPromoWebViewController view is fully created.

- (void) promoViewCreated:(EPZPromoWebViewController *)controller

Parameters
controller

Discussion
The delegate responds to the EPZPromoWebViewController view being successfully and fully created. This method is a convenience method you can use if you desire to know when the view was created, to handle other actions in other parts of your application.

Availability
Available in version 1.0 and later.

Declared In
EPZPromoWebViewController.h