> 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-zh/integration/getting-started.md).

# 开始使用

AppInToss 是 **客户端 SDK**和 **服务器 API** 通过两种方式集成。SDK 用于构建在 Toss App 内运行微应用的环境，API 则通过服务器间通信处理登录、支付等核心功能。

[查看示例项目 ↗](https://github.com/toss/apps-in-toss-examples/tree/main)

[查看示例合集 ↗](https://github.com/toss/apps-in-toss-examples/tree/main/examples)

{% hint style="info" %}
**请注意**

不能使用 iframe。使用 iframe 时，AppInToss 功能无法正常运行，并且在内部安全审查中也会被驳回。不过，用于嵌入 YouTube 视频内容时，可以例外使用 iframe。
{% endhint %}

***

### AppInToss 架构

AppInToss 主要 **SDK（客户端）** 和 **服务器 API** 由两层组成。

<figure><img src="https://3242303459-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbbsGTd7OgbyqnSM8Iwcy%2Fuploads%2FcBc5hfPtb6XP9MJNhJf0%2Fimage.png?alt=media&#x26;token=a9f54f5f-5c71-4440-adfc-6ae4ee182791" alt=""><figcaption></figcaption></figure>

SDK 会将摄像头、位置信息、支付 UI 等 **原生功能**桥接到微应用中直接使用。服务器 API 则 **负责合作方服务器与 AppInToss 服务器之间的通信**。登录令牌验证、支付审批、智能发送等需要在服务器端处理的功能都属于这里。

<figure><img src="https://3242303459-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbbsGTd7OgbyqnSM8Iwcy%2Fuploads%2FAqXKtJF05AYJew8fbKKb%2Fimage.png?alt=media&#x26;token=9dea6a0d-1764-43db-b4b4-304c1fedb1a7" alt=""><figcaption></figcaption></figure>

#### SDK — 微应用运行环境

合作方可以 **WebView SDK** 或 **React Native SDK** 选择其中一种来开发微应用。两个 SDK 都 `Granite`作为通用运行时层使用。

| SDK              | 说明                           |
| ---------------- | ---------------------------- |
| WebView SDK      | 可以在 Toss App 中快速运行现有 Web 服务。 |
| React Native SDK | 在需要原生级性能和与 Toss App 集成时使用。   |

合作方只需集成 SDK 并上传构建产物，经过内部审核流程后即可直接发布。无需复杂的原生开发，也能立即使用登录、支付、认证等核心功能。

#### 服务器 API — 服务器间通信

登录令牌验证、支付处理、智能发送等是 **合作方服务器 ↔ AppInToss 服务器** 之间的 API 通信处理。所有 API 通信都 **mTLS（双向 TLS 认证）** 进行保护。

***

### SDK 介绍

AppInToss SDK 的核心是 `Granite`。 `Granite`是初始化应用运行环境，并负责与 Toss App 通信的通用运行时层。

#### AppsInToss

`AppsInToss.registerApp`会设置服务的基本环境，帮助你无需复杂的初始配置就能快速开始开发。 **`appName`只要传入** 就可以立即使用以下功能。

* **基于文件的路由**：像 Next.js 一样，路径和 URL 会自动映射。
  * 示例： `/my-service/pages/home.ts` → `intoss://my-service/home`
* **查询参数处理**：可以直接使用 URL scheme 参数（如 referrer 等）。
* **返回控制**：可以拦截返回事件，处理显示对话框或关闭页面。
* **屏幕可见性检测**：可以根据页面显示或被遮挡的事件来控制行为。

**签名**

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

**示例：注册应用**

```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}</>;
}

// 只要传入 appName 和 context，默认设置就完成了。
export default AppsInToss.registerApp(AppContainer, { context });
```

#### InitialProps

当用户进入页面时，由原生（Android / iOS）传递给应用的 **初始数据类型**。其结构会因平台而异。

```typescript
type InitialProps = AndroidInitialProps | IOSInitialProps;
```

**属性**

* **platform** · 必需 · `'ios' | 'android'`

  当前应用正在运行的平台。
* **initialColorPreference** · 必需 · `ColorPreference`

  初始颜色主题。表示用户设置的颜色主题。
* **networkStatus** · 必需 · `NetworkStatus`

  当前设备的网络连接状态及所连接的网络。
* **scheme** · `string`

  用于进入当前页面的 URL scheme。
* **initialFontSize** · 必需 · ``xSmall` | `Small` | `Medium` | `Large` | `xLarge` | `xxLarge` | `xxxLarge` | `A11y_Medium` | `A11y_Large` | `A11y_xLarge` | `A11y_xxLarge` | `A11y_xxxLarge``

  （仅 iOS）iOS 系统字体大小。默认值为 `Large`。
* **isVisible** · 必需 · `boolean`

  （仅 iOS）当前页面是否处于可见状态。初始值为 `true`。
* **initialFontScale** · 必需 · `string`

  （仅 Android）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 });
```

***

### 使用 API

{% hint style="info" %}
**仅在需要集成服务器 API 时查看**

在使用 Toss 登录、Toss Pay、智能发送等需要服务器间通信的功能时进行设置。若只使用 SDK，可以跳过本部分。
{% endhint %}

mTLS 证书设置、防火墙配置、API 通用规范是 [使用 API 文档](/documentation/api-and-sdk-zh/integration/server-api.md)中查看。


---

# 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-zh/integration/getting-started.md?ask=<question>&goal=<endgoal>
```

`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.