오퍼월 광고

아래 가이드에서는 Offerwall 광고를 통합하고 표시하는 방법을 설명합니다.

기본 요건

시작 가이드에 따라 필요한 과정을 완료합니다.

추가 요구사항:

• NestAdsSDK v2.7.7 이상 ~ v2.8.0 미만 (v2.7.8에서 Quiz, Mission 지원)

• NestAdsOfferwallSDK v1.0.0 이상 (v1.0.0에서 Quiz, Mission 지원)

---

설치

Swift Package Manager

NestAdsOfferwallSDK를 프로젝트에 추가합니다:

1. Xcode에서 File → Add Package Dependencies... 선택

2. 검색창에 URL 입력:

   https://github.com/wisebirds/nestads-offerwall-ios-sdk

3. 버전 선택: 1.0.0 이상

또는 Package.swift에 직접 추가:

dependencies: [
    .package(url: "https://github.com/wisebirds/nestads-ios-sdk", .upToNextMinor(from: "2.7.7")),
    .package(url: "https://github.com/wisebirds/nestads-offerwall-ios-sdk", from: "1.0.0")
]

---

테스트 광고 게재위치

Placement Code(게재위치 코드)는 어드민의 인벤토리 > 게재위치 메뉴에서 게재위치를 등록 시 시스템을 통해 자동으로 생성됩니다.

---

Offerwall 통합하기

1. AppDelegate에서 초기화

Offerwall SDK를 사용하려면 AppDelegate에서 OfferwallConfig를 통해 초기화해야 합니다.

중요: AppDelegate에서 반드시 import NestAdsOfferwallSDK를 추가해야 합니다. 이것이 없으면 런타임에 SDK를 찾을 수 없습니다.

Swift

import UIKit
import NestAdsSDK
import NestAdsOfferwallSDK  // ⚠️ 필수!

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

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

        // 1. Offerwall 설정 생성
        let offerwallConfig = OfferwallConfig(
            application: application,
            appKey: "YOUR_APP_KEY",      // 앱 키
            appSecret: "YOUR_APP_SECRET", // 앱 시크릿
            timeoutMillis: 30000  // 선택사항: 타임아웃 설정 (밀리초)
        )

        // 2. NestAds 초기화 (Offerwall 설정 포함)
        NestAds.sharedInstance().start(offerwallConfig: offerwallConfig)

        return true
    }
}

appKey, appSecret 은 발급 과정이 필요합니다. 담당자에게 문의 부탁드립니다.

---

2. 사용자 로그인

Offerwall을 표시하기 전에 반드시 사용자 로그인을 완료해야 합니다.

Swift

import NestAdsSDK

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()

        // 사용자 로그인 (Offerwall 사용 전 필수)
        // userId만 필수이고, gender와 birthYear는 선택사항입니다

        // 방법 1: 최소 정보만 (userId만)
        NestAds.Offerwall.login(userId: "user_12345")

        // 방법 2: userId + gender
        // NestAds.Offerwall.login(
        //     userId: "user_12345",
        //     gender: NestAdsGenderMale
        // )

        // 방법 3: 모든 정보 포함 (타겟 광고에 활용)
        // NestAds.Offerwall.login(
        //     userId: "user_12345",
        //     gender: NestAdsGenderMale,
        //     birthYear: 1990
        // )

        // 로그인 확인
        DispatchQueue.main.asyncAfter(deadline: .now() + 1.0) {
            if NestAds.Offerwall.isLoggedIn {
                print("✅ 로그인 성공: \(NestAds.Offerwall.currentUserId)")
            }
        }
    }
}

파라미터 설명:

• userId - [필수] 사용자 고유 ID

• gender - [선택] 성별. Gender 상수 사용 권장

  • NestAdsGenderUnknown (0) - 알 수 없음 (기본값)

  • NestAdsGenderMale (1) - 남성

  • NestAdsGenderFemale (2) - 여성

• birthYear - [선택] 출생 연도. 타겟 광고 최적화에 활용됩니다.

---

3. Offerwall 표시하기

로그인 완료 후 원하는 시점에 Offerwall을 표시할 수 있습니다.

Swift

import NestAdsSDK
import NestAdsOfferwallSDK

class RewardViewController: UIViewController {

    @IBAction func showOfferwallButtonTapped(_ sender: UIButton) {
        // 로그인 확인
        guard NestAds.Offerwall.isLoggedIn else {
            showLoginAlert()
            return
        }

        // Offerwall 표시
        NestAds.Offerwall.openOfferwall(
            from: self,
            placementCode: "YOUR_PLACEMENT_CODE",
            showNavigationBar: false,        // 선택: 네비게이션 바 표시 여부
            useNativeNavigationBar: false,   // 선택: 네이티브 네비게이션 바 사용 여부
            delegate: self                   // 선택: 이벤트 수신
        )
    }

    private func showLoginAlert() {
        let alert = UIAlertController(
            title: "로그인 필요",
            message: "Offerwall을 사용하려면 로그인이 필요합니다",
            preferredStyle: .alert
        )
        alert.addAction(UIAlertAction(title: "확인", style: .default))
        present(alert, animated: true)
    }
}

---

4. Delegate 이벤트 처리

Offerwall의 이벤트를 수신하려면 NestAdsOfferwallDelegate를 구현합니다.

Swift

import NestAdsOfferwallSDK

extension RewardViewController: NestAdsOfferwallDelegate {

    // Offerwall이 열렸을 때
    func offerwallDidOpen() {
        print("✅ Offerwall 열림")
    }

    // Offerwall이 닫혔을 때
    func offerwallDidClose() {
        print("✅ Offerwall 닫힘")
    }

    // 오류가 발생했을 때
    func offerwallDidFail(_ error: NestAdsOfferwallError) {
        print("❌ Offerwall 오류: [\(error.code)] \(error.message)")

        // 오류 타입별 처리
        switch error.code {
        case 1000:
            showAlert("초기화 오류", "SDK가 초기화되지 않았습니다")
        case 4001:
            showAlert("입력 오류", "유효한 사용자 ID를 입력해주세요")
        case 9999:
            showAlert("오류", error.message)
        default:
            showAlert("오류", error.message)
        }
    }

    // 리워드를 획득했을 때
    func offerwallDidEarnReward(amount: Int) {
        print("🎁 리워드 획득: \(amount) 포인트")

        // TODO: 사용자에게 리워드 지급
        UserManager.shared.addPoints(amount)

        // 성공 메시지 표시
        showRewardAlert(amount: amount)
    }

    // 커스텀 이벤트를 수신했을 때 (선택사항)
    func offerwallDidReceiveCustomEvent(eventType: String, payload: [String: Any]) {
        print("📨 커스텀 이벤트: \(eventType)")
        print("   데이터: \(payload)")
    }

    // 데이터 요청을 받았을 때 (선택사항)
    func offerwallDidRequestData(
        requestId: String,
        requestType: String,
        params: [String: Any]
    ) -> [String: Any]? {
        print("📥 데이터 요청")
        print("   Request ID: \(requestId)")
        print("   Request Type: \(requestType)")
        print("   Params: \(params)")

        // 필요에 따라 데이터 반환
        // 예: return ["key": "value"]
        return nil
    }

    private func showRewardAlert(amount: Int) {
        let alert = UIAlertController(
            title: "🎉 축하합니다!",
            message: "\(amount) 포인트를 획득했습니다!",
            preferredStyle: .alert
        )
        alert.addAction(UIAlertAction(title: "확인", style: .default))
        present(alert, animated: true)
    }
}

---

로그아웃

사용자가 로그아웃할 때 Offerwall에서도 로그아웃 처리를 해야 합니다.

Swift

func logoutUser() {
    // Offerwall 로그아웃
    NestAds.Offerwall.logout()

    // 로그아웃 확인
    DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) {
        if !NestAds.Offerwall.isLoggedIn {
            print("✅ 로그아웃 성공")
        }
    }
}

---

상태 확인

Offerwall의 현재 상태를 확인할 수 있습니다.

Swift

// 초기화 여부
let isInitialized = NestAds.Offerwall.isInitialized
print("초기화됨: \(isInitialized)")

// 로그인 여부
let isLoggedIn = NestAds.Offerwall.isLoggedIn
print("로그인됨: \(isLoggedIn)")

// 현재 사용자 ID
let userId = NestAds.Offerwall.currentUserId
print("사용자 ID: \(userId)")

// SDK 버전 정보
let sdkVersion = NestAds.Offerwall.sdkVersion
let adchainVersion = NestAds.Offerwall.adchainSDKVersion
print("Offerwall SDK: \(sdkVersion)")
print("AdChain SDK: \(adchainVersion)")

---

전체 예제

Swift

import UIKit
import NestAdsSDK
import NestAdsOfferwallSDK

class RewardViewController: UIViewController {

    @IBOutlet weak var rewardButton: UIButton!
    @IBOutlet weak var pointsLabel: UILabel!

    override func viewDidLoad() {
        super.viewDidLoad()

        // 사용자 로그인
        loginUser()

        // UI 업데이트
        updatePointsUI()
    }

    private func loginUser() {
        NestAds.Offerwall.login(
            userId: "user_12345",
            gender: NestAdsGenderMale,
            birthYear: 1990
        )
    }

    @IBAction func showOfferwallTapped(_ sender: UIButton) {
        // 로그인 확인
        guard NestAds.Offerwall.isLoggedIn else {
            showLoginAlert()
            return
        }

        // Offerwall 표시
        NestAds.Offerwall.openOfferwall(
            from: self,
            placementCode: "YOUR_PLACEMENT_CODE",
            delegate: self
        )
    }

    private func updatePointsUI() {
        let points = UserManager.shared.currentPoints
        pointsLabel.text = "보유 포인트: \(points)P"
    }

    private func showLoginAlert() {
        let alert = UIAlertController(
            title: "로그인 필요",
            message: "Offerwall을 사용하려면 로그인이 필요합니다",
            preferredStyle: .alert
        )
        alert.addAction(UIAlertAction(title: "확인", style: .default))
        present(alert, animated: true)
    }
}

// MARK: - NestAdsOfferwallDelegate
extension RewardViewController: NestAdsOfferwallDelegate {

    func offerwallDidOpen() {
        print("Offerwall 열림")
    }

    func offerwallDidClose() {
        print("Offerwall 닫힘")
    }

    func offerwallDidFail(_ error: NestAdsOfferwallError) {
        print("오류: [\(error.code)] \(error.message)")

        let alert = UIAlertController(
            title: "오류",
            message: error.message,
            preferredStyle: .alert
        )
        alert.addAction(UIAlertAction(title: "확인", style: .default))
        present(alert, animated: true)
    }

    func offerwallDidEarnReward(amount: Int) {
        print("리워드 획득: \(amount) 포인트")

        // 포인트 지급
        UserManager.shared.addPoints(amount)

        // UI 업데이트
        updatePointsUI()

        // 축하 메시지
        let alert = UIAlertController(
            title: "🎉 축하합니다!",
            message: "\(amount) 포인트를 획득했습니다!",
            preferredStyle: .alert
        )
        alert.addAction(UIAlertAction(title: "확인", style: .default))
        present(alert, animated: true)
    }
}

---

Quiz 광고

필수 설정

Quiz를 사용하기 위해서는 먼저 Offerwall을 초기화하고 사용자 로그인을 완료해야 합니다.

1. Offerwall 초기화 (AppDelegate)

이미 Offerwall을 설정했다면 이 단계는 생략하셔도 됩니다.

import UIKit
import NestAdsSDK
import NestAdsOfferwallSDK

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

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

        // Offerwall 설정 생성
        let offerwallConfig = OfferwallConfig(
            application: application,
            appKey: "YOUR_APP_KEY",
            appSecret: "YOUR_APP_SECRET",
            timeoutMillis: 30000
        )

        // NestAds 초기화
        NestAds.sharedInstance().start(offerwallConfig: offerwallConfig)

        return true
    }
}

2. 사용자 로그인

import NestAdsSDK

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()

        // 사용자 로그인 (Quiz 사용 전 필수)
        NestAds.Offerwall.login(userId: "user_12345")

        // 또는 추가 정보 포함
        // NestAds.Offerwall.login(
        //     userId: "user_12345",
        //     gender: NestAdsGenderMale,
        //     birthYear: 1990
        // )
    }
}

Quiz 사용하기

Swift

import NestAdsSDK
import NestAdsOfferwallSDK

class QuizViewController: UIViewController, NestAdsOfferwallQuizDelegate {

    private var quiz: NestAdsOfferwallQuiz?

    override func viewDidLoad() {
        super.viewDidLoad()
        setupQuiz()
    }

    private func setupQuiz() {
        // 1. Quiz 인스턴스 생성
        quiz = NestAds.Offerwall.quiz()

        // 2. Delegate 설정
        quiz?.setDelegate(self)

        // 3. Quiz 데이터 로드
        quiz?.load()
    }

    @IBAction func startQuizTapped(_ sender: UIButton) {
        guard let quiz = quiz else { return }

        // Quiz 실행 (Quiz ID를 사용하여 특정 Quiz 시작)
        quiz.clickQuiz("quiz_id_123", from: self)
    }

    // MARK: - NestAdsOfferwallQuizDelegate

    /// Quiz 로드 성공
    @objc func quizDidLoad(_ response: NestAdsOfferwallQuizResponse) {
        print("✅ Quiz 로드 성공")
        print("이벤트 개수: \(response.events.count)")

        // response.events에서 사용 가능한 Quiz 목록 확인
        for event in response.events {
            print("Quiz ID: \(event.id)")
            print("Quiz Title: \(event.title)")
        }
    }

    /// Quiz 로드 실패
    @objc func quizDidLoadFail(_ error: NestAdsOfferwallError) {
        print("❌ Quiz 로드 실패")
        print("Error: [\(error.code)] \(error.message)")
    }

    /// Quiz 완료
    @objc func quizDidComplete(_ quizEvent: NestAdsOfferwallQuizEvent, rewardAmount: Int) {
        print("✅ Quiz 완료!")
        print("獲得 포인트: \(rewardAmount)")
        print("Quiz ID: \(quizEvent.id)")

        // 리워드 지급 로직
        UserManager.shared.addPoints(rewardAmount)
    }
}

Quiz 응답 모델

NestAdsOfferwallQuizResponse는 다음 정보를 포함합니다:

속성	타입	설명
success	Bool	응답 성공 여부
events	[NestAdsOfferwallQuizEvent]	Quiz 이벤트 목록
titleText	String?	완료 후 표시할 제목
completedImageUrl	String?	완료 이미지 URL
message	String?	응답 메시지

NestAdsOfferwallQuizEvent는 다음 정보를 포함합니다:

속성	타입	설명
id	String	Quiz 고유 ID
title	String	Quiz 제목
eventDescription	String?	Quiz 설명

---

Mission 광고

필수 설정

Mission을 사용하기 위해서는 먼저 Offerwall을 초기화하고 사용자 로그인을 완료해야 합니다.

1. Offerwall 초기화 (AppDelegate)

위의 Quiz 섹션에서 설명한 Offerwall 초기화를 진행하세요.

2. 사용자 로그인

위의 Quiz 섹션에서 설명한 사용자 로그인을 진행하세요.

Mission 사용하기

Swift

import NestAdsSDK
import NestAdsOfferwallSDK

class MissionViewController: UIViewController, NestAdsOfferwallMissionDelegate {

    private var mission: NestAdsOfferwallMission?
    private var missionResponse: NestAdsOfferwallMissionResponse?

    override func viewDidLoad() {
        super.viewDidLoad()
        setupMission()
    }

    private func setupMission() {
        // 1. Mission 인스턴스 생성
        mission = NestAds.Offerwall.mission()

        // 2. Delegate 설정
        mission?.setDelegate(self)

        // 3. Mission 데이터 로드
        mission?.load()
    }

    @IBAction func startMissionTapped(_ sender: UIButton) {
        guard let mission = mission,
              let response = missionResponse,
              !response.missions.isEmpty else {
            return
        }

        // 첫 번째 Mission 실행
        let missionId = response.missions[0].id
        mission.clickMission(missionId, from: self)
    }

    @IBAction func refreshMissionListTapped(_ sender: UIButton) {
        mission?.refreshMissionList(unitId: "test_unit")
    }

    @IBAction func triggerRewardTapped(_ sender: UIButton) {
        mission?.triggerRewardButtonClick(from: self)
    }

    // MARK: - NestAdsOfferwallMissionDelegate

    /// Mission 로드 성공
    func missionDidLoad(
        _ response: NestAdsOfferwallMissionResponse,
        progress: NestAdsOfferwallMissionProgress
    ) {
        print("✅ Mission 로드 성공")
        self.missionResponse = response

        print("Mission 개수: \(response.missions.count)")
        print("진행도: \(progress.current) / \(progress.total)")
        print("완료율: \(progress.percentage)%")

        // Mission 목록 확인
        for mission in response.missions {
            print("---")
            print("ID: \(mission.id)")
            print("Title: \(mission.title)")
            print("Status: \(mission.status ?? "unknown")")
            print("Point: \(mission.point)")
        }
    }

    /// Mission 로드 실패
    func missionDidLoadFail(_ error: NestAdsOfferwallError) {
        print("❌ Mission 로드 실패")
        print("Error: [\(error.code)] \(error.message)")
    }

    /// Mission 완료
    func missionDidComplete(_ mission: NestAdsOfferwallMissionModel) {
        print("✅ Mission 완료!")
        print("Mission: \(mission.title)")
        print("Point: \(mission.point)")

        // 리워드 지급 로직
        UserManager.shared.addPoints(mission.point)
    }

    /// Mission 진행
    func missionDidProgress(_ mission: NestAdsOfferwallMissionModel) {
        print("⏳ Mission 진행 중")
        print("Progress: \(mission.progress ?? 0) / \(mission.total ?? 0)")
    }

    /// Mission 리스트 새로고침
    func missionListDidRefresh(unitId: String?) {
        print("🔄 Mission 리스트 새로고침됨")
        if let unitId = unitId {
            print("Unit ID: \(unitId)")
        }
    }

    deinit {
        // Mission 리소스 정리
        mission?.destroy()
    }
}

Mission 응답 모델

NestAdsOfferwallMissionResponse는 다음 정보를 포함합니다:

속성	타입	설명
success	Bool	응답 성공 여부
missions	[NestAdsOfferwallMissionModel]	Mission 목록
current	Int	현재 진행도
total	Int	총 Mission 개수
rewardUrl	String?	리워드 URL
titleText	String?	제목 텍스트
descriptionText	String?	설명 텍스트

NestAdsOfferwallMissionProgress는 다음 정보를 포함합니다:

속성	타입	설명
current	Int	현재 진행도
total	Int	총 진행도
percentage	Float	진행률 (%)
isCompleted	Bool	완료 여부

NestAdsOfferwallMissionModel는 다음 정보를 포함합니다:

속성	타입	설명
id	String	Mission 고유 ID
title	String	Mission 제목
missionDescription	String	Mission 설명
point	Int	보상 포인트
status	String?	Mission 상태
progress	Int?	현재 진행도
total	Int?	총 진행도
type	NestAdsOfferwallMissionType	Mission 타입
imageUrl	String	이미지 URL
landingUrl	String	랜딩 URL

Mission 메서드

메서드	설명
load()	Mission 데이터 로드
clickMission(_:from:)	Mission 실행
triggerRewardButtonClick(from:)	리워드 버튼 클릭 트리거
refreshMissionList(unitId:)	Mission 리스트 새로고침
destroy()	Mission 리소스 정리
setDelegate(_:)	Mission 이벤트 Delegate 설정

---

포인트 연동(S2S)

• 마이비 애드체인을 사용하는 파트너는 서버 간(S2S) 연동을 통해 포인트 적립 및 사용자 정보 조회 기능을 구현해야 합니다.

• 자세한 설명은 Adchain doc을 참고 부탁드립니다.

---

관련 레퍼런스

• OfferwallConfig - Offerwall 초기화 설정

• NestAds.Offerwall - Offerwall API

• NestAdsOfferwallDelegate - Offerwall 이벤트 Delegate

• NestAdsOfferwallError - Offerwall 에러 모델

• NestAds - NestAds 클래스

---

문제 해결

"NestAdsOfferwallSDK not available" 경고

원인: AppDelegate에서 SDK를 import하지 않았거나 패키지가 제대로 추가되지 않음

해결책:

1. AppDelegate.swift에 import NestAdsOfferwallSDK 추가

2. Xcode에서 Product → Clean Build Folder (Cmd+Shift+K)

3. 프로젝트 재빌드

Offerwall이 열리지 않음

다음 사항을 확인하세요:

// 1. 초기화 확인
print("Initialized: \(NestAds.Offerwall.isInitialized)")

// 2. 로그인 확인
print("Logged In: \(NestAds.Offerwall.isLoggedIn)")

// 3. Placement Code 확인
print("Placement Code가 비어있지 않은지 확인")

// 4. Delegate 설정 (에러 메시지 수신용)
NestAds.Offerwall.openOfferwall(
    from: self,
    placementCode: placementCode,
    delegate: self  // ← 반드시 설정
)

빌드 오류: "Module 'NestAdsOfferwallSDK' not found"

해결책:

1. Xcode에서 File → Packages → Resolve Package Versions

2. 프로젝트 설정에서 Frameworks, Libraries, and Embedded Content에 SDK가 추가되어 있는지 확인

3. Clean build folder 후 재빌드