iOS API

iOS SDK의 주요 클래스와 메서드 레퍼런스입니다.

AdchainSdk

메인 SDK 클래스 (Singleton).

class AdchainSdk

접근: AdchainSdk.shared

initialize()

func initialize(
    application: UIApplication,
    sdkConfig: AdchainSdkConfig
)

SDK를 초기화합니다. 앱 시작 시 한 번만 호출하며, 비동기로 처리됩니다.

login()

func login(
    adchainSdkUser: AdchainSdkUser,
    listener: AdchainSdkLoginListener? = nil
)

사용자 로그인을 수행합니다. SDK 기능을 사용하기 전에 반드시 로그인해야 합니다.

logout()

func logout()

openOfferwall()

func openOfferwall(
    presentingViewController: UIViewController,
    placementId: String,
    callback: OfferwallCallback? = nil,
    eventCallback: OfferwallEventCallback? = nil
)

기본 오퍼월을 엽니다.

trackEvent()

func trackEvent(
    _ eventName: String,
    payload: [String: Any] = [:]
)

프로퍼티

• func isInitialized() -> Bool - 초기화 상태 확인 (메서드)

• var isLoggedIn: Bool - 로그인 상태

기타 메서드

getCurrentUser()

func getCurrentUser() -> AdchainSdkUser?

현재 로그인된 사용자 정보를 반환합니다.

flushEvents()

func flushEvents()

대기 중인 이벤트를 즉시 서버로 전송합니다.

openOfferwallWithUrl()

커스텀 URL로 오퍼월을 엽니다. 기본 오퍼월 URL이 아닌 특정 URL로 직접 오퍼월을 열어야 할 때 사용합니다.

func openOfferwallWithUrl(
    _ url: String,
    placementId: String,
    presentingViewController: UIViewController,
    callback: OfferwallCallback? = nil,
    eventCallback: OfferwallEventCallback? = nil,
    showNavigationBar: Bool = false,
    useNativeNavigationBar: Bool = false
)

파라미터:

이름	타입	필수	설명
url	String	O	오퍼월로 열 커스텀 URL
placementId	String	O	배치 ID (통계 추적용)
presentingViewController	UIViewController	O	오퍼월을 표시할 뷰 컨트롤러
callback	OfferwallCallback?	X	오퍼월 생명주기 콜백
eventCallback	OfferwallEventCallback?	X	커스텀 이벤트 콜백 (v1.0.41+)
showNavigationBar	Bool	X	커스텀 네비게이션 바 표시 (기본: false)
useNativeNavigationBar	Bool	X	iOS 기본 네비게이션 바 사용 (기본: false)

사용 예시:

AdchainSdk.shared.openOfferwallWithUrl(
    "https://custom-offerwall.example.com/page",
    placementId: "custom_page",
    presentingViewController: self,
    callback: OfferwallCallbackImpl(
        onOpened: { print("열림") },
        onClosed: { print("닫힘") },
        onError: { message in print("에러: \(message)") },
        onRewardEarned: { amount in print("보상: \(amount)") }
    )
)

용도:

• 특정 캠페인 페이지로 직접 이동

• 테스트/스테이징 환경 URL 사용

• 외부 파트너 오퍼월 URL 직접 지정

참고: placementId는 URL에 추가되지 않고 이벤트 추적용으로만 사용됩니다.

openOfferwallNestAds()

func openOfferwallNestAds(
    presentingViewController: UIViewController,
    placementId: String,
    callback: OfferwallCallback? = nil,
    eventCallback: OfferwallEventCallback? = nil,
    showNavigationBar: Bool = false,
    useNativeNavigationBar: Bool = false
)

NestAds placement ID를 사용하여 오퍼월을 엽니다. 서버에서 URL을 가져와 openOfferwallWithUrl()을 호출합니다.

openAdjoeOfferwall()

func openAdjoeOfferwall(
    presentingViewController: UIViewController,
    placementId: String,
    callback: OfferwallCallback? = nil
)

Adjoe 오퍼월을 엽니다 (PlaytimeWeb 사용).

openExternalBrowser()

@discardableResult
func openExternalBrowser(_ url: String, placementId: String) -> Bool

시스템 기본 브라우저에서 URL을 엽니다.

trackCustomEvent()

func trackCustomEvent(
    eventName: String,
    category: String = "custom",
    payload: [String: Any]? = nil
)

커스텀 이벤트를 추적합니다.

getBannerInfo()

func getBannerInfo(
    placementId: String,
    completion: @escaping (Result<BannerInfoResponse, Error>) -> Void
)

배너 정보를 가져옵니다.

getAdvertisingId()

func getAdvertisingId(completion: @escaping (String) -> Void)

광고 ID(IDFA)를 가져옵니다.

setLogLevel() (static)

static func setLogLevel(_ level: LogLevel)

SDK 로그 레벨을 설정합니다. 기본값은 WARNING입니다.

LogLevel:

• .NONE - 로그 없음

• .ERROR - 에러만

• .WARNING - 경고 이상

• .INFO - 정보 이상

• .DEBUG - 디버그 이상

• .VERBOSE - 모든 로그

AdchainSdkConfig

@objc public class AdchainSdkConfig: NSObject {
    @objc public let appKey: String
    @objc public let appSecret: String
    @objc public let environment: Environment
    @objc public let timeoutMillis: Int64
    @objc public let adjoeEnabled: Bool  // deprecated
    @objc public let adjoeSdkHash: String?  // deprecated
}

Builder 패턴

@objc public class Builder: NSObject {
    public init(appKey: String, appSecret: String)

    public func setEnvironment(_ environment: Environment) -> Builder
    public func setTimeoutMillis(_ timeoutMillis: Int64) -> Builder
    public func enableAdjoe(sdkHash: String) -> Builder  // deprecated
    public func disableAdjoe() -> Builder  // deprecated
    public func build() -> AdchainSdkConfig
}

사용 예시:

let config = AdchainSdkConfig.Builder(
    appKey: "YOUR_APP_KEY",
    appSecret: "YOUR_APP_SECRET"
)
.setEnvironment(.production)
.setTimeoutMillis(30000)
.build()

Environment

@objc public enum Environment: Int {
    case production = 0
    case staging = 1
    case development = 2
}

환경:

• .production - 프로덕션 환경

• .staging - 스테이징 환경

• .development - 개발 환경

AdchainSdkUser

@objc public class AdchainSdkUser: NSObject {
    @objc public let userId: String
    public let gender: Gender?
    public let birthYear: Int?

    public init(
        userId: String,
        gender: Gender? = nil,
        birthYear: Int? = nil
    )

    // Objective-C 호환 초기화자
    @objc public convenience init(userId: String)
    @objc public convenience init(userId: String, genderValue: Int, birthYear: Int)
}

Gender

@objc public enum Gender: Int {
    case male = 0
    case female = 1
    case other = 2

    public var stringValue: String  // "M", "F", "O"
}

성별:

• .male - 남성 ("M")

• .female - 여성 ("F")

• .other - 기타/알 수 없음 ("O")

AdchainOfferwallView

public class AdchainOfferwallView: UIView

Native View로 오퍼월을 표시할 수 있습니다 (예: React Native 탭).

메서드:

// placement ID로 오퍼월 로드 (서버에서 URL 가져옴)
func loadOfferwall(placementId: String)

// 직접 URL 지정하여 오퍼월 로드
func loadOfferwall(baseUrl: String, userId: String, appKey: String, placementId: String = "")

// 콜백 설정
func setCallback(_ callback: OfferwallCallback?)

// 이벤트 콜백 설정 (v1.0.41+)
func setEventCallback(_ callback: OfferwallEventCallback?)

Delegate 및 Callback 프로토콜

AdchainSdkLoginListener

로그인 결과를 받는 리스너입니다.

@objc public protocol AdchainSdkLoginListener {
    func onSuccess()
    func onFailure(_ error: AdchainLoginError)
}

OfferwallCallback

오퍼월 이벤트를 받는 콜백입니다.

public protocol OfferwallCallback {
    func onOpened()
    func onClosed()
    func onError(_ message: String)
    func onRewardEarned(_ amount: Int)
}

사용 예시:

AdchainSdk.shared.openOfferwall(
    presentingViewController: self,
    placementId: "main",
    callback: OfferwallCallbackImpl(
        onOpened: {
            print("열림")
        },
        onClosed: {
            print("닫힘")
        },
        onError: { message in
            print("에러: \(message)")
        },
        onRewardEarned: { amount in
            print("보상: \(amount)")
        }
    )
)

OfferwallEventCallback

오퍼월 WebView에서 발생하는 커스텀 이벤트를 받는 콜백입니다 (v1.0.41+).

public protocol OfferwallEventCallback {
    func onCustomEvent(eventType: String, payload: [String: Any])
    func onDataRequest(requestId: String, requestType: String, params: [String: Any]) -> [String: Any]?
}

AdchainQuiz

퀴즈 기능을 제공하는 클래스입니다.

@objc public class AdchainQuiz: NSObject

메서드:

// 인스턴스 생성
@objc public override init()

// 이벤트 리스너 설정
public func setQuizEventsListener(_ listener: AdchainQuizEventsListener)

// 퀴즈 목록 로드
public func load(
    onSuccess: @escaping (QuizResponse) -> Void,
    onFailure: @escaping (AdchainAdError) -> Void,
    shouldStoreCallbacks: Bool = true
)

// 퀴즈 클릭 (ID로)
public func clickQuiz(_ quizId: String, from viewController: UIViewController)

// 퀴즈 클릭 (QuizEvent로)
public func clickQuiz(_ quizEvent: QuizEvent, from viewController: UIViewController)

AdchainQuizEventsListener

protocol AdchainQuizEventsListener: AnyObject {
    func onQuizCompleted(_ quizEvent: QuizEvent, rewardAmount: Int)
}

퀴즈 완료 시 호출됩니다. 이 시점에서 퀴즈 목록을 새로고침해야 합니다.

QuizResponse

struct QuizResponse {
    let success: Bool
    let titleText: String?
    let completedImageUrl: String?
    let completedImageWidth: Int?
    let completedImageHeight: Int?
    let events: [QuizEvent]
    let message: String?
}

QuizEvent

struct QuizEvent {
    let id: String
    let title: String
    let description: String?
    let imageUrl: String
    let point: String
    let landingUrl: String
    let status: String?
    let completed: Bool?
    let impressionOrder: Int?
    let placementId: String?
}

AdchainMission

미션 기능을 제공하는 클래스입니다.

@objc public class AdchainMission: NSObject

메서드:

// 인스턴스 생성
@objc public override init()

// 이벤트 리스너 설정
var eventsListener: AdchainMissionEventsListener?

// 미션 목록 로드
public func load(
    onSuccess: @escaping ([Mission], MissionProgress) -> Void,
    onFailure: @escaping (AdchainAdError) -> Void,
    shouldStoreCallbacks: Bool = true
)

// 미션 클릭 (ID로)
public func clickMission(_ missionId: String, from viewController: UIViewController)

// 미션 클릭 (Mission으로)
public func clickMission(_ mission: Mission, from viewController: UIViewController)

// 보상 수령 버튼 클릭
public func onRewardButtonClicked(from viewController: UIViewController)

AdchainMissionEventsListener

protocol AdchainMissionEventsListener: AnyObject {
    func onCompleted(_ mission: Mission)
    func onProgressed(_ mission: Mission)
    func onRefreshed(unitId: String?)
}

MissionProgress

struct MissionProgress {
    let current: Int       // 완료된 미션 개수
    let total: Int         // 전체 미션 개수
    let percentage: Int    // 완료 비율 (자동 계산)
}

Mission

struct Mission {
    let id: String
    let title: String
    let description: String
    let imageUrl: String
    let landingUrl: String
    let point: String
    let status: String?
    let progress: Int?
    let total: Int?
    let type: MissionType
    let impressionOrder: Int?
    let placementId: String?
}

MissionType

enum MissionType {
    case normal
    case offerwallPromotion
}

AdchainBanner

배너 정보를 가져오는 클래스입니다.

public final class AdchainBanner

접근: AdchainBanner.shared

메서드:

public func getBanner(
    placementId: String,
    onSuccess: @escaping (BannerInfoResponse) -> Void,
    onFailure: @escaping (AdchainAdError) -> Void
)

에러 타입

AdchainLoginError

로그인 관련 에러입니다.

@objc public enum AdchainLoginError: Int {
    case notInitialized = 0
    case invalidUserId = 1
    case networkError = 2
    case unknown = 3

    public var description: String
}

에러 코드:

• notInitialized - SDK가 초기화되지 않음

• invalidUserId - 유효하지 않은 사용자 ID

• networkError - 네트워크 오류

• unknown - 알 수 없는 오류

AdchainAdError

광고(Quiz, Mission, Banner) 관련 에러입니다.

public enum AdchainAdError: Error {
    case notInitialized
    case loadFailed
    case networkError
    case noFill
    case unknown

    public var localizedDescription: String
}

에러 코드:

• notInitialized - SDK가 초기화되지 않음

• loadFailed - 로드 실패

• networkError - 네트워크 오류

• noFill - 사용 가능한 광고 없음

• unknown - 알 수 없는 오류

다음 단계

• Android API

• React Native API