iOS SDK

Monetai iOS SDK는 앱 내에서 다이나믹 프라이싱과 개인화된 오퍼를 직접 구현할 수 있도록 돕습니다. 이 가이드는 SDK 설치부터 초기화, 이벤트 수집, 다이나믹 프라이싱 구현까지 전 과정을 안내합니다.

사전 요구사항

iOS 13.0 이상
Xcode 12.0 이상

추가 자료

GitHub 저장소: https://github.com/hayanmind/monetai-ios
예제 앱: GitHub 저장소의 Examples 폴더에서 다양한 통합 예제를 확인하세요
- Swift 예제: SwiftPackageManagerExample, CocoaPodsExample
- Objective-C 예제: ObjectiveCExample

언어 지원

Monetai iOS SDK는 Swift와 Objective-C 모두를 지원합니다. 아래 코드 예제에서 프로젝트의 언어에 맞는 탭을 선택하여 사용하세요.

SDK 설정

이 섹션에서는 Monetai SDK를 설치하고, 다이나믹 프라이싱에 필요한 데이터를 수집하도록 구성하는 방법을 안내합니다.
모든 프로모션 기능을 원활하게 사용하려면, 아래의 세 가지 단계를 반드시 진행해 주세요.

1. SDK 설치

Swift Package Manager 또는 CocoaPods를 사용하여 프로젝트에 Monetai iOS SDK를 추가합니다.

Swift Package Manager
CocoaPods

Xcode에서 File > Add Package Dependencies로 이동
저장소 URL 입력: https://github.com/hayanmind/monetai-ios
최신 버전을 선택하고 Add Package 클릭
타겟을 선택하고 Add Package 클릭

Podfile에 다음을 추가합니다:

pod 'MonetaiSDK'

그런 다음 실행:

pod install

2. SDK 초기화

앱이 시작될 때 SDK를 초기화합니다.

Swift
Objective-C

import MonetaiSDK

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    // Monetai SDK 초기화
    Task {
        do {
            let result = try await MonetaiSDK.shared.initialize(
                sdkKey: "YOUR_SDK_KEY", // Monetai 대시보드에서 발급받은 SDK 키
                userId: "USER_ID", // 앱 사용자의 사용자 ID
                useStoreKit2: true // 앱에서 구현한 구매 로직에 따라 StoreKit2 사용 여부 설정
            )

            print("Monetai SDK 초기화 완료:", result)
        } catch {
            print("Monetai SDK 초기화 실패:", error)
        }
    }

    return true
}

API 참조

매개변수

매개변수	타입	설명
sdkKey	string	Monetai에서 발급받은 SDK 키 (Settings > SDK Integration)
userId	string	앱 사용자의 사용자 ID (없을 경우 이메일, 디바이스 ID 등 고유 식별값 활용)
useStoreKit2	boolean?	StoreKit2 사용 여부 (앱에서 구현한 구매 로직에 따라 설정, 기본값: `false`)

반환값

반환값	타입	설명
organizationId	number	조직 ID
platform	'ios'	플랫폼 정보
version	string	SDK 버전
userId	string	설정된 사용자 ID

#import <MonetaiSDK/MonetaiSDK.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // Monetai SDK 초기화
    [[MonetaiSDK shared] initializeWithSdkKey:@"YOUR_SDK_KEY"
                                       userId:@"USER_ID"
                                useStoreKit2:YES
                                   completion:^(InitializeResult * _Nullable result, NSError * _Nullable error) {
        if (error) {
            NSLog(@"Monetai SDK 초기화 실패: %@", error);
        } else {
            NSLog(@"Monetai SDK 초기화 완료: %@", result);
        }
    }];

    return YES;
}

API 참조

매개변수

매개변수	타입	설명
sdkKey	string	Monetai에서 발급받은 SDK 키 (Settings > SDK Integration)
userId	string	앱 사용자의 사용자 ID
useStoreKit2	boolean?	StoreKit2 사용 여부 (앱에서 구현한 구매 로직에 따라 설정, 기본값: `false`)

반환값

반환값	타입	설명
organizationId	number	조직 ID
platform	'ios'	플랫폼 정보
version	string	SDK 버전
userId	string	설정된 사용자 ID

3. 사용자 이벤트 기록

정확한 AI 모델 빌딩을 위한 핵심 단계입니다. Monetai의 AI 모델은 앱에서 보내는 사용자 이벤트를 기반으로 행동을 분석하고, 구매 여부를 예측합니다. 이 데이터가 없으면 구매 예측 기능이 동작하지 않으므로, 반드시 필요한 과정입니다.

Swift
Objective-C

import MonetaiSDK

// 기본 이벤트 로깅
await MonetaiSDK.shared.logEvent(eventName: "app_in")

// 매개변수가 있는 이벤트 로깅
await MonetaiSDK.shared.logEvent(
    eventName: "screen_in",
    params: ["screen": "home"]
)

API 참조

매개변수

매개변수	타입	설명
eventName	string	이벤트 이름
params	object?	이벤트 매개변수 (선택사항)

#import <MonetaiSDK/MonetaiSDK.h>

// 기본 이벤트 로깅
[[MonetaiSDK shared] logEventWithEventName:@"app_in" params:nil];

// 매개변수가 있는 이벤트 로깅
NSDictionary *params = @{
    @"screen": @"home"
};
[[MonetaiSDK shared] logEventWithEventName:@"screen_in" params:params];

API 참조

매개변수

매개변수	타입	설명
eventName	string	이벤트 이름
params	object?	이벤트 매개변수 (선택사항)

이벤트 로깅 Tips

앱에서 수집하는 모든 이벤트를 로깅하면, Monetai가 비구매자 예측에 상관성이 높은 이벤트를 자동으로 선별하여 학습에 활용합니다.
수집중인 이벤트가 없는 경우 앱의 주요 기능이나 버튼, 특히 구매 이전에 발생하는 행동들에 이벤트를 심는 것을 권장합니다.

초기화 전 이벤트 처리

초기화가 완료되기 전에 발생한 이벤트는 큐(Queue)에 저장되었다가, 초기화가 완료된 후 자동으로 전송됩니다.

파라미터 사용 가이드라인

중요: 같은 이벤트 이름이라도 파라미터가 다르면 AI 모델이 별개의 이벤트로 인식합니다. 파라미터 값이 너무 다양하면 모델의 정확도가 떨어질 수 있습니다.

모범 사례:

좋음: ["screen": "home"], ["button": "upgrade"], ["category": "premium"]
피하기: ["timestamp": "2024-01-15T10:30:00Z"], ["userId": "user123"], ["sessionId": "abc123"]

이유: 시간, 사용자 ID, 세션 ID와 같은 파라미터는 매번 고유한 이벤트를 생성하여 모델이 패턴을 찾기 어렵게 만듭니다. 구체적인 인스턴스보다는 사용자 행동 카테고리를 나타내는 파라미터에 집중하세요.

다이나믹 프라이싱 구현

필수 설정이 완료되었습니다. 이 섹션에서는 상품 노출을 기록하고 개인화된 오퍼를 조회하는 방법을 다룹니다.
핵심 워크플로우는: 각 화면에 placement를 정의하고 상품 조회를 기록 → getOffer()로 개인화 오퍼를 조회하는 것입니다.

1. 상품 조회 이벤트 기록

이 단계는 필수입니다. 사용자가 상품(가격 화면)을 조회할 때 logViewProductItem()을 호출하여 노출을 기록합니다. 이 데이터는 Monetai의 오퍼 타게팅 최적화에 필수적이며, 기록하지 않으면 오퍼 개인화가 정상적으로 동작하지 않습니다.

상품별로 각각 로그해야 합니다

프로모션 화면에 여러 개의 상품이 표시되는 경우, 각 상품마다 logViewProductItem()을 개별적으로 호출해야 합니다. 사용자에게 노출된 모든 상품에 대해 각각 로그를 남겨 주세요.

모든 구매 화면

각 상품이 노출되는 화면에 설명적인 placement 값을 정의합니다 (예: main_paywall, special_offer, bottom_banner). 이 데이터는 Monetai가 가격을 최적화하는 데 사용됩니다. 추후 해당 화면에 프로모션을 생성할 때 동일한 placement 값을 프로모션의 placement로 설정하면, 기존에 수집된 데이터가 자동으로 연결됩니다. 이미 대시보드에서 프로모션을 생성했다면 대시보드 → 프로모션 → 프로모션 설정에서 placement 값을 확인할 수 있습니다.

Swift
Objective-C

// 일반 구매 화면에서 기록
await MonetaiSDK.shared.logViewProductItem(
    ViewProductItemParams(
        productId: "premium_monthly",
        price: 9.99,
        regularPrice: 9.99,
        currencyCode: "USD",
        placement: "main_paywall"
    )
)

// 일반 구매 화면에서 기록
ViewProductItemParams *params = [[ViewProductItemParams alloc] initWithProductId:@"premium_monthly"
                                                                           price:9.99
                                                                    regularPrice:9.99
                                                                    currencyCode:@"USD"
                                                                       placement:@"main_paywall"
                                                                           month:nil];
[[MonetaiSDK shared] logViewProductItemWithParams:params];

가격 최적화 화면

getOffer()를 사용하여 Monetai 가격 최적화가 적용된 화면에서는 (다음 섹션 참조) logViewProductItem()과 getOffer()에 동일한 placement 값을 사용합니다.

Swift
Objective-C

import MonetaiSDK

// 사용자가 가격 화면을 볼 때 기록 — 상품별로 각각 호출
await MonetaiSDK.shared.logViewProductItem(
    ViewProductItemParams(
        productId: "premium_monthly",
        price: 4.99,
        regularPrice: 9.99,
        currencyCode: "USD",
        placement: "special_offer"
    )
)

await MonetaiSDK.shared.logViewProductItem(
    ViewProductItemParams(
        productId: "premium_yearly",
        price: 39.99,
        regularPrice: 79.99,
        currencyCode: "USD",
        placement: "special_offer"
    )
)

#import <MonetaiSDK/MonetaiSDK.h>

// 사용자가 가격 화면을 볼 때 기록 — 상품별로 각각 호출
ViewProductItemParams *params1 = [[ViewProductItemParams alloc] initWithProductId:@"premium_monthly"
                                                                            price:4.99
                                                                     regularPrice:9.99
                                                                     currencyCode:@"USD"
                                                                        placement:@"special_offer"
                                                                            month:nil];
[[MonetaiSDK shared] logViewProductItemWithParams:params1];

ViewProductItemParams *params2 = [[ViewProductItemParams alloc] initWithProductId:@"premium_yearly"
                                                                            price:39.99
                                                                     regularPrice:79.99
                                                                     currencyCode:@"USD"
                                                                        placement:@"special_offer"
                                                                            month:nil];
[[MonetaiSDK shared] logViewProductItemWithParams:params2];

API Reference: logViewProductItem()

매개변수 (ViewProductItemParams)

매개변수	타입	Required	설명
placement	String	✓	상품이 노출되는 화면 또는 UI 요소의 식별자 (예: `main_paywall`, `special_offer`, `bottom_banner`). 이미 대시보드에서 프로모션을 생성했다면 대시보드 → 프로모션 → 프로모션 설정에서 placement 값을 확인할 수 있습니다.
productId	String	✓	상품 ID (스토어 상품 ID)
price	Double	✓	표시된 가격 (할인 적용 가격)
regularPrice	Double	✓	정가 (할인 전 가격)
currencyCode	String	✓	통화 코드 (예: `USD`, `KRW`)
month	NSNumber?	-	구독 기간 (개월 수)

2. 오퍼 조회하기

MonetaiSDK.shared.getOffer(placement:)를 호출하여 현재 사용자에게 적용 가능한 개인화된 오퍼를 조회합니다. 할인 대상인 경우 할인 정보와 상품 정보가 포함된 Offer 객체가 반환되며, 대상이 아닌 경우 null이 반환됩니다.

오퍼 활용 방법

오퍼가 반환된 경우: 최적화된 할인율과 상품 정보를 기존 가격/프로모션 화면에 적용합니다.
null이 반환된 경우: 다이나믹 프라이싱 최적화가 적용되지 않는 사용자 그룹입니다. 앱에서 기존에 사용하던 기본 할인가를 그대로 적용하면 됩니다.

오퍼 중복 조회 주의

getOffer()는 호출할 때마다 AI 모델이 최적화한 결과를 반환하므로, 같은 사용자라도 호출 시점에 따라 다른 할인 결과가 반환될 수 있습니다. 프로모션이 활성화된 상태에서 getOffer()를 여러 번 호출하면, 사용자에게 표시되는 할인 상품이 의도치 않게 바뀔 수 있습니다.

발생 시나리오:

사용자가 가격 화면에 진입 → getOffer() 호출 → 30% 할인 표시
사용자가 화면을 나갔다가 다시 진입 → getOffer() 재호출 → 50% 할인 반환
같은 프로모션인데 다른 가격이 표시되어 사용자 혼란 발생

권장 사항: getOffer()는 한 번만 호출하고, 프로모션이 활성화되어 있는 동안 그 결과를 캐싱하여 사용하세요. 화면 진입 시마다 재호출하지 마세요.

하나의 오퍼에 여러 상품이 포함되는 경우

프로모션 페이지에 여러 상품(예: 1개월 플랜, 12개월 플랜)이 있고, 에이전트에 두 상품을 모두 등록한 경우 products에는 각 상품별로 개별 최적화된 결과가 포함됩니다. 예를 들어 1개월과 12개월 상품을 등록했다면, 두 상품 각각에 대해 최적화된 가격이 반환됩니다.

Swift
Objective-C

import MonetaiSDK

func showPricingScreen() async {
    do {
        let offer = try await MonetaiSDK.shared.getOffer(placement: "special_offer")

        if let offer = offer {
            // 오퍼가 있는 경우 — 기존 UI에 할인 적용
            // products에는 등록된 상품별로 최적화된 결과가 포함됨
            print("에이전트:", offer.agentName)
            print("상품:", offer.products)

            for product in offer.products {
                print("SKU: \(product.sku), 할인: \(product.discountRate * 100)%")
            }
        } else {
            // 오퍼 없음 — 기존 기본 할인가 표시
            showDefaultPrice()
        }
    } catch {
        print("오퍼 조회 실패:", error)
        showDefaultPrice()
    }
}

API 참조

매개변수

매개변수	타입	설명
placement	String	가격 최적화를 적용할 화면의 고유 식별자. `logViewProductItem()`에서 정의한 값과 동일하게 사용합니다. 이미 대시보드에서 프로모션을 생성했다면 대시보드 → 프로모션 → 프로모션 설정에서 placement 값을 확인할 수 있습니다.

반환 값: Offer? (대상이 아닌 경우 null)

Offer 타입

속성	타입	설명
agentId	Int	에이전트 ID
agentName	String	에이전트 이름
products	[OfferProduct]	오퍼 상품 목록

OfferProduct 타입

속성	타입	설명
name	String	상품 이름
sku	String	상품 SKU (스토어 상품 ID)
discountRate	Double	할인율 (0-1 범위, 예: 0.5 = 50%)
isManual	Bool	수동 설정 할인 여부

#import <MonetaiSDK/MonetaiSDK.h>

- (void)showPricingScreen {
    [[MonetaiSDK shared] getOfferWithPlacement:@"special_offer"
                                      completion:^(Offer * _Nullable offer, NSError * _Nullable error) {
        if (error) {
            NSLog(@"오퍼 조회 실패: %@", error);
            [self showDefaultPrice];
            return;
        }

        if (offer) {
            // 오퍼가 있는 경우 — 기존 UI에 할인 적용
            NSLog(@"에이전트: %@", offer.agentName);

            for (OfferProduct *product in offer.products) {
                NSLog(@"SKU: %@, 할인: %.0f%%", product.sku, product.discountRate * 100);
            }
        } else {
            // 오퍼 없음 — 기존 기본 할인가 표시
            [self showDefaultPrice];
        }
    }];
}

API 참조

매개변수

매개변수	타입	설명
placement	String	가격 최적화를 적용할 화면의 고유 식별자. `logViewProductItem()`에서 정의한 값과 동일하게 사용합니다. 이미 대시보드에서 프로모션을 생성했다면 대시보드 → 프로모션 → 프로모션 설정에서 placement 값을 확인할 수 있습니다.

반환 값: Offer? (대상이 아닌 경우 null)

Offer 타입

속성	타입	설명
agentId	Int	에이전트 ID
agentName	String	에이전트 이름
products	[OfferProduct]	오퍼 상품 목록

OfferProduct 타입

속성	타입	설명
name	String	상품 이름
sku	String	상품 SKU (스토어 상품 ID)
discountRate	Double	할인율 (0-1 범위, 예: 0.5 = 50%)
isManual	Bool	수동 설정 할인 여부

사용자 상태 관리

SDK 재설정

사용자가 로그아웃할 때 SDK를 초기화합니다.

Swift
Objective-C

import MonetaiSDK

// 사용자가 로그아웃할 때
func logoutUser() {
    MonetaiSDK.shared.reset()
    print("사용자 로그아웃 완료")
}

#import <MonetaiSDK/MonetaiSDK.h>

// 사용자가 로그아웃할 때
- (void)logoutUser {
    [[MonetaiSDK shared] reset];
    NSLog(@"사용자 로그아웃 완료");
}

지원
SDK 연동 중 문제가 발생하면 support@monetai.io로 편하게 문의해 주세요.

다음 단계

SDK 설정이 완료되면 다음 단계를 진행하세요:

프로모션 시작하기

사전 요구사항​

추가 자료​

언어 지원​

SDK 설정​

1. SDK 설치​

2. SDK 초기화​

3. 사용자 이벤트 기록​

다이나믹 프라이싱 구현​

1. 상품 조회 이벤트 기록​

모든 구매 화면​

가격 최적화 화면​

2. 오퍼 조회하기​

사용자 상태 관리​

SDK 재설정​

다음 단계​

사전 요구사항

추가 자료

언어 지원

SDK 설정

1. SDK 설치

2. SDK 초기화

3. 사용자 이벤트 기록

다이나믹 프라이싱 구현

1. 상품 조회 이벤트 기록

모든 구매 화면

가격 최적화 화면

2. 오퍼 조회하기

사용자 상태 관리

SDK 재설정

다음 단계