미션

미션은 사용자가 특정 조건을 달성하면 보상을 받는 기능입니다. 데일리 미션, 위클리 미션 등으로 사용자가 매일 앱을 방문하게 만듭니다.

시작하기

AdchainMission 인스턴스 생성

미션 기능을 사용하려면 먼저 AdchainMission 인스턴스를 생성합니다.

Android:

val adchainMission = AdchainMission()

iOS:

let adchainMission = AdchainMission()

React Native:

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

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

이벤트 리스너 설정 (권장)

미션 완료, 진행, 갱신 이벤트를 받으려면 리스너를 설정합니다.

Android:

adchainMission.setEventsListener(object : AdchainMissionEventsListener {
    override fun onCompleted(mission: Mission) {
        Log.d(TAG, "Mission completed: ${mission.id}")
        // 미션 목록 새로고침
        refreshMissionList()
    }

    override fun onProgressed(mission: Mission) {
        Log.d(TAG, "Mission progressed: ${mission.id}")
        // 진행률 UI 업데이트
        updateMissionProgress(mission)
    }

    override fun onRefreshed(unitId: String?) {
        Log.d(TAG, "Mission refreshed: ${unitId}")
        // 미션 목록 전체 새로고침
        refreshMissionList()
    }
})

iOS:

adchainMission.eventsListener = self

// AdchainMissionEventsListener 프로토콜 구현
extension MyViewController: AdchainMissionEventsListener {
    func onCompleted(_ mission: Mission) {
        print("Mission completed: \(mission.id)")
        // 미션 목록 새로고침
        refreshMissionList()
    }

    func onProgressed(_ mission: Mission) {
        print("Mission progressed: \(mission.id)")
        // 진행률 UI 업데이트
        updateMissionProgress(mission)
    }

    func onRefreshed(unitId: String?) {
        print("Mission refreshed: \(unitId ?? "unknown")")
        // 미션 목록 전체 새로고침
        refreshMissionList()
    }
}

React Native:

import {
  addMissionCompletedListener,
  addMissionProgressedListener,
  addMissionRefreshedListener
} from '@1selfworld/adchain-sdk-react-native';

useEffect(() => {
  // 미션 완료
  const completedSub = addMissionCompletedListener((event) => {
    console.log('Mission completed:', event.missionId, event.unitId);
    if (event.unitId === MISSION_UNIT_ID) {
      loadMissionList();
      Alert.alert('미션 완료!', '포인트가 지급되었습니다.');
    }
  });

  // 미션 진행
  const progressedSub = addMissionProgressedListener((event) => {
    console.log('Mission progressed:', event.missionId, event.unitId);
    if (event.unitId === MISSION_UNIT_ID) {
      loadMissionList(); // 부분 새로고침
    }
  });

  // 미션 갱신 (WebView에서 트리거)
  const refreshedSub = addMissionRefreshedListener((event) => {
    console.log('Mission refreshed:', event.unitId);
    if (event.unitId === MISSION_UNIT_ID) {
      loadMissionList(); // 전체 새로고침
    }
  });

  return () => {
    completedSub.remove();
    progressedSub.remove();
    refreshedSub.remove();
  };
}, []);

미션 목록 조회

현재 진행 중인 미션 목록을 가져옵니다.

Android:

adchainMission.getMissionList(
    onSuccess = { missions ->
        missions.forEach { mission ->
            Log.d(TAG, "미션: ${mission.title}")
            Log.d(TAG, "보상: ${mission.point}")
        }

        // UI 업데이트
        updateMissionList(missions)
    },
    onFailure = { error ->
        Log.e(TAG, "미션 조회 실패: ${error.message}")
    }
)

iOS:

adchainMission.load(
    onSuccess: { missions, progress in
        for mission in missions {
            print("미션: \(mission.title)")
            print("보상: \(mission.point)")
        }

        // progress.current: 완료된 미션 개수
        // progress.total: 전체 미션 개수
        print("진행도: \(progress.current)/\(progress.total)")

        // UI 업데이트
        self.updateMissionList(missions)
        self.updateProgress(progress)
    },
    onFailure: { error in
        print("미션 조회 실패: \(error.localizedDescription)")
    }
)

React Native:

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

try {
  const response = await AdchainSdk.loadMissionList(MISSION_UNIT_ID);

  const {
    missions,           // 미션 목록
    completedCount,     // 완료된 미션 개수
    totalCount,         // 전체 미션 개수
    canClaimReward      // 보상 수령 가능 여부
  } = response;

  missions.forEach(mission => {
    console.log(`미션: ${mission.title}`);
    console.log(`보상: ${mission.reward}P`);
  });

  // 상태 업데이트
  setMissionList(missions);
  setProgress({ current: completedCount, total: totalCount });
  setCanClaimReward(canClaimReward);
} catch (error) {
  console.error('미션 조회 실패:', error);
}

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

응답 데이터 구조

MissionResponse (Android/iOS)

서버에서 반환되는 전체 응답 구조입니다.

필드

타입

설명

success

boolean

요청 성공 여부

events

Mission[]

미션 목록

current

number

완료된 미션 개수

total

number

전체 미션 개수

rewardUrl

string?

보상 수령 URL

titleText

string?

미션 섹션 제목 (예: "무료 포인트 모으기!")

descriptionText

string?

설명 텍스트

bottomText

string?

하단 텍스트 (예: "800만 포인트 받으러 가기")

rewardIconUrl

string?

보상 아이콘 URL

bottomIconUrl

string?

하단 아이콘 URL

MissionListResponse (React Native)

React Native에서 반환되는 응답 구조입니다.

필드

타입

설명

missions

Mission[]

미션 목록

completedCount

number

완료된 미션 개수

totalCount

number

전체 미션 개수

canClaimReward

boolean

보상 수령 가능 여부

titleText

string?

미션 섹션 제목

descriptionText

string?

설명 텍스트

bottomText

string?

하단 텍스트

rewardIconUrl

string?

보상 아이콘 URL

bottomIconUrl

string?

하단 아이콘 URL

Mission

개별 미션 객체의 구조입니다.

필드

타입

Android

iOS

React Native

설명

id

string

✅

미션 고유 ID

title

string

✅

미션 제목

description

string

✅

미션 설명

imageUrl

string

✅

썸네일 이미지 URL

landingUrl

string

✅

✅ (actionUrl)

미션 URL

point

string

✅

보상 포인트 (문자열)

reward

number

✅

보상 포인트 (숫자)

status

string?

✅

미션 상태

progress

number?

✅

미션 진행도

total

number?

✅

미션 목표

type

MissionType

✅

✅ (string)

미션 타입

isCompleted

boolean?

✅

완료 여부 (RN)

impressionOrder

number?

✅

노출 순서 (내부 추적용)

placementId

string?

✅

배치 ID (내부 추적용)

중요:

point 필드는 string 타입입니다 (Android/iOS). React Native는 reward (number) 사용.
progress와 total은 개별 미션의 진행도입니다 (예: "광고 3개 클릭" 중 2개 완료).
MissionResponse의 current/total은 전체 미션 중 완료된 개수입니다.

MissionType:

normal - 일반 미션
offerwall_promotion - 오퍼월 프로모션 (클릭 시 오퍼월 열림)

MissionProgress (iOS)

iOS의 load() 메서드가 두 번째 파라미터로 반환하는 구조입니다.

필드

타입

설명

current

number

완료된 미션 개수

total

number

전체 미션 개수

percentage

number

완료 비율 (자동 계산)

MissionStatus (Android)

Android의 getMissionStatus() 메서드가 반환하는 구조입니다.

필드

타입

설명

current

number

완료된 미션 개수

total

number

전체 미션 개수

isCompleted

boolean

모든 미션 완료 여부

canClaimReward

boolean

보상 수령 가능 여부

미션 클릭 처리

사용자가 미션을 클릭하면 clickMission() 메서드를 호출합니다.

Android:

// RecyclerView 아이템 클릭
holder.itemView.setOnClickListener {
    // 미션 타입별 처리
    when (mission.type) {
        MissionType.OFFERWALL_PROMOTION -> {
            // 오퍼월 프로모션: 오퍼월 열기
            AdchainSdk.openOfferwall(context, placementId = "mission_promo")
        }
        else -> {
            // 일반 미션: 미션 WebView 열기
            adchainMission.clickMission(mission.id)
        }
    }
}

iOS:

// TableView 셀 선택
func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {
    tableView.deselectRow(at: indexPath, animated: true)
    let mission = missions[indexPath.row]

    if mission.type == .offerwallPromotion {
        AdchainSdk.shared.openOfferwall(
            presentingViewController: self,
            placementId: "mission_promo"
        )
    } else {
        adchainMission.clickMission(mission.id, from: self)
    }
}

React Native:

const handleMissionClick = async (mission: Mission) => {
  try {
    if (mission.type === 'offerwall_promotion') {
      // 오퍼월 프로모션: 오퍼월 열기
      await AdchainSdk.openOfferwall('mission_promo');
    } else {
      // 일반 미션: 미션 WebView 열기
      await AdchainSdk.clickMission(MISSION_UNIT_ID, mission.id);
    }
  } catch (error) {
    console.error('미션 클릭 실패:', error);
  }
};

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

clickMission 동작 흐름

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

mission_clicked 이벤트 추적
리스너의 onClicked() 콜백 호출 (설정된 경우)
미션 WebView를 전체화면으로 열기
사용자가 미션 완료 시:
- mission_completed 이벤트 추적
- 리스너의 onCompleted() 콜백 호출
- 포인트 자동 지급 (서버)
미션 진행 업데이트 시:
- mission_progressed 이벤트 추적
- 리스너의 onProgressed() 콜백 호출
WebView에서 갱신 트리거 시:
- 리스너의 onRefreshed() 콜백 호출

보상 수령

모든 미션을 완료하면 보상을 수령할 수 있습니다.

Android:

// 보상 수령 버튼 클릭
rewardButton.setOnClickListener {
    adchainMission.clickGetReward()
}

iOS:

// 보상 수령 버튼 클릭
@objc func claimRewardTapped() {
    adchainMission.onRewardButtonClicked(from: self)
}

React Native:

const handleClaimReward = async () => {
  try {
    await AdchainSdk.claimReward(MISSION_UNIT_ID);
    Alert.alert('보상 수령 완료!', '포인트가 지급되었습니다.');
    // 미션 목록 새로고침
    loadMissionList();
  } catch (error) {
    console.error('보상 수령 실패:', error);
  }
};

// 버튼
<TouchableOpacity
  onPress={handleClaimReward}
  disabled={!canClaimReward}
>
  <Text>보상 받기</Text>
</TouchableOpacity>

보상 수령 가능 여부는 MissionStatus.canClaimReward (Android), MissionListResponse.canClaimReward (React Native)로 확인하거나, iOS에서는 progress.current == progress.total로 판단합니다.

미션 상태 조회

Android

getMissionStatus() 메서드로 전체 미션 완료 상태를 조회합니다.

adchainMission.getMissionStatus(
    onSuccess = { status ->
        Log.d(TAG, "완료: ${status.current}/${status.total}")

        if (status.canClaimReward) {
            // 보상 수령 UI 표시
            showRewardButton()
        }
    },
    onFailure = { error ->
        Log.e(TAG, "상태 조회 실패: ${error}")
    }
)

iOS

load() 메서드가 반환하는 MissionProgress를 사용합니다.

adchainMission.load(
    onSuccess: { missions, progress in
        print("완료: \(progress.current)/\(progress.total)")
        print("진행률: \(progress.percentage)%")

        if progress.current == progress.total && progress.total > 0 {
            // 보상 수령 UI 표시
            showRewardButton()
        }
    },
    onFailure: { error in
        print("Failed: \(error)")
    }
)

React Native

loadMissionList() 응답의 canClaimReward 필드를 사용합니다.

const response = await AdchainSdk.loadMissionList(MISSION_UNIT_ID);

console.log(`완료: ${response.completedCount}/${response.totalCount}`);

if (response.canClaimReward) {
  // 보상 수령 UI 표시
  setShowRewardButton(true);
}

이벤트 리스너

리스너 인터페이스

Android:

interface AdchainMissionEventsListener {
    fun onCompleted(mission: Mission)
    fun onProgressed(mission: Mission)
    fun onRefreshed(unitId: String?)
}

iOS:

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

이벤트 설명

onCompleted

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

호출 시점: 미션 WebView에서 완료 이벤트 수신 시

사용 예시:

Android:

override fun onCompleted(mission: Mission) {
    Log.d(TAG, "Mission completed: ${mission.title}")

    // 미션 목록 새로고침 (필수)
    adchainMission.getMissionList(
        onSuccess = { missions ->
            updateMissionList(missions)
        },
        onFailure = { error ->
            Log.e(TAG, "Refresh failed: $error")
        }
    )

    // 사용자에게 알림
    showToast("미션 완료! ${mission.point} 포인트가 지급되었습니다.")
}

iOS:

func onCompleted(_ mission: Mission) {
    print("Mission completed: \(mission.title)")

    // 미션 목록 새로고침 (필수)
    adchainMission.load(
        onSuccess: { missions, progress in
            self.updateMissionList(missions)
            self.updateProgress(progress)
        },
        onFailure: { error in
            print("Refresh failed: \(error)")
        }
    )

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

React Native:

const completedSub = addMissionCompletedListener((event) => {
  console.log('Mission completed:', event.missionId);

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

onProgressed

미션 진행도가 업데이트되었을 때 호출됩니다.

호출 시점: 미션 WebView에서 진행 업데이트 이벤트 수신 시

사용 예시:

Android:

override fun onProgressed(mission: Mission) {
    Log.d(TAG, "Mission progressed: ${mission.id}, ${mission.progress}/${mission.total}")

    // 해당 미션의 진행률 UI만 업데이트 (부분 새로고침)
    updateMissionProgress(mission)
}

iOS:

func onProgressed(_ mission: Mission) {
    print("Mission progressed: \(mission.id)")

    // 해당 미션의 진행률 UI만 업데이트
    updateMissionProgress(mission)
}

React Native:

const progressedSub = addMissionProgressedListener((event) => {
  console.log('Mission progressed:', event.missionId);

  // 부분 새로고침 (해당 미션만 업데이트)
  if (event.unitId === MISSION_UNIT_ID) {
    loadMissionList();
  }
});

onRefreshed

미션 WebView에서 전체 미션 목록 갱신을 요청할 때 호출됩니다.

호출 시점: 미션 WebView에서 갱신 이벤트 트리거 시 (예: 보상 수령 후)

파라미터:

unitId: 갱신을 요청한 미션 Unit ID (Android/iOS는 nullable, React Native는 이벤트 페이로드에 포함)

사용 예시:

Android:

override fun onRefreshed(unitId: String?) {
    Log.d(TAG, "Mission refreshed: $unitId")

    // 미션 목록 전체 새로고침 (필수)
    adchainMission.getMissionList(
        onSuccess = { missions ->
            updateMissionList(missions)
        },
        onFailure = { error ->
            Log.e(TAG, "Refresh failed: $error")
        }
    )
}

iOS:

func onRefreshed(unitId: String?) {
    print("Mission refreshed: \(unitId ?? "unknown")")

    // 미션 목록 전체 새로고침 (필수)
    adchainMission.load(
        onSuccess: { missions, progress in
            self.updateMissionList(missions)
            self.updateProgress(progress)
        },
        onFailure: { error in
            print("Refresh failed: \(error)")
        }
    )
}

React Native:

const refreshedSub = addMissionRefreshedListener((event) => {
  console.log('Mission refreshed:', event.unitId);

  // 해당 Unit의 미션 목록 전체 새로고침
  if (event.unitId === MISSION_UNIT_ID) {
    loadMissionList();
  }
});

자동 추적 이벤트

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

이벤트명

발생 시점

페이로드

mission_impressed

미션 목록 로드 시 (각 미션마다)

missionId, missionTitle, impressionOrder, placementId, userId

mission_clicked

미션 클릭 시

missionId, missionTitle, landingUrl, impressionOrder, placementId, userId

mission_completed

미션 완료 시

missionId, missionTitle, impressionOrder, placementId, userId

mission_progressed

미션 진행 업데이트 시

missionId, missionTitle, progress, total, userId

mission_refreshed

미션 목록 갱신 시

unitId, userId

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

UI 구현 가이드

미션 목록 표시

Android (RecyclerView)

class MissionAdapter(
    private val context: Activity,
    private val adchainMission: AdchainMission
) : RecyclerView.Adapter<MissionViewHolder>() {

    private var missions: List<Mission> = emptyList()

    override fun onBindViewHolder(holder: MissionViewHolder, position: Int) {
        val mission = missions[position]

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

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

        // 진행률 표시
        if (mission.progress != null && mission.total != null) {
            val percentage = (mission.progress.toFloat() / mission.total * 100).toInt()
            holder.progressBar.progress = percentage
            holder.progressText.text = "${mission.progress}/${mission.total}"
        }

        // 완료된 미션 표시
        if (mission.status == "completed") {
            holder.itemView.alpha = 0.5f
            holder.completedBadge.visibility = View.VISIBLE
        } else {
            holder.itemView.alpha = 1.0f
            holder.completedBadge.visibility = View.GONE
        }

        // 미션 타입별 처리
        holder.itemView.setOnClickListener {
            when (mission.type) {
                MissionType.OFFERWALL_PROMOTION -> {
                    // 오퍼월 프로모션
                    AdchainSdk.openOfferwall(context, placementId = "mission_promo")
                }
                else -> {
                    // 일반 미션
                    if (mission.status != "completed") {
                        adchainMission.clickMission(mission.id)
                    }
                }
            }
        }
    }

    fun updateMissions(newMissions: List<Mission>) {
        missions = newMissions
        notifyDataSetChanged()
    }
}

iOS (UITableView)

extension MissionViewController: UITableViewDataSource, UITableViewDelegate {
    func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
        return missions.count
    }

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

        let mission = missions[indexPath.row]

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

        // 진행률 표시
        if let progress = mission.progress, let total = mission.total, total > 0 {
            let percentage = Float(progress) / Float(total)
            cell.progressView.progress = percentage
            cell.progressLabel.text = "\(progress)/\(total)"
        }

        // 완료된 미션 표시
        if mission.status == "completed" {
            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 mission = missions[indexPath.row]

        if mission.type == .offerwallPromotion {
            AdchainSdk.shared.openOfferwall(
                presentingViewController: self,
                placementId: "mission_promo"
            )
        } else if mission.status != "completed" {
            adchainMission?.clickMission(mission.id, from: self)
        }
    }
}

React Native (FlatList)

const MissionList = () => {
  const [missions, setMissions] = useState<Mission[]>([]);
  const [progress, setProgress] = useState({ current: 0, total: 0 });
  const [canClaimReward, setCanClaimReward] = useState(false);

  const loadMissionList = async () => {
    try {
      const response = await AdchainSdk.loadMissionList(MISSION_UNIT_ID);
      setMissions(response.missions);
      setProgress({
        current: response.completedCount,
        total: response.totalCount
      });
      setCanClaimReward(response.canClaimReward);
    } catch (error) {
      console.error(error);
    }
  };

  useEffect(() => {
    loadMissionList();

    // 이벤트 리스너 등록
    const completedSub = addMissionCompletedListener((event) => {
      if (event.unitId === MISSION_UNIT_ID) {
        loadMissionList();
      }
    });

    const progressedSub = addMissionProgressedListener((event) => {
      if (event.unitId === MISSION_UNIT_ID) {
        loadMissionList();
      }
    });

    const refreshedSub = addMissionRefreshedListener((event) => {
      if (event.unitId === MISSION_UNIT_ID) {
        loadMissionList();
      }
    });

    return () => {
      completedSub.remove();
      progressedSub.remove();
      refreshedSub.remove();
    };
  }, []);

  const handleMissionClick = async (mission: Mission) => {
    if (mission.isCompleted) return;

    try {
      if (mission.type === 'offerwall_promotion') {
        await AdchainSdk.openOfferwall('mission_promo');
      } else {
        await AdchainSdk.clickMission(MISSION_UNIT_ID, mission.id);
      }
    } catch (error) {
      console.error(error);
    }
  };

  return (
    <View style={styles.container}>
      {/* 진행률 표시 */}
      <View style={styles.progressContainer}>
        <Text style={styles.progressText}>
          {progress.current}/{progress.total} 미션 완료
        </Text>
        <ProgressBar
          progress={progress.total > 0 ? progress.current / progress.total : 0}
        />
      </View>

      {/* 미션 목록 */}
      <FlatList
        data={missions}
        keyExtractor={(item) => item.id}
        renderItem={({ item }) => (
          <TouchableOpacity
            onPress={() => handleMissionClick(item)}
            disabled={item.isCompleted}
            style={[
              styles.missionItem,
              item.isCompleted && styles.completedItem
            ]}
          >
            <Image source={{ uri: item.imageUrl }} style={styles.image} />
            <View style={styles.content}>
              <Text style={styles.title}>{item.title}</Text>
              <Text style={styles.description}>{item.description}</Text>
              <Text style={styles.reward}>{item.reward}P</Text>
            </View>
            {item.isCompleted && (
              <View style={styles.completedBadge}>
                <Text style={styles.badgeText}>완료</Text>
              </View>
            )}
          </TouchableOpacity>
        )}
      />

      {/* 보상 수령 버튼 */}
      {canClaimReward && (
        <TouchableOpacity
          style={styles.rewardButton}
          onPress={handleClaimReward}
        >
          <Text style={styles.rewardButtonText}>보상 받기</Text>
        </TouchableOpacity>
      )}
    </View>
  );
};

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

진행률 UI 구현

Android 예제 (체크박스 + 라인):

private fun updateProgress(progress: MissionProgress) {
    // progress.current: 완료된 미션 개수
    // progress.total: 전체 미션 개수

    when (progress.current) {
        0 -> {
            checkBox1.setImageResource(R.drawable.ic_circle_check_empty)
            checkBox2.setImageResource(R.drawable.ic_circle_check_empty)
            checkBox3.setImageResource(R.drawable.ic_circle_check_empty)
            progressLine1.setBackgroundColor(getColor(R.color.gray_light))
            progressLine2.setBackgroundColor(getColor(R.color.gray_light))
        }
        1 -> {
            checkBox1.setImageResource(R.drawable.ic_circle_check_filled)
            checkBox2.setImageResource(R.drawable.ic_circle_check_empty)
            checkBox3.setImageResource(R.drawable.ic_circle_check_empty)
            progressLine1.setBackgroundColor(getColor(R.color.gray_light))
            progressLine2.setBackgroundColor(getColor(R.color.gray_light))
        }
        2 -> {
            checkBox1.setImageResource(R.drawable.ic_circle_check_filled)
            checkBox2.setImageResource(R.drawable.ic_circle_check_filled)
            checkBox3.setImageResource(R.drawable.ic_circle_check_empty)
            progressLine1.setBackgroundColor(getColor(R.color.purple_500))
            progressLine2.setBackgroundColor(getColor(R.color.gray_light))
        }
        else -> { // 3개 이상 완료
            checkBox1.setImageResource(R.drawable.ic_circle_check_filled)
            checkBox2.setImageResource(R.drawable.ic_circle_check_filled)
            checkBox3.setImageResource(R.drawable.ic_circle_check_filled)
            progressLine1.setBackgroundColor(getColor(R.color.purple_500))
            progressLine2.setBackgroundColor(getColor(R.color.purple_500))
        }
    }

    // 보상 수령 가능 여부
    if (progress.current >= progress.total && progress.total > 0) {
        // 미션 목록 숨기고 보상 버튼 표시
        missionRecyclerView.visibility = View.GONE
        rewardContainer.visibility = View.VISIBLE
    }
}

완료된 미션 필터링

완료된 미션을 제외하고 싶다면:

Android/iOS:

// Android
val activeMissions = missions.filter { it.status != "completed" }

// iOS
let activeMissions = missions.filter { $0.status != "completed" }

React Native:

const activeMissions = missions.filter(m => !m.isCompleted);

빈 상태 처리

미션이 모두 완료되었을 때:

// React Native 예제
if (missions.every(m => m.isCompleted)) {
  return (
    <View style={styles.emptyContainer}>
      <Text style={styles.emptyText}>
        모든 미션을 완료했습니다!
      </Text>
      <TouchableOpacity onPress={handleClaimReward}>
        <Text>보상 받기</Text>
      </TouchableOpacity>
    </View>
  );
}

보상 수령 UI

보상 수령 가능 시 UI 변경:

// Android
if (status.canClaimReward) {
    // 미션 목록 숨기고 보상 UI 표시
    missionRecyclerView.visibility = View.GONE
    rewardContainer.visibility = View.VISIBLE

    rewardButton.setOnClickListener {
        adchainMission.clickGetReward()
    }
}

// iOS
if progress.current == progress.total && progress.total > 0 {
    // 미션 목록 숨기고 보상 UI 표시
    missionTableView.isHidden = true
    rewardContainer.isHidden = false
}

React Native 특수사항

unitId 파라미터

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

unitId란?

AdChain 대시보드에서 생성하는 Mission Unit의 고유 식별자
같은 앱에서 여러 Mission Unit을 운영할 수 있음 (예: 메인 화면, 프로필 화면)
각 Unit별로 다른 미션 세트 관리 가능

사용 예시:

// 상수로 관리
const MAIN_MISSION_UNIT = 'mission_main_001';
const PROFILE_MISSION_UNIT = 'mission_profile_001';

// 메인 화면
const mainMissions = await AdchainSdk.loadMissionList(MAIN_MISSION_UNIT);
await AdchainSdk.clickMission(MAIN_MISSION_UNIT, missionId);
await AdchainSdk.claimReward(MAIN_MISSION_UNIT);

// 프로필 화면
const profileMissions = await AdchainSdk.loadMissionList(PROFILE_MISSION_UNIT);
await AdchainSdk.clickMission(PROFILE_MISSION_UNIT, missionId);
await AdchainSdk.claimReward(PROFILE_MISSION_UNIT);

이벤트 리스너

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

import {
  addMissionCompletedListener,
  addMissionProgressedListener,
  addMissionRefreshedListener
} from '@1selfworld/adchain-sdk-react-native';

useEffect(() => {
  // 미션 완료
  const completedSub = addMissionCompletedListener((event) => {
    console.log('Mission completed:', event);
    // event.unitId: 완료된 미션의 Unit ID
    // event.missionId: 완료된 미션의 ID

    if (event.unitId === MISSION_UNIT_ID) {
      loadMissionList();
      Alert.alert('미션 완료!', '포인트가 지급되었습니다.');
    }
  });

  // 미션 진행
  const progressedSub = addMissionProgressedListener((event) => {
    console.log('Mission progressed:', event);

    if (event.unitId === MISSION_UNIT_ID) {
      loadMissionList(); // 부분 새로고침
    }
  });

  // 미션 갱신
  const refreshedSub = addMissionRefreshedListener((event) => {
    console.log('Mission refreshed:', event);

    if (event.unitId === MISSION_UNIT_ID) {
      loadMissionList(); // 전체 새로고침
    }
  });

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

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

주의사항

로그인 필수: 사용자가 로그인되어 있어야 미션 조회 가능
네트워크 필요: 오프라인 상태에서는 조회 불가
point는 문자열: point 필드는 string 타입 (Android/iOS)
progress와 current 혼동 주의:
- mission.progress / mission.total: 개별 미션의 진행도
- response.current / response.total: 완료된 미션 개수
플랫폼별 필드명 차이: iOS는 point, React Native는 reward

베스트 프랙티스

이벤트 리스너 우선 설정 (필수!)

// 목록 로드 전에 리스너 설정
adchainMission.setEventsListener(listener)
adchainMission.getMissionList(...)

onCompleted/onRefreshed에서 반드시 새로고침

override fun onCompleted(mission: Mission) {
    // 미션 목록 새로고침 필수
    adchainMission.getMissionList(...)
}

override fun onRefreshed(unitId: String?) {
    // 미션 목록 새로고침 필수
    adchainMission.getMissionList(...)
}

onProgressed에서 부분 새로고침

override fun onProgressed(mission: Mission) {
    // 해당 미션의 진행률 UI만 업데이트 (효율적)
    updateMissionProgress(mission)
}

미션 타입별 처리

when (mission.type) {
    MissionType.OFFERWALL_PROMOTION -> {
        // 오퍼월 열기
        AdchainSdk.openOfferwall(context, "promo")
    }
    else -> {
        // 미션 클릭
        adchainMission.clickMission(mission.id)
    }
}

보상 수령 가능 시 UI 변경

if (status.canClaimReward) {
    // 미션 목록 숨기고 보상 버튼 표시
    missionRecyclerView.visibility = View.GONE
    rewardContainer.visibility = View.VISIBLE
}

완료된 미션 시각적 구분
- 투명도 낮추기 (alpha = 0.5)
- "완료" 배지 표시
- 클릭 비활성화

React Native 캐싱 전략

// 5분 TTL로 캐싱
const CACHE_TTL = 5 * 60 * 1000;
let cachedMissions = null;
let cacheTime = 0;

const loadMissionList = async (forceRefresh = false) => {
  const now = Date.now();
  if (!forceRefresh && cachedMissions && (now - cacheTime < CACHE_TTL)) {
    return cachedMissions;
  }

  const response = await AdchainSdk.loadMissionList(MISSION_UNIT_ID);
  cachedMissions = response;
  cacheTime = now;
  return response;
};

에러 처리

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

진행률 UI 실시간 업데이트

// onProgressed 콜백 활용
override fun onProgressed(mission: Mission) {
    // 전체 목록 새로고침 대신 해당 미션만 업데이트
    adapter.updateMissionProgress(mission.id, mission.progress, mission.total)
}

Android/iOS 인스턴스 관리

// 필요할 때마다 새 인스턴스 생성 가능
class MissionActivity : AppCompatActivity() {
    private var adchainMission: AdchainMission? = null

    override fun onResume() {
        super.onResume()
        adchainMission = AdchainMission()
        adchainMission?.setEventsListener(this)
        loadMissionList()
    }
}

다음 단계

Previous퀴즈 Next배너

Last updated 1 month ago

Good morning

시작하기

AdchainMission 인스턴스 생성

이벤트 리스너 설정 (권장)

미션 목록 조회

응답 데이터 구조

MissionResponse (Android/iOS)

MissionListResponse (React Native)

Mission

MissionProgress (iOS)

MissionStatus (Android)

미션 클릭 처리

clickMission 동작 흐름

보상 수령

미션 상태 조회

Android

iOS

React Native

이벤트 리스너

리스너 인터페이스

이벤트 설명

onCompleted

onProgressed

onRefreshed

자동 추적 이벤트

UI 구현 가이드

미션 목록 표시

Android (RecyclerView)

iOS (UITableView)

React Native (FlatList)

진행률 UI 구현

완료된 미션 필터링

빈 상태 처리

보상 수령 UI

React Native 특수사항

unitId 파라미터

이벤트 리스너

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

주의사항

베스트 프랙티스

다음 단계