Mobile SDK iOS
From ePrize Developers Wiki
Contents |
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.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.
