> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/integration/getting-started.md). # Getting started AppsInToss is **Client SDK**and **Server API** There are two integration methods. The SDK sets up the mini-app runtime environment inside the Toss app, and the API handles core functions such as login and payments through server-to-server communication. [View sample project ↗](https://github.com/toss/apps-in-toss-examples/tree/main) [Check out the examples ↗](https://github.com/toss/apps-in-toss-examples/tree/main/examples) {% hint style="info" %} **Please note** You can't use iframes. If you use an iframe, AppsInToss features won't work properly, and it will also be rejected during internal security review. However, using an iframe to embed YouTube video content is allowed as an exception. {% endhint %} *** ### AppsInToss architecture AppsInToss is broadly divided into **SDK (client)** and **Server API** into two layers.
The SDK acts as a bridge so that native features such as camera, location information, and payment UI **native features**can be used directly in mini-apps. The server API **communication between the partner's server and the AppsInToss server**is responsible for. Functions that must be processed on the server, such as login token verification, payment approval, and smart sending, fall into this category.
#### SDK — mini-app runtime environment Partners **WebView SDK** or **React Native SDK** choose one to develop their mini-apps. Both SDKs `Granite`use Granite as a common runtime layer. | SDK | Description | | ---------------- | ------------------------------------------------------------------------- | | WebView SDK | You can quickly run an existing web service inside the Toss app. | | React Native SDK | Use this when you need native-level performance and Toss app integration. | Partners can upload the build artifact after integrating only the SDK and can launch it right away after internal review. You can use core features such as login, payments, and authentication immediately without complex native development. #### Server API — server-to-server communication Login token verification, payment processing, smart sending, and more are handled through **partner server ↔ AppsInToss server** API communication. All API communication is **mTLS (mutual TLS authentication)** protected by. *** ### SDK Introduction The core of the AppsInToss SDK is `Granite`. `Granite`It initializes the app runtime environment and serves as a common runtime layer that handles communication with the Toss app. #### AppsInToss `AppsInToss.registerApp`It sets up the service's default environment and helps you start development quickly without complex initial configuration. **`appName`By passing only** you can immediately use the features below. * **File-based routing**: Paths and URLs are automatically mapped like in Next.js. * Example: `/my-service/pages/home.ts` → `intoss://my-service/home` * **Query parameter handling**: URL scheme parameters (such as referrer) can be used directly. * **Back button control**: You can intercept back events to show dialogs or close screens. * **Screen visibility detection**: You can control behavior based on events when the screen becomes visible or hidden. **Signature** ```typescript AppsInToss: { registerApp( AppContainer: ComponentType>, { appName, context, router }: BedrockProps ): (initialProps: InitialProps) => JSX.Element; readonly appName: string; } ``` **Example: Registering an app** ```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) { return <>{children}; } // The default setup is complete if you pass only appName and context. export default AppsInToss.registerApp(AppContainer, { context }); ``` #### InitialProps The **initial data type**that native (Android / iOS) passes to the app when the user enters a screen. It differs by platform. ```typescript type InitialProps = AndroidInitialProps | IOSInitialProps; ``` **Properties** * **platform** · Required · `'ios' | 'android'` The platform on which the current app is running. * **initialColorPreference** · Required · `ColorPreference` The initial color theme. It reflects the color theme set by the user. * **networkStatus** · Required · `NetworkStatus` The device's current network connection status and connected network. * **scheme** · `string` The URL scheme used to enter the current screen. * **initialFontSize** · Required · ``xSmall` | `Small` | `Medium` | `Large` | `xLarge` | `xxLarge` | `xxxLarge` | `A11y_Medium` | `A11y_Large` | `A11y_xLarge` | `A11y_xxLarge` | `A11y_xxxLarge`` (iOS only) This is the iOS system font size. The default is `Large`It is. * **isVisible** · Required · `boolean` (iOS only) Whether the current screen is visible. The initial value is `true`It is. * **initialFontScale** · Required · `string` (Android only) The system font scale reflecting Android accessibility settings. **Example: Using initial data** ```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) { // You can use the initial values provided by native when entering the screen console.log({ initialProps }); return <>{children}; } export default AppsInToss.registerApp(AppContainer, { context }); ``` *** ### Using the API {% hint style="info" %} **Please check this only if server API integration is needed** Set this up when using features that require server-to-server communication, such as Toss Login, Toss Pay, and Smart Sending. If you're using only the SDK, you can skip this section. {% endhint %} mTLS certificate setup, firewall configuration, and API common specifications [API Usage Guide](/documentation/api-and-sdk-en/integration/server-api.md)for more details. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/integration/getting-started.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.