미니앱 공유 링크

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

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

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

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

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

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

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

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

캐시 관련 안내

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

• Kakao Debugger → https://developers.kakao.com/tool/debugger/sharing
• Facebook Debugger → https://developers.facebook.com/tools/debug/

시그니처

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

파라미터

• url · 필수

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

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

반환 값

• Promise<string>

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

예제

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 });
}

React

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

React Native

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

예제 앱 체험하기

apps-in-toss-examples 저장소에서 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