앱인토스 소개 – 출시 전 체크리스트와 버전 관리, 검토부터 롤백(Rollback)까지

앱인토스 출시 체크리스트는 미니앱을 올리기 전에 마주치는 관문이고, 비게임 가이드를 열어 보면 항목마다 검수 승인 여부와 이어지는 기준이라는 것을 알 수 있습니다. 이 글은 그 문서를 구역별로 읽고, 출시한 뒤의 버전 관리와 롤백 절차까지 이어서 정리합니다.

프로젝트 진행 방식 글에서 출시 순서를 한 줄로만 적었기 때문에, 여기서는 체크리스트의 항목과 배포 단계의 조건을 공식 문서 문장 기준으로 풀어 씁니다. 마지막에는 제 물마시기 미니앱 코드에서 항목과 맞닿는 두 곳을 옮겼어요.

다만 제가 검수를 제출해서 받은 결과를 이 글에 담지는 않았습니다. 문서에 적힌 기준과 앱 코드만 다룹니다.

앱인토스 출시 체크리스트는 10개 구역으로 나뉜다

문서 제목은 비게임 출시 가이드이고, 미니앱에 공통으로 적용되는 기준과 기능별 가이드가 한 페이지에 들어 있습니다. 체크 항목을 제가 직접 세어 보니 10개 구역에 76개 항목이었어요. 문서가 항목을 지속적으로 최신화한다고 밝혀서 이 숫자는 글을 쓴 날 기준입니다.

가장 먼저 읽을 문장은 도입부입니다. 체크리스트를 지키지 않았거나 다크 패턴(Dark Pattern)이 확인되면 검수가 승인되지 않고, 출시 뒤에 확인돼도 서비스 노출이 제한되거나 중단될 수 있다고 적혀 있어요.

접속과 내비게이션 바 항목은 뒤로가기에 몰려 있다

접속 및 앱 내 기능 구역(4개)은 미니앱이 정상적으로 열리는지, 앱 정보의 앱 내 기능으로 소개한 기능을 미니앱에서 똑같이 쓸 수 있는지, 등록한 스킴이 제대로 연결되는지를 봅니다. 스킴으로 들어온 뒤 뒤로가기가 작동하는지도 한 항목이에요.

내비게이션 바 구역은 10개로 가장 길고, 앱인토스 내비게이션 바를 쓰는 것이 전제입니다. 기본 로고와 앱 이름은 지울 수 있지만 파트너사 자체 로고를 넣는 것은 허용되지 않아요. 토스 내비게이션 바의 뒤로가기 버튼과 직접 만든 뒤로가기 버튼이 동시에 보이면 안 되고, 최초 화면에서 뒤로가기를 누르면 미니앱이 종료돼야 합니다. 사용자 식별키 구역(3개)은 식별자를 저장해 정상 시작하는지, 종료 후 재접속해도 데이터가 유지되는지를 확인합니다.

앱인토스 출시 체크리스트의 보안 항목은 렌더링 방식을 정한다

보안 및 안정성 구역(7개)은 웹으로 만드는 사람에게 제약이 가장 큰 곳입니다.

• 외부에서 받은 코드를 실행하는 기능(eval 등)은 쓸 수 없습니다.
• 자사 사이트로 이동하거나 그 콘텐츠를 렌더링할 수 없고, 최종 콘텐츠는 토스 도메인 안에서 렌더링돼야 합니다. 예시로 window.location.replace와 자사 도메인을 불러오는 웹뷰·iframe 중첩이 적혀 있어요.
• 서버 사이드 렌더링(Server-Side Rendering, SSR)은 쓸 수 없고, 클라이언트 사이드 렌더링(Client-Side Rendering, CSR)이나 정적 사이트 생성(Static Site Generation, SSG)만 됩니다.
• WebSocket은 암호화된 wss://만, API 통신은 HTTPS만 허용됩니다.
• 로그인 정보와 결제 내역 같은 민감 정보는 DB에 암호화해서 저장해야 합니다.

HTTPS 조건은 테스트 문서와 이어집니다. 샌드박스에서는 HTTP 요청이 허용되지만 라이브 환경에서는 HTTPS만 허용되고, HTTP 기반 API는 토스 앱에서 차단된다고 테스트 문서의 자주 묻는 질문에 적혀 있어요. 서버와 통신한다면 서버의 CORS 허용 Origin에 미니앱 Origin을 넣어야 하는데, 어떤 Origin이 필요한지는 SDK 버전에 따라 달라서 원문의 표기를 확인해야 합니다.

앱인토스 출시 체크리스트의 이용 동작과 UX 조건

서비스 이용 동작 구역(14개)에는 구현할 때 놓치기 쉬운 문장이 모여 있습니다. 미니앱 테마는 라이트 모드로 구현돼 있어야 하고, 지도처럼 꼭 필요한 경우를 빼면 제스처 확대·축소는 꺼져 있어야 해요. 스크롤, 터치, 화면 전환 반응이 2초 이상 지연되면 안 되며, 공유 기능에는 intoss-private:// 대신 intoss:// 스킴을 써야 합니다. 위치나 알림 같은 기기 권한은 사용자 동의를 먼저 받고, 허용하지 않아도 나머지 기능은 정상 작동해야 한다고 적혀 있어요.

UX 구역(7개)에서는 진입하자마자 토스 로그인이나 알림 동의문 같은 바텀시트가 자동으로 나타나면 안 된다는 항목이 눈에 띕니다. 특정 화면 전환에서 바텀시트로 행동을 강제로 유도하는 것도, 링크나 컴포넌트로 자사 서비스 이동이나 자사 앱 설치를 유도하는 것도 금지돼요.

로그인, 결제, 광고 구역은 쓰는 기능에 따라 적용된다

나머지 네 구역은 해당 기능을 쓸 때 적용되는 것으로 읽힙니다. 문서가 “해당 기능을 쓰는 경우에만”이라고 구분해 적은 것은 아니고, 로그인 구역 첫 항목이 “토스 로그인을 사용하는 경우”로 시작하는 데서 제가 그렇게 읽었어요.

광고를 인트로·로딩·컷신·팝업 모달 같은 일시적인 화면에 노출하지 않는다는 항목은 UX 구역에 따로 있습니다. 광고 쪽은 수익화 글과 같이 보면 이해가 쉬워요.

물마시기 앱 코드에서 체크리스트 항목과 맞닿는 두 곳

앱인토스 출시 체크리스트 항목에 대응하는 코드가 확인되는 곳만 옮깁니다. 첫째는 네비게이션 바 구역의 뒤로가기 항목입니다. 물마시기 앱의 이 구독은 바텀시트가 열려 있을 때만 토스의 뒤로가기 이벤트를 받아 시트를 닫아요. 같은 파일에는 다른 화면용 구독도 따로 있습니다.

  useEffect(() => {
    if (!sheet || !("ReactNativeWebView" in window)) return;
    return graniteEvent.addEventListener('backEvent', {
      onEvent: () => setSheet(null),
      onError: (error) => console.error('뒤로가기를 처리하지 못했어요.', error),
    });
  }, [sheet]);

둘째는 인앱 광고 구역의 사전 로딩 항목입니다. 전면 광고를 화면이 열릴 때 미리 불러 두고, 불러오기가 끝난(loaded) 상태일 때만 보여 줄 수 있게 되어 있어요. 아래는 useCliffAd의 불러오는 부분입니다.

  const load = useCallback(() => {
    if (!adGroupId || loadedRef.current || !cliffSupported()) return;
    try {
      disposerRef.current?.();
      disposerRef.current = loadFullScreenAd({
        options: { adGroupId },
        onEvent: (event) => { if (event.type === 'loaded') loadedRef.current = true; },
        onError: () => { loadedRef.current = false; },
      });
    } catch {
      loadedRef.current = false;
    }
  }, [adGroupId]);

  useEffect(() => {
    load();
    return () => disposerRef.current?.();
  }, [load]);

이 대응은 코드를 체크리스트 문장에 맞춰 읽은 것이고, 이 앱이 검수에서 어떤 판정을 받았는지를 말해 주지는 않습니다.

새 버전은 번들 업로드부터 출시까지 네 단계를 거친다

출시 뒤의 업데이트도 처음 출시와 같은 방식입니다. 공식 문서는 새 기능을 넣거나 오류를 고쳤다면 기존과 같은 방식으로 새 앱 번들(Bundle, .ait)을 올리라고 안내합니다. 올린 번들은 검토 요청, 승인, 출시 단계를 다시 거치고, 승인된 뒤 출시하기 버튼을 눌러야 새 버전이 기존 앱을 대체해요. 아래 네 단계의 순서는 버전 관리 문서의 업로드·검토·출시에 테스트 문서의 내용을 끼워 넣어 제가 이어 붙인 것이고, 테스트를 이 자리에서 해야 한다는 문장이 문서에 있는 것은 아닙니다.

롤백은 이전 버전을 골라 다시 출시하는 방식이다

롤백(Rollback)은 앱 출시 메뉴에서 이전에 출시한 버전 목록을 보고, 되돌릴 버전을 선택한 뒤 출시하기 버튼을 누르는 순서입니다. 롤백도 사용자에게 즉시 반영돼서 버전을 신중히 고르라고 문서가 당부해요.

출시 전에 토스 앱에서 직접 확인하는 방법도 문서에 있습니다. 로컬 브라우저나 샌드박스 앱에서 정상이어도 토스 앱 웹뷰에서는 문제가 생길 수 있어서, 업로드한 번들을 테스트 스킴으로 연 뒤 내비게이션 바의 더보기에서 웹 디버그 툴즈를 열면 Log, System, Network, Element 탭으로 로그와 네트워크 요청, 페이지 구조를 볼 수 있습니다. 토스 앱에서만 흰 화면이 보이는 경우를 예로 들어 설명해요.

문서가 말하지 않는 부분이 하나 있습니다. 롤백할 때 검토를 다시 거치는지는 적혀 있지 않아서, 이 글에서는 단정하지 않았어요.

앱 실행에 심각한 오류가 생기면 문서는 채널톡으로 바로 문의하라고 안내합니다. 출시 직후에는 오류·크래시 로그, Sentry, API 응답 지연과 실패율, 외부 리소스·CDN 로딩 실패를 모니터링하라고 권하고요. 내비게이션 바의 신고하기로 받은 의견은 콘솔의 신고 내역 메뉴에서 볼 수 있습니다. 출시한 뒤에도 사후 검수가 있어서 개선 요청을 받을 수 있고, 법·정책 위반이 발견되면 긴급 운영 중단이 먼저 진행될 수 있다고 적혀 있어요.

앱인토스는 토스 앱 안에서 미니앱을 서비스하는 플랫폼이고, 공식 안내는 앱인토스 개발자센터에 있습니다.

이 글은 직접 만들고 운영하며 남긴 기록입니다. 적힌 수치는 작성 시점의 제 계정 기준이며, 같은 결과나 수익을 보장하지 않습니다.