iOs SDK Tutorial

Tutorial

The Koupon Media SDK can act in two modes: (1) a mode that acts as signed URL generator and (2) a mode that allows the SDK to issue network calls on the developer’s behalf. Allowing the SDK to issue the network request often simplifies the logic for getting started. However, more advanced applications may want to manage batched network calls; and the signed URL generator supports these types of apps as well.

Quick Start (Standard SDK Use)

Are you starting your iOS app from scratch? If you want to save time configuring your new project, you can download our starter Xcode project, which is empty except for the pre-loaded Koupon Media SDK.

Once you have configured your application for the Koupon Media SDK, the typical flow of calling SDK functions follows the pattern below.

  1. Register (or re-register) a consumer.
  2. Retrieve the consumer’s offer list.
  3. Mark offers in “Access” state
  4. Mark offers as “Viewed.”
  5. Mark offers as “Presented.”

Register (or Re-register) a Consumer

The code for registering a consumer was introduced in the section “Registering a Consumer,” above. To reiterate, update AppDelegate.m to register the consumer with a CID, email address, mobile number or all three identifiers.

 
//  AppDelegate.m
//  MyKouponSample

#import "AppDelegate.h"

@implementation AppDelegate

@synthesize kouponSDK;

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{   
    //Init the Koupon SDK using the KouponConfiguration.plist file
    kouponSDK = [[Koupon alloc] init];
   [kouponSDK createConsumerIdentity:[NSMutableDictionary dictionary] withOptionalQueryData:nil];

 

Retrieve the Consumer’s Offer List

To retrieve a list of offers for the consumer, call the Koupon Media SDK as follows:

 
// Create a dictionary of filters to pass into 
// the GetConsumerOfferList function.  See the SDK API documentation 
// for a detailed list of filters or visit the Consumer API documentation.

KMRequest *request = [kouponSDK getConsumerOfferList:nil withOptionalQueryData:nil];
[request sendRequestAsyncOnSuccess:^(NSMutableDictionary * response) {
    NSData *jsonData;
    NSString *jsonString;
    if(response) {
        jsonData = [NSJSONSerialization dataWithJSONObject:response options:0 error:nil];
    }
    if(jsonData) {
        jsonString = [[NSString alloc] initWithBytes:[jsonData bytes] length:[jsonData length] encoding:NSUTF8StringEncoding];
    }
    NSLog(@"The response is an NSDictionary containing the JSON response of the Consumer API.  You could convert this dictionary to a JSON object: %@", jsonString);
     
} OnFailure:^(NSMutableDictionary * response) {
}];

 

Mark an Offer in “Access” state

To mark a consumer’s offers as in an “access” state, which helps the Koupon Media system learn about consumer preferences based on what the consumer has or has not accessed, call the Koupon Media SDK as follows:

 
//PromoId is an integer representing the promotion you are trying to update.
KMRequest *kmRedeemRequest = [kouponSDK updateConsumerState:@“ACCESS" forOffer:[NSString stringWithFormat:@"%d",promoId] withOptionalData:nil];[kmRedeemRequest sendRequestAsyncOnSuccess:^(NSMutableDictionary *viewedResp) {
    //The “ACCESS" state returns
    //See the Consumer API documentation for a complete list of all the available properties of this dictionary.
} OnFailure:^(NSMutableDictionary *viewedResp) {
    //Handle Failure
}];

 

Mark an Offer as Viewed

To mark a consumer’s offers as “viewed,” which helps the Koupon Media system learn about consumer preferences based on what the consumer has or has not viewed, call the Koupon Media SDK as follows:

 
//PromoId is an integer representing the promotion you are trying to update.
KMRequest *kmRedeemRequest = [kouponSDK updateConsumerState:@"VIEWED" forOffer:[NSString stringWithFormat:@"%d",promoId] withOptionalData:nil];
[kmRedeemRequest sendRequestAsyncOnSuccess:^(NSMutableDictionary *viewedResp) {
    //The "VIEWED" state returns
    //See the Consumer API documentation for a complete list of all the available properties of this dictionary.
} OnFailure:^(NSMutableDictionary *viewedResp) {
    //Handle Failure
}];

 

Mark an Offer as Presented

Another common task for the Koupon Media SDK is to mark offers as used or “presented.” Note that offers can be configured as single-use or multi-use. When a consumer’s application marks a single-use offer as “presented” (i.e. the barcode has been presented to the screen for scanning), the offer will be removed from his or her offer list. Conversely, multi-use offers will be counted as used, but continue to appear in the offer list until the offer expires.

The following code block demonstrates how to use the Koupon Media SDK to issue a network call for marking an offerID as “presented.”

 
//PromoId is an integer representing the promotion you are trying to update.
KMRequest *kmRedeemRequest = [kouponSDK updateConsumerState:@"PRESENTED" forOffer:[NSString stringWithFormat:@"%d",promoId] withOptionalData:nil];
[kmRedeemRequest sendRequestAsyncOnSuccess:^(NSMutableDictionary *redeemResp) {
    //Handle Success
    //The "PRESENTED" state returns all of the redemption assets
    //See the Consumer API documentation for a complete list of all the available properties of this dictionary.
} OnFailure:^(NSMutableDictionary *redeemResp) {
    //Handle Failure
}];

 

Using the SDK as a URL Generator

The Koupon Media SDK can work within existing network calling mechanics, thus you may find it helpful to utilize the SDK as a URL generator. The signed URLs generated by the SDK can be requested via your own scheme, which is demonstrated by the following code:

 
NSString *signedUrl = [[kouponSDK getConsumerOfferList:nil withOptionalQueryData:nil] url];
    NSLog(@"Generated url from Koupon Media SDK: %@", signedUrl);

// Request this URL from a preferred network request mechanism