> 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/common/growth/share/miniapp-share-link.md).

# 미니앱 공유 링크

`getTossShareLink` 함수는 사용자가 지정한 경로를 **토스 앱에서 열 수 있는 공유 링크**로 변환해주는 유틸이에요. 이 링크를 다른 사람에게 전달하면, 토스 앱이 실행되며 **지정한 딥링크 화면으로 바로 이동**할 수 있어요.

토스 앱이 설치되지 않은 경우에는 다음과 같이 동작해요.

* iOS → **앱스토어**로 이동
* Android → **플레이스토어**로 이동

경로는 토스 앱 내부 화면을 가리키는 **딥링크(deep link)** 형식이어야 해요. 예를 들어 아래와 같이 작성할 수 있어요.

```
intoss://<앱이름>
intoss://<앱이름>/about?name=test
```

또한 `ogImageUrl`을 지정하면 SNS·메신저 등 외부 플랫폼에서 공유될 때 표시되는 **미리보기(OG 이미지)** 를 직접 설정할 수 있어요. OG 이미지는 플랫폼별로 잘리는 방식이나 캐시 특성이 다르기 때문에, 공유 시 의도한 대로 노출되려면 아래를 지켜 주세요.

* 이미지 URL은 반드시 `https://`로 시작하는 **절대 경로**여야 합니다.
* **플랫폼별 권장 크기** · `비율, 파일 형식, 파일 용량 등의 세부 규칙은 내부 문서의 OG 이미지 규칙를 확인해 적용하세요.`

OG 이미지를 잘못 설정하면 미리보기가 의도와 다르게 보이거나, 일부 플랫폼에서 아예 노출되지 않을 수 있으니 주의해주세요.

{% hint style="info" %}
**캐시 관련 안내**

외부 플랫폼은 OG 메타데이터(이미지/제목/설명)를 캐싱해두기 때문에, 한 번 공유된 링크는 변경 사항이 바로 반영되지 않을 수 있어요. 빠른 반영이 필요하다면 각 플랫폼이 제공하는 **디버거 도구**를 이용해 캐시를 직접 초기화해 주세요.

* Kakao Debugger → <https://developers.kakao.com/tool/debugger/sharing>
* Facebook Debugger → <https://developers.facebook.com/tools/debug/>
  {% endhint %}

**시그니처**

```typescript
function getTossShareLink(url: string, ogImageUrl?: string): Promise<string>;
```

**파라미터**

* **url** · 필수

  딥링크로 열고 싶은 경로예요. `intoss://` 로 시작하는 문자열이어야 해요.
* ogImageUrl string

  공유 시 미리보기(OG)에 표시할 이미지 URL이에요. `https://` 로 시작하는 절대 경로여야 해요.

**반환 값**

* `Promise<string>`

  `deep_link_value`가 포함된 토스 공유 링크를 반환해요.

**예제**

{% tabs %}
{% tab title="js" %}

```js
import { share, getTossShareLink } from '@apps-in-toss/web-framework';

async function handleShare() {
  const tossLink = await getTossShareLink(
    'intoss://my-app',
    'https://static.toss.im/icons/png/4x/icon-share-dots-mono.png',
  );

  // 생성한 링크를 메시지로 공유해요.
  await share({ message: tossLink });
}
```

{% endtab %}

{% tab title="React" %}

```tsx
import { share, getTossShareLink } from '@apps-in-toss/web-framework';
import { Button } from '@toss/tds-mobile';

function ShareButton() {
  async function handleClick() {
    const tossLink = await getTossShareLink(
      'intoss://my-app',
      'https://static.toss.im/icons/png/4x/icon-share-dots-mono.png',
    );

    // 생성한 링크를 메시지로 공유해요.
    await share({ message: tossLink });
  }

  return <Button onClick={handleClick}>공유하기</Button>;
}
```

{% endtab %}

{% tab title="React Native" %}

```tsx
import { share, getTossShareLink } from '@apps-in-toss/framework';
import { Button } from '@toss/tds-react-native';

function ShareButton() {
  async function handleClick() {
    const tossLink = await getTossShareLink(
      'intoss://my-app',
      'https://static.toss.im/icons/png/4x/icon-share-dots-mono.png',
    );

    // 생성한 링크를 메시지로 공유해요.
    await share({ message: tossLink });
  }

  return <Button onPress={handleClick}>공유하기</Button>;
}
```

{% endtab %}
{% endtabs %}

**예제 앱 체험하기**

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 저장소에서 [with-share-link](https://github.com/toss/apps-in-toss-examples/tree/main/with-share-link) 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.

QR 코드 링크: intoss\://with-share-link

### 앱 출시 전 테스트 안내

`intoss://` 스킴은 **앱이 정식 출시된 이후에만 접근 가능해요.** 출시 전 기능 테스트를 위해서는 업로드 시 생성된 **테스트 스킴(QR 코드)** 를 활용해야 해요.

**① QR 코드에서 `deploymentId` 확인하기**

앱 번들을 업로드할 때마다 새로운 `deploymentId`가 발급돼요. 테스트 스킴에서는 `_deploymentId` 는 필수 파라미터예요.

예시 :

```
intoss-private://appsintoss?_deploymentId=0198c000-68c3-7d2b-0000-2c00000005ec
```

**② 스킴에 path/query 적용하여 테스트하기**

* 하위 path를 적용한 경우 :

```
intoss-private://appsintoss/path/pathpath?_deploymentId=0198c000-68c3-7d2b-0000-2c00000005ec
```

* 쿼리 파라미터를 적용한 경우 : queryParams는 반드시 URL-encoding이 필요해요.

```
intoss-private://appsintoss?_deploymentId=0198c000-68c3-7d2b-0000-2c00000005ec&queryParams=%7B%22categoryKey%22%3A%22
```


---

# 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/common/growth/share/miniapp-share-link.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.