설정 및 사전 준비

서버 Firewall 설정 사전 요구사항

연동을 진행하기 전에, Unifi 서버와의 원활한 통신 및 API 호출(사용자 매핑 확인, 등록, 미션 달성 등)을 위해 백엔드에서 다음 Firewall 설정과 인증 키 설정을 완료해야 합니다.

• 서버 IP 등록 (Firewall 개방): 서비스 서버가 Unifi 서버로 API를 호출할 수 있도록, Unifi의 Firewall에 해당 IP가 Whitelist에 등록되어야 합니다. 연동을 시작하기 전에 서비스 서버의 모든 Outbound IP 주소를 Unifi 담당자에게 제공해 주세요.
• 인증 키 설정: Unifi 담당자로부터 X-Partner-Id와 X-Api-Key를 사전에 발급받아 백엔드 환경 변수에 설정하고, API 호출 시 요청 헤더에 포함해야 합니다.

Unifi 시스템 등록을 위한 사전 전달 정보

서비스를 Unifi 미션/리워드 시스템에 노출하려면, 연동 개발 전에 다음 기획 정보와 에셋을 정리하여 Unifi 담당자에게 전달해야 합니다.

Partner (서비스 퍼블리셔) 기본 정보

• 메인 URL: 회사 또는 서비스의 메인 웹사이트 주소입니다.
• 로고 이미지: 420 × 420 픽셀. Partner를 대표하는 이미지입니다.
• 스크린샷 이미지: 600 × 1296 픽셀(최대 7장). Partner를 알릴 수 있는 이미지로, 미션 페이지의 Preview 영역에 노출됩니다.
• 다국어 Partner 명: 영어(EN)는 필수이며, 그 외 언어는 선택입니다.
• 다국어 Partner 타이틀 (짧은 설명): Partner를 소개하는 짧은 설명입니다. 5개 언어(EN, KR, JA, TH, TW)로 제공해야 합니다.
• 다국어 Partner 상세 설명: 추가로 Partner에 대해 알릴 수 있는 내용이 있다면 기재해 주세요. 5개 언어(EN, KR, JA, TH, TW)로 제공해야 합니다.
• 공식 소셜 채널 (OA): 공식 소셜 채널 링크(LINE, X, Facebook, Discord, Instagram, Medium).
• Tag: 서비스와 관련된 키워드입니다(예: #puzzle, #RPG). Partner 설명과 함께 노출됩니다.

각 항목이 실제로 어느 영역에 노출되는지는 아래 라벨링된 화면을 참고해 주세요.

Mission Group (서비스 매칭) 기본 정보

• 다국어 타이틀 & 소개: Unifi 앱 미션 목록에 표시될 타이틀과 소개 문구입니다. 5개 언어(EN, KR, JA, TH, TW)로 제공해야 합니다.
• 메인 배너 이미지: 1280 × 720 픽셀 1장. Mission 페이지에 진입할 때 노출됩니다.
• 매칭할 Service ID: 이 Mission Group과 연결될 서비스의 고유 식별자입니다.
• 미션 노출 방식: 현재는 등록된 모든 미션을 한 번에 표시하는 '전체 노출(목록형)' 방식으로 운영됩니다. (Single Mission의 경우 자동으로 '전체 노출'로 선택됩니다.)
• 최종 클리어 조건: 전체 그룹을 달성한 것으로 간주하기 위해 그룹 내에서 완료해야 하는 개별 미션의 목표 개수를 설정합니다. (Single Mission의 경우 자동으로 1로 설정됩니다.)
• 미션 유의사항 (선택): Mission Group에 다국어로 유의사항을 적으면 상세 화면(App Detail Page)에 함께 노출됩니다(예: "이 미션의 리워드는 일본 사용자에게만 제공됩니다"). 적지 않으면 아무 문구도 노출되지 않습니다.

Individual Mission 상세 및 Mission Key 발급 방식

Unifi에 등록되는 각 Individual Mission은 API 식별을 위한 Mission Key를 가집니다. 개발 편의에 따라 아래 두 가지 방식 중에서 선택할 수 있습니다.

1. Unifi 랜덤 생성: Unifi 시스템이 랜덤한 영숫자 키를 생성하여 전달합니다.
2. Partner의 기존 ID 매핑: 서비스 서버에서 관리하는 기존 Mission/Achievement ID(Mission ID)를 제공하면, 이를 Unifi 시스템에 Mission Key로 직접 등록합니다. 별도의 매핑 값을 관리할 필요가 없어 개발 편의성이 향상됩니다.

팁

Mission Key 중복 금지 정책
생성 방식이나 Partner ID 등록 여부와 관계없이, 동일한 서비스(Service ID) 내에서 Mission Key는 절대 중복되어서는 안 됩니다.

Mission Key는 미션 달성 정보를 받기 위해 사전에 Unifi와 공유되어야 하며, 공유된 키로 정보가 들어올 때 비로소 보상이 진행됩니다. 달성 정보 전달 API는 API 스펙을 참고해 주세요.

• Mission Type Name: 미션의 성격을 나타내는 고유한 영문 키워드입니다(예: PLAY, ACHIEVE_LEVEL).
• 다국어 미션 명: 사용자에게 노출되는 실제 미션 목표 문구입니다. 5개 언어(EN, KR, JA, TH, TW)로 제공해야 합니다.
• 미션 썸네일 이미지 (선택): 400 × 400 픽셀(미제공 시 기본 이미지로 대체됩니다).
• 미션 링크 (진입 URL): 사용자가 Unifi 앱에서 미션을 클릭했을 때 이동할 서비스 URL입니다. 접속 환경별로(LIFF / Web / Mini) 준비해 주세요 — 해당 환경의 URL이 없으면 그 환경에서는 미션이 노출되지 않습니다.

리워드 구성

리워드 방식

MINI 파트너사는 두 가지 방식 중 하나를 고릅니다.

방식	설명	설정 단위
고정 (FIXED)	미션을 달성하면 정해진 JPYC 수량을 그대로 지급합니다.	보상 수량
럭키드로우 (LUCKY_DRAW)	미션을 달성하면 뽑기권을 지급하고, 사용자가 뽑기를 해서 서로 다른 보상을 받습니다.	뽑기권 개수

• Reward Unit: Individual Mission 클리어 / Mission Group 클리어 중 어느 시점에 리워드를 지급할지 선택합니다.

예산과 보상액 정하기

• 미션 전체 예산은 미션 시작 2주 전까지 함께 논의합니다. 미션을 여러 개 운영할 때는 합의한 전체 예산을 나눠서 설정할 수 있습니다.
• 개별 보상액은 방식에 따라 다르게 설정합니다.
  • 고정: 한 번에 지급하는 수량
  • 럭키드로우: 지급하는 뽑기권 개수
• 사용자당 최대 보상액은 선택 항목이며, 고정과 럭키드로우 모두 설정할 수 있습니다. 설정하지 않으면 제한이 없습니다.
• 럭키드로우는 전체 예산과 함께 등수별 보상 금액, 당첨자 수(당첨 확률 구조)까지 정해야 하므로 Unifi 사업팀과 미리 협의해 주세요.

예산이 모두 쓰이면

보상 예산이 모두 쓰이거나 설정한 한도에 도달하면, 그 보상에 연결된 미션 또는 미션 그룹은 자동으로 종료됩니다. 운영 상황에 따라 예정보다 일찍 종료될 수 있습니다.

운영 체크리스트

미션 운영 중에는 다음 사항을 확인해 주세요.

• 파트너 정보 미리 등록: 미션 페이지에 파트너 정보가 함께 보이므로, 미션을 설정하기 전에 파트너 정보가 등록되어 있어야 합니다.
• Mission Key 미리 공유: 미리 공유되지 않으면 달성 정보를 미션과 연결할 수 없어 보상도 지급되지 않습니다.
• 1회성 미션 중복 방지: 1회성 미션은 완료 정보를 여러 번 받아도 보상은 한 번만 지급합니다. 반복해서 보상을 주고 싶다면 Unifi 담당자와 미리 논의해 주세요.
• 미션 시작·종료 시각: 분 단위까지 설정할 수 있습니다.

팁

미션 달성 API 등 기술 연동 관련 문의는 API 스펙 문서의 안내를 따라 주세요.