Mission & Reward 연동 가이드

본 가이드는 LINE Mini App 환경에서 Unifi Mini와 서비스 간의 미션, 리워드 지급, 사용자 매핑에 대한 전체 연동 과정을 다룹니다.

Unifi Mission & Reward는 파트너사가 만든 미션을 Unifi에 보여주고, 사용자가 그 미션을 달성하면 Unifi 중앙 리워드 월렛에서 보상을 바로 지급하는 시스템입니다. 파트너사가 보상을 직접 보내지는 않으며, 미션을 만들고 달성 정보를 전달하는 것까지가 파트너사가 맡는 부분입니다.

미션 구조 및 기본 정책

Unifi 시스템의 미션은 Mission Group > Individual Mission의 계층 구조로 관리됩니다.

• Mission Group: 특정 목적을 위해 묶인 미션의 집합입니다. 각 Mission Group은 각 파트너(Partner ID)에 매핑됩니다. Mission Group 하위에 여러개의 Individual mission을 생성하고 운영할 수 있습니다.
• Individual Mission: 사용자가 완료해야 하는 구체적인 미션입니다.(예: 특정 레벨 도달, 특정 금액 이상 구매).
• Reset Time: Daily 미션에만 해당되며 미션 초기화 시간은 Unifi와 사전 협의 후 지정된 시간에 따라 설정 및 운영됩니다.

미션 타입

타입	설명
데일리 (DAILY)	매일 다시 참여할 수 있습니다. 설정한 초기화 시각(Reset Hour)이 지나면 진행 상태가 처음으로 돌아갑니다. 보상을 받지 않은 상태여도 초기화 시각이 지나면 받을 수 없습니다. 초기화 시각은 JST(일본 표준시) 기준입니다.
1회성 (ONE_TIME)	운영 기간 중 한 번만 참여하고 달성할 수 있습니다. 종료 시각까지 참여할 수 있고, 종료된 뒤에는 참여할 수 없습니다.

미션 구조: 싱글 미션 vs. 미션 그룹

미션은 싱글 미션 또는 미션 그룹으로 만들 수 있습니다.

• 싱글 미션: 미션 1개를 달성하면 보상 1개를 받는 구조입니다.
• 미션 그룹: 싱글 미션 여러 개를 하나로 묶고, 그중 정해진 개수(예: 3개 중 3개)를 달성하면 보상 1개를 받는 구조입니다.
• 하나의 그룹에 싱글 미션을 여러 개 넣을 수 있습니다.
• 보상은 싱글 미션에 개별로 붙일 수도 있고, 미션 그룹 달성에만 붙일 수도 있습니다.

팁

미션 그룹으로 운영하려면 구성을 미리 Unifi 담당자와 함께 논의해 주세요.

서비스 퍼블리셔 연동 순서 (To-Do List)

원활한 시스템 연동을 위해 다음 순서대로 작업을 진행해 주세요.

단계	담당 팀	작업 (To-Do)
Step 1 준비	Infra / Backend	API 통신을 허용하기 위해 서비스 서버의 모든 Outbound IP 주소를 Unifi 담당자에게 제공합니다(Firewall 개방 필요). Unifi가 발급한 Partner ID와 API Key를 서버 환경 변수에 설정합니다.
Step 2 기획 정보	Biz / PM	[사전 전달 정보]에 명시된 서비스 에셋(이미지, 다국어 텍스트)을 준비합니다. 미션 구성(Mission Key 발급 방식 포함)과 리워드 유형(Fixed, Lucky Draw)을 확정하여 Unifi에 제출합니다. Unifi가 설정을 완료한 후 최종 Mission Key를 전달합니다.
Step 3 사용자 매핑	Frontend / Backend	(FE) 서비스 진입 시 URL 파라미터로 전달되는 일회성 토큰을 파싱하는 로직을 추가합니다. (FE) 매핑되지 않은 사용자를 Unifi Auth API로 보내는 브라우저 리다이렉트 로직을 추가합니다. (BE) 사용자 매핑 확인 API(GET /v1/mission-users)를 연동합니다. (BE) 토큰 기반 사용자 매핑 등록 API(POST /v1/mission-users/connect)를 연동합니다.
Step 4 미션 달성	Backend	(BE) 사용자가 미션을 완료할 때 미션 달성 API(POST /v1/achieve)를 연동합니다. (BE) Preview 환경에서 테스트한 후 Production 환경에 배포합니다.