퀴즈

퀴즈는 사용자가 간단한 질문에 답하고 포인트를 받을 수 있는 기능입니다. 오퍼월과 함께 사용하면 참여율이 높아집니다.

시작하기

AdchainQuiz 인스턴스 생성

퀴즈 기능을 사용하려면 먼저 AdchainQuiz 인스턴스를 생성합니다.

Android:

val adchainQuiz = AdchainQuiz()

iOS:

let adchainQuiz = AdchainQuiz()

React Native:

React Native에서는 SDK의 전역 인스턴스를 사용합니다.

import AdchainSdk from '@1selfworld/adchain-sdk-react-native';

퀴즈 완료 이벤트 리스너 설정 (선택사항)

퀴즈 완료 이벤트를 받으려면 리스너를 설정합니다.

Android:

adchainQuiz.setQuizEventsListener(object : AdchainQuizEventsListener {
    override fun onQuizCompleted(quizEvent: QuizEvent, score: Int) {
        Log.d(TAG, "Quiz completed: ${quizEvent.id}, score: $score")
        // 퀴즈 목록 새로고침
        refreshQuizList()
    }
})

iOS:

adchainQuiz.setQuizEventsListener(self)

// AdchainQuizEventsListener 프로토콜 구현
extension MyViewController: AdchainQuizEventsListener {
    func onQuizCompleted(_ quizEvent: QuizEvent, rewardAmount: Int) {
        print("Quiz completed: \(quizEvent.id), reward: \(rewardAmount)")
        // 퀴즈 목록 새로고침
        refreshQuizList()
    }
}

React Native:

import { addQuizCompletedListener } from '@1selfworld/adchain-sdk-react-native';

useEffect(() => {
  const subscription = addQuizCompletedListener((event) => {
    console.log('Quiz completed:', event.quizId, event.unitId);
    // 퀴즈 목록 새로고침
    if (event.unitId === QUIZ_UNIT_ID) {
      loadQuizList();
    }
  });

  return () => subscription.remove();
}, []);

퀴즈 목록 조회

현재 진행 중인 퀴즈 목록을 가져옵니다.

Android:

adchainQuiz.getQuizList(
    onSuccess = { quizResponse ->
        val titleText = quizResponse.titleText // 섹션 제목
        val quizzes = quizResponse.events      // 퀴즈 목록

        quizzes.forEach { quiz ->
            Log.d(TAG, "퀴즈: ${quiz.title}")
            Log.d(TAG, "보상: ${quiz.point}")
        }

        // UI 업데이트
        updateQuizList(quizzes)
    },
    onFailure = { error ->
        Log.e(TAG, "퀴즈 조회 실패: ${error.message}")
    }
)

iOS:

adchainQuiz.load(
    onSuccess: { quizResponse in
        let titleText = quizResponse.titleText // 섹션 제목
        let quizzes = quizResponse.events      // 퀴즈 목록

        for quiz in quizzes {
            print("퀴즈: \(quiz.title)")
            print("보상: \(quiz.point)")
        }

        // UI 업데이트
        self.updateQuizList(quizzes)
    },
    onFailure: { error in
        print("퀴즈 조회 실패: \(error.localizedDescription)")
    }
)

React Native:

const QUIZ_UNIT_ID = 'quiz_unit_001'; // 대시보드에서 생성한 Unit ID

try {
  const quizResponse = await AdchainSdk.loadQuizList(QUIZ_UNIT_ID);
  const titleText = quizResponse.titleText; // 섹션 제목
  const quizzes = quizResponse.events;      // 퀴즈 목록

  quizzes.forEach(quiz => {
    console.log(`퀴즈: ${quiz.title}`);
    console.log(`보상: ${quiz.point}`);
  });

  // 상태 업데이트
  setQuizList(quizzes);
  setTitleText(titleText);
} catch (error) {
  console.error('퀴즈 조회 실패:', error);
}

React Native 중요: 모든 Quiz API는 unitId 파라미터가 필수입니다. AdChain 대시보드에서 Quiz Unit을 생성하고 해당 ID를 사용하세요.

응답 데이터 구조

QuizResponse

퀴즈 목록 조회 시 반환되는 전체 응답 구조입니다.

필드	타입	설명
success	boolean	요청 성공 여부
titleText	string?	퀴즈 섹션 제목 (예: "데일리 1분 퀴즈")
completedImageUrl	string?	모든 퀴즈 완료 시 표시할 배너 이미지 URL
completedImageWidth	number?	완료 배너 이미지 너비 (픽셀)
completedImageHeight	number?	완료 배너 이미지 높이 (픽셀)
events	QuizEvent[]	퀴즈 목록
message	string?	에러 메시지 (실패 시)

QuizEvent (Quiz)

개별 퀴즈 객체의 구조입니다.

필드	타입	Android	iOS	React Native	설명
id	string	✅	✅	✅	퀴즈 고유 ID
title	string	✅	✅	✅	퀴즈 제목
description	string?	✅	✅	✅	퀴즈 설명
imageUrl	string	✅	✅	✅	썸네일 이미지 URL
point	string	✅	✅	✅	보상 포인트 (문자열, 예: "100P")
landingUrl	string	✅	✅	내부 사용	퀴즈 URL
status	string?	✅	✅	-	퀴즈 상태
completed	boolean?	✅	✅	-	완료 여부
isCompleted	boolean?	-	-	✅	완료 여부 (RN)
impressionOrder	number?	✅	✅	-	노출 순서 (내부 추적용)
placementId	string?	✅	✅	-	배치 ID (내부 추적용)

중요:

• point 필드는 string 타입입니다 (예: "100P", "+50포인트"). 숫자로 파싱하지 마세요.

• 완료 여부는 Android/iOS에서 completed, React Native에서 isCompleted로 확인합니다.

• impressionOrder와 placementId는 SDK 내부 추적용 필드입니다.

예시:

{
  "success": true,
  "titleText": "데일리 1분 퀴즈",
  "completedImageUrl": "https://example.com/completed.png",
  "completedImageWidth": 800,
  "completedImageHeight": 200,
  "events": [
    {
      "id": "quiz_001",
      "title": "오늘의 상식 퀴즈",
      "description": "간단한 상식 문제 5개",
      "imageUrl": "https://example.com/quiz1.jpg",
      "point": "100P",
      "landingUrl": "https://quiz.example.com/001",
      "completed": false,
      "isCompleted": false // React Native
    }
  ]
}

퀴즈 클릭 처리

사용자가 퀴즈를 클릭하면 clickQuiz() 메서드를 호출합니다. SDK가 자동으로 WebView를 열고 퀴즈를 진행합니다.

Android:

// RecyclerView 아이템 클릭
holder.itemView.setOnClickListener {
    adchainQuiz.clickQuiz(quiz.id)
}

iOS:

// TableView 셀 선택
func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {
    let quiz = quizzes[indexPath.row]
    adchainQuiz.clickQuiz(quiz.id, from: self)
}

React Native:

const handleQuizClick = async (quiz) => {
  try {
    await AdchainSdk.clickQuiz(QUIZ_UNIT_ID, quiz.id);
    // 퀴즈 WebView가 자동으로 열립니다
  } catch (error) {
    console.error('퀴즈 클릭 실패:', error);
  }
};

// 컴포넌트에서
<TouchableOpacity onPress={() => handleQuizClick(quiz)}>
  <Text>{quiz.title}</Text>
</TouchableOpacity>

clickQuiz 동작 흐름

clickQuiz() 호출 시 SDK는 자동으로:

1. quiz_clicked 이벤트 추적

2. 퀴즈 WebView를 전체화면으로 열기

3. 사용자가 퀴즈 완료 시:

   • quiz_completed 이벤트 추적

   • 리스너의 onQuizCompleted() 콜백 호출 (설정된 경우)

   • 포인트 자동 지급 (서버)

이벤트 리스너

리스너 인터페이스

Android:

interface AdchainQuizEventsListener {
    fun onQuizCompleted(quizEvent: QuizEvent, score: Int)
}

iOS:

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

onQuizCompleted

사용자가 퀴즈를 완료했을 때 호출됩니다. 이 시점에서 UI를 새로고침해야 합니다.

호출 시점: 퀴즈 WebView에서 완료 이벤트 수신 시

파라미터:

• quizEvent: 완료된 퀴즈 정보

• score (Android) / rewardAmount (iOS): 획득한 점수/보상 (일반적으로 0)

사용 예시:

Android:

override fun onQuizCompleted(quizEvent: QuizEvent, score: Int) {
    Log.d(TAG, "Quiz completed: ${quizEvent.title}")

    // 퀴즈 목록 새로고침 (필수)
    adchainQuiz.getQuizList(
        onSuccess = { response ->
            updateQuizList(response.events)
        },
        onFailure = { error ->
            Log.e(TAG, "Refresh failed: $error")
        }
    )

    // 사용자에게 알림
    showToast("퀴즈 완료! 포인트가 지급되었습니다.")
}

iOS:

func onQuizCompleted(_ quizEvent: QuizEvent, rewardAmount: Int) {
    print("Quiz completed: \(quizEvent.title)")

    // 퀴즈 목록 새로고침 (필수)
    adchainQuiz.load(
        onSuccess: { response in
            self.updateQuizList(response.events)
        },
        onFailure: { error in
            print("Refresh failed: \(error)")
        }
    )

    // 사용자에게 알림
    showAlert(message: "퀴즈 완료! 포인트가 지급되었습니다.")
}

React Native:

const subscription = addQuizCompletedListener((event) => {
  console.log('Quiz completed:', event.quizId);

  // 해당 unitId의 퀴즈 목록만 새로고침
  if (event.unitId === QUIZ_UNIT_ID) {
    loadQuizList();
    Alert.alert('퀴즈 완료!', '포인트가 지급되었습니다.');
  }
});

자동 추적 이벤트

SDK는 다음 이벤트를 자동으로 추적하여 AdChain 대시보드에 전송합니다.

이벤트명	발생 시점	페이로드
quiz_impressed	퀴즈 목록 로드 시 (각 퀴즈마다)	quizId, quizTitle, impressionOrder, placementId, userId
quiz_clicked	퀴즈 클릭 시	quizId, quizTitle, landingUrl, impressionOrder, placementId, userId
quiz_completed	퀴즈 완료 시	quizId, quizTitle, impressionOrder, placementId, userId

이 이벤트들은 별도로 구현할 필요가 없으며, AdChain 대시보드의 통계에 자동으로 반영됩니다.

UI 구현 가이드

퀴즈 목록 표시

Android (RecyclerView)

class QuizAdapter(
    private var quizzes: List<QuizEvent>,
    private val adchainQuiz: AdchainQuiz
) : RecyclerView.Adapter<QuizViewHolder>() {

    override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): QuizViewHolder {
        val view = LayoutInflater.from(parent.context)
            .inflate(R.layout.item_quiz, parent, false)
        return QuizViewHolder(view)
    }

    override fun onBindViewHolder(holder: QuizViewHolder, position: Int) {
        val quiz = quizzes[position]

        holder.titleText.text = quiz.title
        holder.pointText.text = quiz.point
        holder.descriptionText.text = quiz.description

        Glide.with(holder.itemView.context)
            .load(quiz.imageUrl)
            .centerCrop()
            .into(holder.imageView)

        // 완료된 퀴즈 표시
        if (quiz.completed == true) {
            holder.itemView.alpha = 0.5f
            holder.completedBadge.visibility = View.VISIBLE
        } else {
            holder.itemView.alpha = 1.0f
            holder.completedBadge.visibility = View.GONE
        }

        holder.itemView.setOnClickListener {
            if (quiz.completed != true) {
                adchainQuiz.clickQuiz(quiz.id)
            }
        }
    }

    fun updateQuizzes(newQuizzes: List<QuizEvent>) {
        quizzes = newQuizzes
        notifyDataSetChanged()
    }
}

iOS (UITableView)

func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
    return quizzes.count
}

func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
    let cell = tableView.dequeueReusableCell(
        withIdentifier: "QuizCell",
        for: indexPath
    ) as! QuizTableViewCell

    let quiz = quizzes[indexPath.row]

    cell.titleLabel.text = quiz.title
    cell.pointLabel.text = quiz.point
    cell.descriptionLabel.text = quiz.description
    cell.imageView?.loadImage(from: quiz.imageUrl)

    // 완료된 퀴즈 표시
    if quiz.completed == true {
        cell.contentView.alpha = 0.5
        cell.completedBadge.isHidden = false
    } else {
        cell.contentView.alpha = 1.0
        cell.completedBadge.isHidden = true
    }

    return cell
}

func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {
    tableView.deselectRow(at: indexPath, animated: true)

    let quiz = quizzes[indexPath.row]
    if quiz.completed != true {
        adchainQuiz.clickQuiz(quiz.id, from: self)
    }
}

React Native (FlatList)

const QuizList = () => {
  const [quizzes, setQuizzes] = useState<Quiz[]>([]);
  const [titleText, setTitleText] = useState<string>('');

  const loadQuizList = async () => {
    try {
      const response = await AdchainSdk.loadQuizList(QUIZ_UNIT_ID);
      setQuizzes(response.events);
      setTitleText(response.titleText || '데일리 퀴즈');
    } catch (error) {
      console.error(error);
    }
  };

  const handleQuizClick = async (quiz: Quiz) => {
    if (quiz.isCompleted) return;

    try {
      await AdchainSdk.clickQuiz(QUIZ_UNIT_ID, quiz.id);
    } catch (error) {
      console.error(error);
    }
  };

  return (
    <View>
      <Text style={styles.title}>{titleText}</Text>
      <FlatList
        data={quizzes}
        keyExtractor={item => item.id}
        renderItem={({ item }) => (
          <TouchableOpacity
            onPress={() => handleQuizClick(item)}
            disabled={item.isCompleted}
            style={[
              styles.quizItem,
              item.isCompleted && styles.completedItem
            ]}
          >
            <Image source={{ uri: item.imageUrl }} style={styles.image} />
            <View style={styles.content}>
              <Text style={styles.quizTitle}>{item.title}</Text>
              <Text style={styles.description}>{item.description}</Text>
              <Text style={styles.point}>{item.point}</Text>
            </View>
            {item.isCompleted && (
              <View style={styles.completedBadge}>
                <Text>완료</Text>
              </View>
            )}
          </TouchableOpacity>
        )}
      />
    </View>
  );
};

const styles = StyleSheet.create({
  completedItem: {
    opacity: 0.5,
  },
  // ... 기타 스타일
});

완료된 퀴즈 필터링

완료된 퀴즈를 제외하고 싶다면:

Android/iOS:

// Android
val availableQuizzes = quizzes.filter { it.completed != true }

// iOS
let availableQuizzes = quizzes.filter { $0.completed != true }

React Native:

const availableQuizzes = quizzes.filter(q => !q.isCompleted);

빈 상태 처리

모든 퀴즈가 완료되었을 때 completedImageUrl을 사용하여 완료 배너를 표시할 수 있습니다.

React Native 예시:

const QuizList = () => {
  const [quizResponse, setQuizResponse] = useState<QuizResponse | null>(null);

  if (quizResponse?.events.length === 0 && quizResponse.completedImageUrl) {
    return (
      <View style={styles.completedContainer}>
        <Image
          source={{ uri: quizResponse.completedImageUrl }}
          style={{
            width: '100%',
            aspectRatio:
              quizResponse.completedImageWidth! / quizResponse.completedImageHeight!
          }}
          resizeMode="contain"
        />
        <Text style={styles.completedText}>
          모든 퀴즈를 완료했습니다! 내일 다시 도전하세요.
        </Text>
      </View>
    );
  }

  return (
    // 퀴즈 목록 렌더링
  );
};

Android/iOS:

// Android
if (quizResponse.events.isEmpty() && quizResponse.completedImageUrl != null) {
    showCompletedBanner(quizResponse.completedImageUrl)
}

// iOS
if quizResponse.events.isEmpty, let completedImageUrl = quizResponse.completedImageUrl {
    showCompletedBanner(imageUrl: completedImageUrl)
}

React Native 특수사항

unitId 파라미터

React Native SDK에서는 모든 Quiz API에 unitId가 필수입니다.

unitId란?

• AdChain 대시보드에서 생성하는 Quiz Unit의 고유 식별자

• 같은 앱에서 여러 Quiz Unit을 운영할 수 있음 (예: 메인 화면, 프로필 화면)

• 각 Unit별로 다른 퀴즈 세트 관리 가능

사용 예시:

// 상수로 관리
const MAIN_QUIZ_UNIT = 'quiz_main_001';
const PROFILE_QUIZ_UNIT = 'quiz_profile_001';

// 메인 화면
const quizzes = await AdchainSdk.loadQuizList(MAIN_QUIZ_UNIT);
await AdchainSdk.clickQuiz(MAIN_QUIZ_UNIT, quizId);

// 프로필 화면
const profileQuizzes = await AdchainSdk.loadQuizList(PROFILE_QUIZ_UNIT);
await AdchainSdk.clickQuiz(PROFILE_QUIZ_UNIT, quizId);

이벤트 리스너

React Native는 Native Event Emitter를 사용합니다.

import { addQuizCompletedListener } from '@1selfworld/adchain-sdk-react-native';

// 컴포넌트 마운트 시 등록
useEffect(() => {
  const subscription = addQuizCompletedListener((event) => {
    console.log('Quiz completed:', event);
    // event.unitId: 완료된 퀴즈의 Unit ID
    // event.quizId: 완료된 퀴즈의 ID

    // 해당 Unit의 퀴즈만 새로고침
    if (event.unitId === QUIZ_UNIT_ID) {
      loadQuizList();
    }
  });

  // 컴포넌트 언마운트 시 정리
  return () => subscription.remove();
}, []);

주의사항 및 베스트 프랙티스

주의사항

• 로그인 필수: 사용자가 로그인되어 있어야 퀴즈 조회 가능

• 네트워크 필요: 오프라인 상태에서는 조회 불가

• point는 문자열: point 필드는 string 타입으로, 숫자로 파싱하지 말 것

• 플랫폼별 필드명 차이: 완료 여부는 Android/iOS에서 completed, React Native에서 isCompleted

베스트 프랙티스

1. 이벤트 리스너 우선 설정

   // 목록 로드 전에 리스너 설정
   adchainQuiz.setQuizEventsListener(listener)
   adchainQuiz.getQuizList(...)

2. onQuizCompleted에서 반드시 새로고침

   override fun onQuizCompleted(quizEvent: QuizEvent, score: Int) {
       // 퀴즈 목록 새로고침 필수
       adchainQuiz.getQuizList(...)
   }

3. 완료된 퀴즈 시각적 구분

   • 투명도 낮추기 (alpha = 0.5)

   • "완료" 배지 표시

   • 클릭 비활성화

4. React Native 캐싱 전략

   // 5분 TTL로 캐싱
   const CACHE_TTL = 5 * 60 * 1000;
   let cachedQuizzes = null;
   let cacheTime = 0;
   
   const loadQuizList = async (forceRefresh = false) => {
     const now = Date.now();
     if (!forceRefresh && cachedQuizzes && (now - cacheTime < CACHE_TTL)) {
       return cachedQuizzes;
     }
   
     const response = await AdchainSdk.loadQuizList(QUIZ_UNIT_ID);
     cachedQuizzes = response;
     cacheTime = now;
     return response;
   };

5. 빈 상태 처리

   • 퀴즈가 없을 때는 오퍼월로 유도하는 배너 표시

   • 완료 이미지 (completedImageUrl) 활용

6. 에러 처리

   onFailure = { error ->
       when (error) {
           AdchainAdError.NOT_INITIALIZED -> {
               // SDK 미초기화
               showError("SDK를 초기화해주세요")
           }
           AdchainAdError.NETWORK_ERROR -> {
               // 네트워크 오류
               showError("네트워크 연결을 확인해주세요")
           }
           AdchainAdError.EMPTY_RESPONSE -> {
               // 빈 응답
               showEmptyState()
           }
           else -> {
               // 기타 오류
               showError("오류가 발생했습니다")
           }
       }
   }

7. Android/iOS 인스턴스 관리

   // 필요할 때마다 새 인스턴스 생성 가능
   class QuizActivity : AppCompatActivity() {
       private var adchainQuiz: AdchainQuiz? = null
   
       override fun onResume() {
           super.onResume()
           adchainQuiz = AdchainQuiz()
           loadQuizList()
       }
   }

다음 단계

• 미션 사용하기

• 오퍼월

• 이벤트 추적