iOS

iOS 앱에 애드체인 SDK를 연동하는 방법을 소개합니다.

시작하기 전에

SDK를 설치하기 전에 다음을 준비해주세요:

• Xcode: 14.0 이상

• iOS: 14.0 이상

• Swift: 5.5 이상

• appKey & appSecret: 애드체인 ADMIN에서 발급받은 인증 정보 ([email protected]로 문의)

1. SDK 설치

SDK를 설치하는 방법은 두 가지가 있습니다. CocoaPods가 익숙하시면 그걸 쓰시고, 아니면 Swift Package Manager를 쓰시면 됩니다.

방법 1: CocoaPods (추천)

프로젝트에 Podfile이 없다면 먼저 만듭니다:

cd 프로젝트경로
pod init

Podfile을 열어서 다음 내용을 추가합니다:

platform :ios, '14.0'

target 'YourAppTarget' do
  use_frameworks!

  # 애드체인 SDK
  pod 'AdChainSDK', '~> 1.0.48'
end

저장하고 설치 실행:

pod install

설치가 끝나면 .xcworkspace 파일로 프로젝트를 열어야 합니다 (.xcodeproj가 아니라).

방법 2: Swift Package Manager (SPM)

Xcode에서:

1. File > Add Packages... 선택

2. 검색창에 입력: https://github.com/1selfworld-labs/adchain-sdk-ios

3. Dependency Rule을 "Up to Next Major Version"으로 설정하고 1.0.48 입력

4. Add Package 클릭

2. Info.plist 설정

Info.plist 파일에 몇 가지 설정을 추가해야 합니다.

App Transport Security

HTTP 통신 허용 (일부 광고에서 필요함):

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

ATT (App Tracking Transparency)

광고 추적 권한 요청 문구:

<key>NSUserTrackingUsageDescription</key>
<string>맞춤형 광고를 제공하기 위해 사용됩니다</string>

문구는 앱 컨셉에 맞게 바꾸셔도 됩니다.

3. SDK 초기화

AppDelegate에서 초기화

SDK는 앱 시작 시 한 번만 초기화합니다. AppDelegate.swift 파일을 열어서:

import UIKit
import AdChainSDK

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

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

        // SDK 설정
        let config = AdchainSdkConfig.Builder(
            appKey: "YOUR_APP_KEY",
            appSecret: "YOUR_APP_SECRET"
        )
        .setEnvironment(.production)
        .build()

        // SDK 초기화 (비동기로 처리됨)
        AdchainSdk.shared.initialize(
            application: application,
            sdkConfig: config
        )

        return true
    }
}

SwiftUI를 쓴다면 App 구조체에서도 비슷하게 할 수 있습니다.

import SwiftUI
import AdChainSDK

@main
struct MyApp: App {
    init() {
        let config = AdchainSdkConfig.Builder(
            appKey: "YOUR_APP_KEY",
            appSecret: "YOUR_APP_SECRET"
        )
        .setEnvironment(.production)
        .build()

        AdchainSdk.shared.initialize(
            application: UIApplication.shared,
            sdkConfig: config
        )
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

초기화 확인하기

SDK 초기화는 백그라운드에서 비동기로 진행됩니다. 초기화 완료 여부는 아래 메서드로 확인할 수 있습니다:

if AdchainSdk.shared.isInitialized() {
    // 초기화 완료 - 로그인 및 다른 기능 사용 가능
} else {
    // 아직 초기화 안 됨 - 서버 검증 진행 중
}

참고: initialize() 호출 직후에는 false일 수 있습니다. 일반적으로 앱 시작 후 1-2초 내에 완료됩니다.

4. ATT 권한 요청

iOS 14.5 이상에서는 광고 추적 권한을 사용자에게 요청해야 합니다. 일반적으로 앱 시작 후 적절한 시점에 요청합니다

import AppTrackingTransparency

func requestTrackingPermission() {
    // iOS 14.5 이상에서만
    if #available(iOS 14.5, *) {
        ATTrackingManager.requestTrackingAuthorization { status in
            switch status {
            case .authorized:
                print("추적 허용됨")
            case .denied:
                print("추적 거부됨")
            case .notDetermined:
                print("아직 결정 안 함")
            case .restricted:
                print("추적 제한됨")
            @unknown default:
                break
            }
        }
    }
}

앱 시작하자마자 띄우면 거부당할 확률이 높으니, 사용자가 어느 정도 앱을 써본 후에 띄우는 게 좋습니다.

5. 사용자 로그인

SDK를 쓰려면 사용자 로그인이 필요합니다:

import AdChainSDK

// 사용자 정보 생성
let user = AdchainSdkUser(
    userId: "user123",         // 앱의 사용자 ID (필수)
    gender: .male,            // 성별 (선택)
    birthYear: 1990           // 출생연도 (선택)
)

// 로그인
AdchainSdk.shared.login(
    adchainSdkUser: user,
    listener: LoginListener()
)

// 로그인 리스너
class LoginListener: AdchainSdkLoginListener {
    func onSuccess() {
        print("로그인 성공")
        // 이제 오퍼월이나 다른 기능 사용 가능
    }

    func onFailure(_ error: AdchainLoginError) {
        print("로그인 실패: \(error.description)")
    }
}

userId는 앱에서 사용하는 사용자 식별자를 사용합니다. 성별이나 출생연도는 선택사항이지만, 제공하면 광고 타겟팅 정확도가 향상됩니다.

로그인 상태 확인하기

로그인 후에는 현재 로그인 상태를 확인할 수 있습니다:

// 로그인 여부 확인
if AdchainSdk.shared.isLoggedIn {
    // 로그인 상태 - 오퍼월 및 다른 기능 사용 가능
} else {
    // 미로그인 상태 - 로그인 필요
}

프로퍼티	타입	설명
isLoggedIn	Bool	로그인 여부

6. 오퍼월 띄우기

이제 오퍼월을 띄워봅시다:

import AdChainSDK

// 버튼 액션에서
@IBAction func showOfferwallTapped(_ sender: Any) {
    AdchainSdk.shared.openOfferwall(
        presentingViewController: self,
        placementId: "main_offerwall",  // 배치 위치 구분용 (선택)
        callback: OfferwallCallbackImpl(
            onOpened: {
                print("오퍼월 열림")
            },
            onClosed: {
                print("오퍼월 닫힘")
            },
            onError: { message in
                print("오퍼월 에러: \(message)")
            },
            onRewardEarned: { amount in
                print("보상 획득: \(amount)")
            }
        )
    )
}

SwiftUI에서는:

struct ContentView: View {
    var body: some View {
        Button("오퍼월 열기") {
            guard let windowScene = UIApplication.shared.connectedScenes.first as? UIWindowScene,
                  let rootViewController = windowScene.windows.first?.rootViewController else {
                return
            }

            AdchainSdk.shared.openOfferwall(
                presentingViewController: rootViewController,
                placementId: "main_offerwall",
                callback: nil  // 콜백은 선택사항
            )
        }
    }
}

오퍼월 호출 전 상태 확인하기

오퍼월을 안전하게 호출하려면 SDK 초기화와 로그인 상태를 먼저 확인하는 것이 좋습니다:

@IBAction func showOfferwallTapped(_ sender: Any) {
    // 1. SDK 초기화 확인
    guard AdchainSdk.shared.isInitialized() else {
        showAlert(message: "SDK 초기화 중입니다")
        return
    }

    // 2. 로그인 상태 확인
    guard AdchainSdk.shared.isLoggedIn else {
        showAlert(message: "로그인이 필요합니다")
        return
    }

    // 3. 오퍼월 열기
    AdchainSdk.shared.openOfferwall(
        presentingViewController: self,
        placementId: "main_offerwall",
        callback: OfferwallCallbackImpl(
            onOpened: { print("오퍼월 열림") },
            onClosed: { print("오퍼월 닫힘") },
            onError: { message in print("오퍼월 에러: \(message)") },
            onRewardEarned: { amount in print("리워드 획득: \(amount)") }
        )
    )
}

SDK 내부에서도 초기화와 로그인 상태를 체크하여 onError 콜백으로 에러 메시지를 전달합니다. 미리 체크하면 더 나은 사용자 경험을 제공할 수 있습니다.

샘플 프로젝트

전체 예제 코드를 보고 싶으시면 GitHub 샘플 프로젝트를 참고하세요:

iOS 샘플: https://github.com/1selfworld-labs/adchain-sdk-ios-sample

샘플 프로젝트에는 UIKit과 SwiftUI 예제가 모두 포함되어 있습니다.

다음 단계

기본 설정이 끝났습니다. 이제 다른 기능들을 써볼 수 있습니다:

• 오퍼월 상세 사용법

• 퀴즈 사용하기

• 미션 사용하기

• 이벤트 추적하기

문제가 생겼다면

초기화나 로그인이 안 된다면 문제 해결 페이지를 확인해보세요.

참고사항

시뮬레이터에서 테스트

시뮬레이터에서도 SDK가 작동하지만, 광고 ID를 가져올 수 없어서 일부 광고가 안 나올 수 있습니다. 제대로 테스트하려면 실제 기기를 쓰는 게 좋습니다.