오퍼월 광고

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

기본 요건

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

추가 요구사항:

• NestAdsSDK 버전 v2.6.4 또는 v2.8.0 이상

• NestAdsOfferwallSDK v0.1.0 이상

---

설치

1. 프로젝트 단 settings.gradle 파일에 아래의 오퍼월 광고를 위한 maven repository를 추가합니다.

Gradle

dependencyResolutionManagement {
   repositories {
      mavenCentral()

       // JitPack repository for AdChain SDK
      maven { url = uri("https://jitpack.io") }

      // Adjoe SDK Maven repository
      maven { url = uri("https://releases.adjoe.io/maven") }
   }
}

1. app 모듈 수준의 build.gradle 파일에 offerwall sdk 의존성을 추가합니다.

Gradle

dependencies {
   implementation 'com.nestads:nestads-offerwall-sdk-android:$version'
}

---

테스트 광고 게재위치

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

---

Offerwall 통합하기

1. Application 클래스에서 초기화

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

중요: Application 클래스에서 반드시 import com.nestads.sdk.offerwall.model.OfferwallConfig를 추가해야 합니다. 이것이 없으면 런타임에 SDK를 찾을 수 없습니다.

Kotlin

import android.app.Application
import com.nestads.sdk.ads.NestAds
import com.nestads.sdk.offerwall.model.OfferwallConfig  // ⚠️ 필수!

class MyApp : Application() {

    override fun onCreate() {
        super.onCreate()

        // 1. Offerwall 설정 생성
        val offerwallConfig = OfferwallConfig.Builder(
            appKey = APP_KEY,        // 앱 키
            appSecret = APP_SECRET   // 앱 시크릿
        )
            .setTimeoutMillis(30000)  // 선택사항: 타임아웃 설정 (밀리초)
            .build()

        // 2. NestAds 초기화 (Offerwall 설정 포함)
        NestAds.initialize(this, offerwallConfig)
    }

    companion object {
        private const val APP_KEY = "YOUR_APP_KEY"
        private const val APP_SECRET = "YOUR_APP_SECRET"
    }
}

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

2. AndroidManifest.xml에 Application 클래스 등록

Application 클래스를 생성한 후에는 반드시 AndroidManifest.xml에 등록해야 합니다.

<application
    android:name=".MyApp"
    android:allowBackup="true"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name"
    android:theme="@style/AppTheme">

    <!-- 나머지 설정 -->

</application>

android:name=".MyApp" 속성을 추가하지 않으면 Application 클래스가 실행되지 않아 SDK가 초기화되지 않습니다.

---

사용자 로그인

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

사용자 정보와 함께 로그인

Kotlin

NestAds.Offerwall.login(
    userId, // 필수
    gender, // 선택
    birthYear, // 선택
    customProperties // 선택
)

---

파라미터 설명:

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

• gender - [선택] 성별.

  • NestAdsGenderMale (1) - 남성

  • NestAdsGenderFemale (2) - 여성

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

---

로그인 리스너 사용

val user = OfferwallUser(userId = "user123")

val loginListener = object : OfferwallLoginListener {
    override fun onSuccess() {
        Log.d("NestAds", "로그인 성공")
        Toast.makeText(context, "로그인되었습니다", Toast.LENGTH_SHORT).show()
    }

    override fun onFailure(errorType: OfferwallLoginListener.ErrorType) {
        Log.e("NestAds", "로그인 실패: $errorType")
        Toast.makeText(context, "로그인 실패", Toast.LENGTH_SHORT).show()
    }
}

NestAds.Offerwall.login(user, loginListener)

---

로그인 에러 타입별 처리

val loginListener = object : OfferwallLoginListener {
    override fun onSuccess() {
        Log.d("NestAds", "로그인 성공")
        // 메인 화면으로 이동
        startMainActivity()
    }

    override fun onFailure(errorType: OfferwallLoginListener.ErrorType) {
        when (errorType) {
            OfferwallLoginListener.ErrorType.NOT_INITIALIZED -> {
                Log.e("NestAds", "SDK가 초기화되지 않았습니다")
            }
            OfferwallLoginListener.ErrorType.INVALID_USER_ID -> {
                Log.e("NestAds", "잘못된 사용자 ID")
            }
            OfferwallLoginListener.ErrorType.NETWORK_ERROR -> {
                Log.e("NestAds", "네트워크 오류")
            }
            OfferwallLoginListener.ErrorType.AUTHENTICATION_FAILED -> {
                Log.e("NestAds", "인증 실패")
            }
            OfferwallLoginListener.ErrorType.UNKNOWN -> {
                Log.e("NestAds", "알 수 없는 오류")
            }
        }
    }
}

---

3. Offerwall 표시하기

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

Kotlin

fun openOfferwall(
  context: Context,
  placementCode: String,
  callback: OfferwallCallback? = null,
  eventCallback: OfferwallEventCallback? = null
)

// 사용 예시
NestAds.Offerwall.openOfferwall(
    context = context,
    placementCode = "YOUR_PLACEMENT_CODE",
    callback = object : OfferwallCallback {
        ...
    },
    eventCallback = object : OfferwallEventCallback {
        ...
    }
)

로그아웃

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

Kotlin

NestAds.Offerwall.logout()

---

상태 확인

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

Kotlin

// 초기화 여부
val isInitialized = NestAds.Offerwall.isInitialized

// 로그인 여부
val isLoggedIn = NestAds.Offerwall.isLoggedIn

// 현재 사용자 ID
val userId = NestAds.Offerwall.currentUserId

// SDK 버전 정보
val sdkVersion = NestAds.Offerwall.sdkVersion
val adchainSDKVersion = NestAds.Offerwall.adchainSdkVersion

---

Quiz 광고

필수 설정

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

1. Offerwall 초기화 (Application)

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

Kotlin

import android.app.Application
import com.nestads.sdk.offerwall.core.NestAdsOfferwall
import com.nestads.sdk.offerwall.model.OfferwallConfig

class MyApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        // Offerwall 설정 생성
        val offerwallConfig = OfferwallConfig.Builder(
            appKey = "YOUR_APP_KEY",
            appSecret = "YOUR_APP_SECRET"
        )
            .setTimeout(30000) // 타임아웃 설정 (밀리초)
            .build()

        // NestAds Offerwall 초기화
        NestAdsOfferwall.initialize(this, offerwallConfig)
    }
}

2. 사용자 로그인

Kotlin

import com.nestads.sdk.offerwall.core.NestAdsOfferwall
import com.nestads.sdk.offerwall.model.OfferwallUser
import com.nestads.sdk.offerwall.listener.OfferwallLoginListener

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // 사용자 생성 (Quiz 사용 전 필수)
        val user = OfferwallUser.Builder("user_12345").build()

        // 또는 추가 정보 포함
        // val user = OfferwallUser.Builder("user_12345")
        //     .setGender(OfferwallUser.Gender.MALE)
        //     .setBirthYear(1990)
        //     .build()

        // 로그인
        NestAdsOfferwall.login(user, object : OfferwallLoginListener {
            override fun onSuccess() {
                // 로그인 성공
            }

            override fun onFailure(errorType: OfferwallLoginListener.ErrorType) {
                // 로그인 실패
            }
        })
    }
}

---

Quiz 사용하기

Kotlin

import com.nestads.sdk.offerwall.core.NestAds
import com.nestads.sdk.offerwall.listener.OfferwallQuizEventsListener
import com.nestads.sdk.offerwall.model.quiz.OfferwallQuizResponse
import com.nestads.sdk.offerwall.model.quiz.OfferwallQuizEvent
import com.nestads.sdk.offerwall.model.OfferwallAdError

class QuizActivity : AppCompatActivity() {

    private val quiz = NestAds.Offerwall.quiz()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_quiz)

        setupQuiz()
    }

    private fun setupQuiz() {
        // 1. Quiz 이벤트 리스너 설정
        quiz.setQuizEventsListener { quizEvent, rewardAmount ->
            // Quiz 완료
            println("✅ Quiz 완료!")
            println("획득 포인트: $rewardAmount")
            println("Quiz ID: ${quizEvent.id}")

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

        // 2. Quiz 데이터 로드
        loadQuizList()
    }

    private fun loadQuizList() {
        quiz.getQuizList(
            onSuccess = { response ->
                // Quiz 로드 성공
                println("✅ Quiz 로드 성공")
                println("이벤트 개수: ${response.events.size}")

                // response.events에서 사용 가능한 Quiz 목록 확인
                response.events.forEach { event ->
                    println("Quiz ID: ${event.id}")
                    println("Quiz Title: ${event.title}")
                }
            },
            onFailure = { error ->
                // Quiz 로드 실패
                println("❌ Quiz 로드 실패")
                println("Error: [${error.code}] ${error.message}")
            }
        )
    }

    fun startQuiz(view: View) {
        // Quiz 실행 (Quiz ID를 사용하여 특정 Quiz 시작)
        quiz.clickQuiz("quiz_id_123")
    }
}

---

Quiz 응답 모델

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

속성	타입	설명
success	Boolean?	응답 성공 여부
events	List<OfferwallQuizEvent>	Quiz 이벤트 목록
titleText	String?	완료 후 표시할 제목
completedImageUrl	String?	완료 이미지 URL
completedImageWidth	Int?	완료 이미지 너비
completedImageHeight	Int?	완료 이미지 높이
message	String?	응답 메시지

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

속성	타입	설명
id	String	Quiz 고유 ID
title	String	Quiz 제목
description	String?	Quiz 설명
imageUrl	String	Quiz 이미지 URL
landingUrl	String	랜딩 페이지 URL
point	String	보상 포인트
status	String?	Quiz 상태
completed	Boolean?	완료 여부
impressionOrder	Int?	노출 순서
placementId	String?	배치 ID

---

Mission 광고

필수 설정

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

1. Offerwall 초기화 (Application)

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

2. 사용자 로그인

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

---

Mission 사용하기

Kotlin

import com.nestads.sdk.offerwall.core.NestAds
import com.nestads.sdk.offerwall.listener.OfferwallMissionEventsListener
import com.nestads.sdk.offerwall.model.mission.Mission
import com.nestads.sdk.offerwall.model.mission.MissionStatus
import com.nestads.sdk.offerwall.model.OfferwallAdError

class MissionActivity : AppCompatActivity() {

    private val mission = NestAds.Offerwall.mission()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_mission)

        setupMission()
    }

    private fun setupMission() {
        // 1. Mission 이벤트 리스너 설정
        mission.setEventsListener(object : OfferwallMissionEventsListener {
            override fun onCompleted(mission: Mission) {
                // Mission 완료
                println("✅ Mission 완료!")
                println("Mission: ${mission.title}")
                println("Point: ${mission.point}")

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

            override fun onProgressed(mission: Mission) {
                // Mission 진행 중
                println("⏳ Mission 진행 중")
                println("Progress: ${mission.progress} / ${mission.total}")
            }

            override fun onRefreshed(unitId: String?) {
                // Mission 리스트 새로고침
                println("🔄 Mission 리스트 새로고침됨")
                unitId?.let { println("Unit ID: $it") }
            }
        })

        // 2. Mission 데이터 로드
        loadMissionList()

        // 3. Mission 상태 조회
        loadMissionStatus()
    }

    private fun loadMissionList() {
        mission.getMissionList(
            onSuccess = { missions ->
                // Mission 로드 성공
                println("✅ Mission 로드 성공")
                println("Mission 개수: ${missions.size}")

                // Mission 목록 확인
                missions.forEach { m ->
                    println("---")
                    println("ID: ${m.id}")
                    println("Title: ${m.title}")
                    println("Status: ${m.status ?: "unknown"}")
                    println("Point: ${m.point}")
                    println("Type: ${m.type}")
                }
            },
            onFailure = { error ->
                // Mission 로드 실패
                println("❌ Mission 로드 실패")
                println("Error: [${error.code}] ${error.message}")
            }
        )
    }

    private fun loadMissionStatus() {
        mission.getMissionStatus(
            onSuccess = { status ->
                // Mission 상태 조회 성공
                println("✅ Mission 상태 조회 성공")
                println("진행도: ${status.current} / ${status.total}")
                println("완료율: ${if (status.total > 0) status.current * 100 / status.total else 0}%")
                println("완료 여부: ${status.isCompleted}")
                println("보상 청구 가능: ${status.canClaimReward}")
            },
            onFailure = { error ->
                println("❌ Mission 상태 조회 실패")
                println("Error: [${error.code}] ${error.message}")
            }
        )
    }

    fun startMission(view: View) {
        // 첫 번째 Mission 실행
        val response = mission.getOfferwallMissionResponse()
        response?.events?.firstOrNull()?.let { firstMission ->
            mission.clickMission(firstMission.id)
        }
    }

    fun refreshMissionList(view: View) {
        // Mission 리스트 새로고침
        mission.refreshMissionList(unitId = "test_unit")
    }

    fun triggerReward(view: View) {
        // 보상 청구
        mission.clickGetReward()
    }

    override fun onDestroy() {
        super.onDestroy()
        // Mission 리소스 정리는 자동으로 처리됨
    }
}

---

Mission 응답 모델

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

속성	타입	설명
success	Boolean?	응답 성공 여부
events	List<Mission>	Mission 목록
current	Int	현재 완료된 Mission 수
total	Int	총 Mission 개수
rewardUrl	String?	리워드 URL
titleText	String?	제목 텍스트
descriptionText	String?	설명 텍스트
bottomText	String?	하단 텍스트
rewardIconUrl	String?	보상 아이콘 URL
bottomIconUrl	String?	하단 아이콘 URL
message	String?	응답 메시지

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

속성	타입	설명
current	Int	완료된 Mission 수
total	Int	총 Mission 수
isCompleted	Boolean	모든 Mission 완료 여부
canClaimReward	Boolean	보상 청구 가능 여부

Mission은 다음 정보를 포함합니다:

속성	타입	설명
id	String	Mission 고유 ID
title	String	Mission 제목
description	String	Mission 설명
point	String	보상 포인트
status	String?	Mission 상태
progress	Int?	현재 진행도 (0-100)
total	Int?	총 진행도
type	MissionType?	Mission 타입
imageUrl	String	이미지 URL
landingUrl	String	랜딩 URL
impressionOrder	Int?	노출 순서
placementId	String?	배치 ID

MissionType은 다음 타입을 지원합니다:

타입	값	설명
NORMAL	"normal"	일반 Mission
OFFERWALL_PROMOTION	"offerwall_promotion"	Offerwall 프로모션 Mission

---

Mission 메서드

메서드	설명
setEventsListener(listener)	Mission 이벤트 리스너 설정
getMissionList(onSuccess, onFailure)	Mission 목록 조회
getMissionStatus(onSuccess, onFailure)	Mission 상태 조회
getOfferwallMissionResponse()	현재 Mission 응답 조회
clickMission(missionId)	Mission 실행
clickGetReward()	보상 청구
refreshMissionList(unitId)	Mission 리스트 새로고침

---

포인트 연동(S2S)

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

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

---

관련 레퍼런스

• OfferwallConfig - Offerwall 초기화 설정

• NestAds.Offerwall - Offerwall API

• NestAdsOfferwallQuiz - Offerwall API

• NestAdsOfferwallMission - Offerwall API

---