Simpler is better!

1. Overview

This guide shows how to integrate Moduad SDK library and implement In App Purchase in your iphone application. The basic steps to implement In App Purchase with Moduad SDK are following:

Notice) In App Purchase is supported only in iPhone OS 3.0 or above.

2. Registering In App Purchases

2.1. Adding In App Purchases at iTunes Connect
① Create new App ID without wild-card character(*) and enable In App Purchase configuration at iPhone Provisioning Portal. The bundle ID will be used later for application development.

① Join Moduad at http://www.moduad.com and create new application. Application ID and version are used to implement item store with Moduad SDK.

• Enter the same product ID as you created at iTunes Connect.
• Enter the name of In App Purchase.
• Enter the type and the attributes of the type which are additionally provided by Moduad service.
• Enter the icon image of In App Purchase.
• Enter the content file of In App Purchase. The content file will be downloaded after a user buys the In App Purchase item.
• Select either a development (sandbox) environment or a production environment. During development, you should test your application in a sandbox environment, which allows you to test your application without creating financial transactions.
• Enable or disable the item to be displayed in item store.
• Enable or disable the item to be displayed only to test devices. Using this feature with test devices, you can test their virtual goods before available to users. Go to SDK tab menu to add test devices.

⑤ Add the In App Purchase items recursively which you want to show in item store. You can copy or reorder items on the page.

3.2. Adding Moduad SDK Library
In Finder, copy the folder ModuadSDK into the root of your project folder. Include the folder recursively in your project. To do this, right click the project icon in your project explorer, Add --> Existing Files… --> select ModuadSDK --> Add. A dialogue will appear. Choose the following options:

• Uncheck Copy items into destination group…
• Set Reference Type to Default
• Select Recursively create groups for any added folders
• Check project name in Add To Targets box
• Click Add

3.3. Adding Reference Frameworks
The Moduad SDK library uses reference frameworks from iPhone SDK. You have to add the reference of these frameworks in your application. To do this, right click on the Resources folder in your project (if one doesn’t already exist, create it) and select Add --> Existing Frameworks… Select the following frameworks:

• QuartzCore.framework
• SystemConfiguration.framework
• UIKit.framework
• Foundation.framework
• CoreGraphics.framework
• StoreKit.framework

If a dialogue appears select the following options:

• Set Reference Type to Default
• Set Text Encoding to Unicode(UTF-8)
• Check project name in Add To Targets box
• Click Add

These frameworks are normally present at the following path (for iPhone OS 3.0):

• /Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS3.0.sdk/System/Library/Frameworks

3.4. Confiruring Applicaiotn ID and Version
Each application has an application ID and a application version. Both application ID and version are must be configured into your application before you use any other Moduad SDK API. These values can be found in the SDK tab menu of application at Moduad website.

Open the file ModuadConnectKey.h in ModuadSDK folder and set the values of application ID and version for your application. The names of two keys are the following:

• moduadAppID
• moduadAppVersion

NSString* moduadAppID = @"4028808625d4a96d0125d4ccc8500123";
NSString* moduadAppVersion = @"1.0";

3.5. Initializing Connection to Moduad Server
Before you use item store, your application must connect Moduad server and be authorized with application ID and version. You need to create the instance of a shared object ModuadConnect in your application’s delegate class file.

To initialize ModuadConnect, the following two header files need to be imported in your class file.

#import "ModuadConnect.h"
#import "ModuadConnectKey.h"

Then initialize the shared object with singleton method connectModuadServer. This object has to be declared once, so declare it in application’s delegate.

- (void)applicationDidFinishLaunching:(UIApplication *)application {    
     // Connect Moduad server
    [ModuadConnect connectModuadServer];
}

In addition, once the ModuadConnect shard object was initialized, it can be referenced by sharedController method.

moduadConnect = [ModuadConnect sharedConroller];

3.6. Displaying Item Store View
To show the item store in your application, you need to call presentModalViewController with the instance of ModuadConnect as a parameter.

The following header file has to be included in the view controller file.

#import "ModuadConnect.h"

Create the ModuadConnect instance and pass it to presentModalViewController method. Use the following code to display the item store in your view controller file.

ModuadConnect* moduadConnect = [ModuadConnect sharedController];
[self presentModalViewController:moduadConnect animated:YES];

Additionally item store can be set to be displayed in any direction on screen. Use the method setViewDirectionMode defined in ModuadConnect.h.

- (void)setViewDirectionMode:(NSInteger)direction;

Set UI interface orientation before displaying the item store. Four basic orientation modes are supported such as UinterfaceOrientationPortrait, UIInterfaceOrientationLandscapeRight, UIInterfaceOrientationLandscapeLeft, and UIInterfaceOrientationPortraitUpsideDown.

[moduadConnect setViewDirectionMode:UIInterfaceOrientationPortrait];

3.7. Getting the User’s Purchased Items
To retrieve the list of items which a user has purchase in your application, use the getPurchasedModuadItems method defiend in ModuadConnect.h.

- (NSMutableArray *)getPurchasedModuadItems;

Return values are the array of ModuadItem objects. You can query the ModuadItem for its name, attributes, data file location, etc. See ModuadConnect.h for more information about ModuadItem API.

NSArray* myItems = [moduadConnect getPurchasedModuadItems];
for (ModuadItem* myItem in myItems) { … }

3.8 Getting the Information of User’s Virtual Currency (for Virtual Goods)
If you need to get the name of virtual currency or the balance of a user’s virtual currency in any place in your application, you can use the method getModuadCurrency defined in ModuadConnect.h.

- (NSDictionary *)getModuadCurrency;

If you need to get the name of virtual currency or the balance of a user’s virtual currency in any place in your application, you can use the method getModuadCurrency defined in ModuadConnect.h.

• key:@"name" – (NSString) the name of virtual currency
• key:@"balance" – (NSInteger) the balance of a user’s virtual currency

NSDictionary* cash = [moduadConnect getModuadCurrency];

4. Testing In App Purchase in Item Store

4.1. Displaing Items in Item Store
Once item store is implemented in your application, you need to test it on your deivce. Item store will show both virtual goods and In App Purchase items which you added before at Moduad website. Virtual goods can be purchased using virtual currency and In App Purchase items can be purchased at App Store through Store Kit framework. Item store will show the available items and the purchased items separately.

 4.2 Displaying In App Purchase Details
A user can buy In App Purchase at the item details view. The content of In App Purchase will be downloaded after buying.

4.3. Buying an In App Purchase Item
In App Purchase can be tested with a Test User account. Please create a Test User at iTunes Connect.

1. 개요

모두애드에서 제공하는 SDK를 사용하여 아이폰 애플리케이션을 위한 In App Purchase를 구현 가이드이다. 기본 구현 절차는 다음과 같다.

① Moduad 웹사이트에서 회원 가입 후 아이템 호스팅 메뉴에서 신규 애플리케이션을 등록한다. 등록된 애플리케이션의 ID와 버전은 향후 SDK를 이용한 애플리케이션 개발에 사용된다.

• Product ID 항목은 iTunes Connect에서 등록한 Product ID와 동일한 값을 입력한다.
• Name 항목은 상품명으로 이후 iTunes Connect에서 등록한 In App Purchase 명으로 대체되어 표시된다.
• Type 및 Type 속성들은 Moduad에서 별도로 추가적으로 제공하는 기능으로 Moduad SDK의 Item Store에서 표시하기 위한 항목이다.
• Icon은 Moduad SDK의 Item Store에서 표시하기 위한 항목이다.
• Content File은 In App Purchase 상품의 콘텐트 내용을 담은 파일이다. Content 내용은 수정될 수 있으며, Revision 번호로 관리된다.
• Environment는 애플리케이션이 앱스토어에 출시 전 개발 단계에서 In App Purchase를 테스트하기 위해서는 Development(Sandbox) 모드로 설정하고, 상용인 경우에는 Production 모드로 설정한다.
• 추가로 In App Purchase 상품이 Item Store 보여질 지 여부를 설정한다.
• 테스트 목적으로 특정 Device에서만 In App Purchase 상품이 표시되게 설정할 수 있다. (SDK 탭메뉴의 Test Device 등록 참고).

⑤ iTunes Connect에서 등록한 In App Purchase 상품을 반복하여 등록한다. 아래와 같은 목록을 볼 수 있다. 목록 화면에서 아이템 복사와 재정렬 기능을 사용할 수 있다.

3.2. Moduad SDK Library 추가하기
Finder에서 다운받은 ModuadSDK 폴더를 개발하려는 Xcode 프로젝트의 루트 폴더에 복사한다. 해당 프로젝트를 열고, ModuadSDK 폴더를 포함시킨다. 프로젝트 메뉴에서 Add --> Existing Files…  --> select ModuadSDK --> Add 과정을 거친다. 다이얼로그가 표시되면 다음과 같이 옵션을 선택한다.

• Copy items into destination group… 체크를 해지한다.
• Reference Type을 Default로 셋팅한다.
• Recursively create groups for any added folders를 선택한다.
• Add To Targets 박스에서 project name을 체크한다.
• Add를 클릭한다.

3.3. 참조 Framework 추가하기
Moduad SDK 라이브러리는 iPhone SDK에서 제공하는 여러 기본 참조 라이브러리를 사용한다. 따라서 Xcode 프로젝트에서 관련된 참조 라이브러리를 포함시켜야 한다. 프로젝트의 Resources 폴더(없을 경우 생성할 것)에서 오른쪽 마우스를 클릭한 후 Add --> Existing Frameworks... 를 선택한 후 다음과 같은 프레임워크를 포함한다.

• QuartzCore.framework
• SystemConfiguration.framework
• UIKit.framework
• Foundation.framework
• CoreGraphics.framework
• StoreKit.framework

다이얼로그가 표시되면 다음과 같은 옵션을 선택한 후 추가한다.

• Reference Type을 Default로 셋팅한다.
• Text Encoding을 Unicode(UTF-8)로 셋팅한다.
• Add To Targets 박스에서 project name을 체크한다.
• Add를 클릭한다.

이 참조 프레임워크들은 iPhone OS 3.0일 경우에 다음과 같은 경로에서 찾을 수 있다.

• /Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS3.0.sdk/System/Library/Frameworks

3.4. 애플리케이션 ID 및 버전 설정하기
Moduad SDK를 이용하여 애플리케이션을 개발할 경우 Moduad 웹사이트에서 애플리케이션 등록 후 생성된 Applicaion ID와 Version 값을 맞게 설정해야 한다. 이 값들은 Moduad 웹사이트에서 해당 애플리케이션의 SDK 탭메뉴에서 확인할 수 있다.

프로젝트에 추가된 ModuadSDK 라이브러리에 포함된 ModuadConnectKey.h 파일을 열어 다음 2개의 값을 개발자 애플리케이션에 해당하는 값으로 대체하여 설정한다.

• moduadAppID
• moduadAppVersion

설정 예제 코드는 다음과 같다.

NSString* moduadAppID = @"4028808625d4a96d0125d4ccc8500123";
NSString* moduadAppVersion = @"1.0";

3.5. Moduad 서버 연결하기
개발자 애플리케이션에서 Item Store를 이용하기 전에 위에서 설정한 Application ID와 Version을 가지고 Moduad 서버에 연결하여 반드시 인증을 해야 한다. 애플리케이션의 델리게이드 클래스 파일에 ModuadConnect 공유 객체 인스턴스를 생성하고, Moduad 서버에 연결을 하면 된다.

애플리케이션 델리케이드 클래스 파일에 다음과 같이 2개의 헤더 파일을 포함한다.

#import "ModuadConnect.h"
#import "ModuadConnectKey.h"

ModuadConnect의 클래스 메소드인 connectModuadServer로 공유 객체를 초기화한다. 애플리케이션 델리케이드 안에 선언하여 애플리케이션 시작 시에 최초 한번만 수행하면 된다. 샘플 코드는 다음과 같다.

- (void)applicationDidFinishLaunching:(UIApplication *)application {    
     // Connect Moduad server
    [ModuadConnect connectModuadServer];
}

참고로, 한번 초기화된 ModuadConnect 공유 객체를 다시 사용하려면 다음과 같이 sharedController 메소드로 참조할 수 있다.

moduadConnect = [ModuadConnect sharedConroller];

3.6. Item Store 뷰 보이기
애플리케이션 안에서 Item Store 뷰를 보이기 위해서는 보이고자 하는 뷰 컨트롤러에서 초기화된  ModuadConnect 인스턴스를 인자로 하여 presentModalViewController 메소드를 호출하면 된다.

애플리케이션 뷰 컨트롤러 클래스 파일에 다음과 같이 헤더 파일을 포함한다.

#import "ModuadConnect.h"

뷰 컨트롤러에서 Item Store를 보이고자 하는 부분에서 다음과 같은 코드를 사용한다.

ModuadConnect* moduadConnect = [ModuadConnect sharedController];
[self presentModalViewController:moduadConnect animated:YES];

추가로, Moduad Item Store는 가로화면(Landscapre)와 세로화면(Portrait)의 UI를 모두 지원한다. ModuadConnect에 정의된 setViewDirectionMode 메소드를 사용하면 된다.

- (void)setViewDirectionMode:(NSInteger)direction;

이를 설정하기 위해서는 Item Store 뷰를 보이기 전에 다음과 같은 메소드를 통해 설정할 수 있다. 기본 값인 UIInterfaceOrientationPortrait 외에 UIInterfaceOrientationLandscapeRight, UIInterfaceOrientationLandscapeLeft, UIInterfaceOrientationPortraitUpsideDown 4가지 방향을 설정할 수 있다. 사용 예제 코드는 다음과 같다.

[moduadConnect setViewDirectionMode:UIInterfaceOrientationPortrait];

3.7. 구입한 아이템 정보 얻기
Item Store에서 구입 후 다운로드 한 아이템들에 대한 정보를 얻기 위해서는 ModuadConnect에 정의된 getPurchasedModuadItems 메소드를 사용하여 얻을 수 있다.

- (NSMutableArray *)getPurchasedModuadItems;

반환 값은 동일하게 ModuadConnect에 정의된 ModuadItem 객체의 배열로서 반환된다. 다운로드한 아이템의 이름, 아이콘, 속성, 다운로드된 콘텐트 파일 위치 등을 얻을 수 있다 (ModuadItem API를 참조). 사용 예제 코드는 다음과 같다.

NSArray* myItems = [moduadConnect getPurchasedModuadItems];
for (ModuadItem* myItem in myItems) { … }

3.8 사용자의 가상 화폐 정보 얻기 (가상 아이템에서만 사용)
애플리케이션에서 가상 아이템을 구입을 위한 사용자의 가상 화폐 잔고 정보를 얻기 위해서는 ModuadConnect에 정의된 getModuadCurrency 메소드를 사용하여 얻을 수 있다.

- (NSDictionary *)getModuadCurrency;

반환 값은 NSDictionary 객체이고, 다음과 같은 Key를 사용하여 화폐 이름과 금액을 얻을 수 있다.

• key:@"name" – (NSString) 애플케이션에서 사용되는 가상화폐 이름
• key:@"balance" – (NSInteger) 사용자의 가상화폐 잔액

사용 예제 코드는 다음과 같다.

NSDictionary* cash = [moduadConnect getModuadCurrency];

4. Item Store에서 In App Purchase 테스트

4.1. Item Store 아이템 목록
모두애드 SDK에서 기본으로 제공하는 Item Store에서는 가상 아이템 목록과 In App Purchase 목록을 보여주며, 구입 가능한 아이템과 구입을 완료한 목록으로 구분된다. 가상 아이템은 무료 및 가상 화폐 기반으로 구입을 하며, In App Purchase 상품는 애플 iTunes Connect에서 설정한 가격 정보로 Store Kit 프래임워크를 통해서 구입을 하게 된다.

 4.2 In App Purchase 상품 정보
Item Store에서 보여지는 상품 정보는 다음과 같다. 이곳에서 구매 버튼을 클릭하여 해당 아이템을 구매 후 다운로드할 수 있다.

4.3. In App Purchase 상품 구입
애플 iTunes Connect에서 설정한 테스트 개정을 통해 In App Purchase 상품 구입을 테스트해 볼 수 있다.