앱인토스 개발자센터 로고

개요 ​

앱인토스 SDK는 토스 앱 내에서 미니앱을 빠르게 구축하기 위한 WebView 및 React Native용 런타임 프레임워크예요.
SDK의 코어는 Granite이며, 앱 실행 환경과 통신을 담당하는 공통 런타임 프레임워크예요.

현재는 WebView SDK와 React Native SDK 두 가지 형태로 제공돼요.
이 문서는 Granite의 AppsInToss 구성요소와, 네이티브에서 전달되는 초기 데이터(InitialProps)를 설명해요.

샘플 프로젝트 보러가기 ↗ 예제 모음 확인하기 ↗

시그니처 ​

AppsInToss ​

typescript
AppsInToss: {
    registerApp(
      AppContainer: ComponentType<PropsWithChildren<InitialProps>>,
      { appName, context, router }: BedrockProps
    ): (initialProps: InitialProps) => JSX.Element;
    readonly appName: string;
}

InitialProps ​

typescript
type InitialProps = AndroidInitialProps | IOSInitialProps;

AppsInToss ​

AppsInToss.registerApp은 서비스의 기본 환경을 설정하고, 복잡한 초기 구성 없이 개발을 빠르게 시작하도록 도와줘요.
appName만 전달해도 파일 기반 라우팅, 쿼리 파라미터 처리, 뒤로 가기, 화면 가시성 감지 등 핵심 기능을 즉시 사용할 수 있어요.

제공 기능 ​

  • 파일 기반 라우팅: Next.js처럼 경로와 URL이 자동 매핑돼요.
    • /my-service/pages/home.ts → intoss://my-service/home
  • 쿼리 파라미터 처리: URL 스킴 파라미터(referrer 등)를 바로 사용 가능
  • 뒤로 가기 제어: 뒤로 가기 이벤트를 가로채 다이얼로그 표시나 화면 닫기 처리 가능
  • 화면 가시성 감지: 화면이 보이거나 가려지는 이벤트에 맞춰 동작 제어 가능

프로퍼티 ​

  • registerApp필수 · RegisterService

    앱을 초기화하고 라우팅/파라미터/뒤로가기/가시성 제어 기능을 활성화해요.

예제: 앱 등록하기 ​

tsx
import { AppsInToss } from '@apps-in-toss/framework';
import { PropsWithChildren } from 'react';
import { InitialProps } from '@granite-js/react-native';
import { context } from '../require.context';

function AppContainer({ children }: PropsWithChildren<InitialProps>) {
  return <>{children}</>;
}

// 앱 이름과 context만 전달하면 기본 설정이 완료돼요.
export default AppsInToss.registerApp(AppContainer, { context });

InitialProps ​

React Native 앱에서 사용자가 특정 화면으로 진입할 때, 네이티브(Android/iOS)가 앱으로 전달하는 초기 데이터 타입이에요.
플랫폼별 구조가 다르고, 초기 렌더링과 상태 설정에 필요한 핵심 정보가 포함돼요.

  • Android: AndroidInitialProps
  • iOS: IOSInitialProps

프로퍼티 ​

  • platform필수 · 'ios' | 'android'

    현재 앱이 실행 중인 플랫폼이에요.

  • initialColorPreference필수 · ColorPreference

    초기 컬러 테마예요. 사용자가 설정한 컬러 테마를 나타내요.

  • networkStatus필수 · NetworkStatus

    현재 기기의 네트워크 연결 상태와 연결된 네트워크예요.

  • schemestring

    현재 화면에 진입하는 데 사용한 URL 스킴이에요.

  • initialFontSize필수 · xSmall | Small | Medium | Large | xLarge | xxLarge | xxxLarge | A11y_Medium | A11y_Large | A11y_xLarge | A11y_xxLarge | A11y_xxxLarge

    (iOS only) iOS 시스템 폰트 크기예요. 기본값은 Large예요.

  • isVisible필수 · boolean

    (iOS only) 현재 화면이 보이는 상태인지 여부예요. 초기값은 true예요.

  • initialFontScale필수 · string

    (Android only) Android 접근성 설정을 반영한 시스템 폰트 스케일이에요.

예제: 초기 데이터 활용하기 ​

tsx
import { AppsInToss } from '@apps-in-toss/framework';
import { PropsWithChildren } from 'react';
import { InitialProps } from '@granite-js/react-native';
import { context } from '../require.context';

function AppContainer({ children, ...initialProps }: PropsWithChildren<InitialProps>) {
  // 화면 진입 시 네이티브가 내려준 초기값을 활용할 수 있어요
  console.log({ initialProps });
  return <>{children}</>;
}

export default AppsInToss.registerApp(AppContainer, { context });