본문으로 건너뛰기

상세 연동 과정 및 플로우차트

사용자 매핑은 두 가지 진입 시나리오를 지원합니다. 두 경우 모두, 최종적으로 서비스의 사용자 키(partnerUid)와 일회성 매핑 토큰(token)을 Unifi 서버로 전송하여 매핑을 완료한 뒤 미션 달성을 기록하는 구조입니다.

시나리오 A: Unifi → 서비스 앱 진입​

  1. 앱 진입 및 토큰 수신: 사용자가 Unifi에서 서비스 미션을 클릭하면 서비스 페이지로 리다이렉트됩니다. 이때 일회성 토큰이 URL Query Parameter로 전달됩니다.
    예시: https://miniapp.line.me/{Service_App_ID}/...?token={mapping_token}
  2. 사용자 매핑 상태 확인: 서비스 진입 시, 서비스의 사용자 식별자(partnerUid)를 기준으로 사용자가 이미 Unifi 계정에 연결되어 있는지 확인합니다. (사용자 매핑 상태 확인 참조)
  3. 사용자 매핑 등록 요청 (미매핑인 경우): 연결되어 있지 않다면, 수신한 토큰과 partnerUid를 Unifi 서버로 전송하여 매핑을 등록합니다. (사용자 매핑 등록 참조)
  4. 미션 달성 요청: 사용자가 매핑되어 있다면, 미션 달성 API 호출 시 서비스의 사용자 키를 포함하여 미션 완료를 처리합니다.

시나리오 B: 서비스 앱 → 매핑을 위한 Unifi 로그인​

  1. 매핑 상태 확인: 서비스 내에서 사용자의 Unifi 매핑 상태를 확인합니다. (사용자 매핑 상태 확인 참조)
  2. Unifi 로그인 안내: 미매핑 상태라면, 미션을 수행하기 위해 Unifi 로그인이 필요하다는 안내(팝업 등)를 표시합니다.
  3. Unifi 로그인 진입 (Auth API 브라우저 리다이렉트): 프론트엔드(FE)가 브라우저 화면을 Unifi 서버 Auth Endpoint로 직접 이동시킵니다. URL에는 서비스의 partnerId, browserType, 그리고 로그인 후 복귀할 최종 목적지인 redirectUrl이 포함되어야 합니다.
    Preview:
    https://app-api-reward.unifi.me/v1/mission-users/auth?partnerId={partnerId}&browserType={browserType}&redirectUrl={URL Encoded redirectUrl}
    Prod:
    https://api-reward.unifi.me/v1/mission-users/auth?partnerId={partnerId}&browserType={browserType}&redirectUrl={URL Encoded redirectUrl}
  4. 로그인 후 서비스 앱으로 복귀: Unifi 로그인이 완료되면, Unifi 서버가 redirectUrl에 일회성 매핑 토큰(token=)을 덧붙여 사용자를 반환합니다.
    복귀 URL 형식: https://miniapp.line.me/{Service_App_ID}/{path}?myParam=xyz&token={mapping_token}
  5. 매핑 등록 및 미션 달성: 복귀 시 URL 파라미터로 수신한 토큰을 사용하여 매핑을 등록하고(사용자 매핑 등록 참조), 시나리오 A와 동일하게 미션 달성 API를 호출합니다.
경고

Auth API 프론트엔드 호출 방식 (시나리오 B)
/auth API는 내부적으로 LINE LIFF 로그인 URL을 구성하여 302 Redirect 응답을 반환합니다. 따라서 fetch나 axios로 호출하면 사용자의 화면이 로그인 페이지로 전환되지 않습니다. 반드시 템플릿 리터럴을 사용하여 브라우저의 window.location.href로 이동시켜야 합니다.

const redirectUrl = encodeURIComponent('https://miniapp.line.me/{Service_App_ID}/{path}?myParam=xyz');
window.location.href = `https://api-reward.unifi.me/v1/mission-users/auth?partnerId=${partnerId}&browserType=${browserType}&redirectUrl=${redirectUrl}`;