setClipboardText

사용자의 클립보드에 임의의 문자열을 복사합니다. 링크, 인증 코드, 영수증 번호 등 "한 번 복사하면 편한" UX를 만들 때 사용합니다.

시그니처

import { setClipboardText } from '@apps-in-toss/web-framework';

declare function setClipboardText(text: string): Promise<void>;

파라미터

이름	타입	필수	설명
text	string	✓	클립보드에 복사할 문자열. 빈 문자열도 허용되지만 UX상 권장되지 않습니다.

반환값

• Promise<void> — 복사가 완료되면 resolve.
• 권한 denied로 인한 실패는 "권한" 섹션 참고. 웹 환경에서는 navigator.clipboard.writeText reject 같은 비권한 사유로도 실패할 수 있으므로 try/catch는 항상 권장됩니다.

권한

clipboard 권한이 필요합니다. 권한이 명시적으로 denied 상태이면 호출이 실패하므로 try/catch로 감싸세요. notDetermined 상태에서는 호출이 그대로 진행될 수 있지만, 사용자 경험상 먼저 다이얼로그로 승격시키는 것이 안전합니다. 상세 처리 패턴은 Guides — 권한 처리 패턴을 참고하세요.

호출부에 붙어 있는 유틸:

const status = await setClipboardText.getPermission();
// 'allowed' | 'denied' | 'notDetermined'

if (status !== 'allowed') {
  await setClipboardText.openPermissionDialog();
}

예제

최소 예제

import { setClipboardText } from '@apps-in-toss/web-framework';

async function copyInviteCode() {
  await setClipboardText('AIT-2026-HELLO');
}

실전 예제 — 복사 후 사용자에게 피드백

import { setClipboardText } from '@apps-in-toss/web-framework';

// `showAppToast`는 SDK가 제공하지 않습니다 — 앱의 자체 토스트/스낵바 컴포넌트로 대체하세요.
declare function showAppToast(message: string): void;

async function copyWithFeedback(value: string) {
  try {
    await setClipboardText(value);
    showAppToast('복사되었습니다');
  } catch (error) {
    showAppToast('복사에 실패했어요. 다시 시도해 주세요.');
    console.error(error);
  }
}

직접 실행해 보기

sdk-example에서 이 API를 실제로 호출하고 결과를 확인할 수 있습니다.

→sdk-example에서 실행해 보기

관련 API

• getClipboardText — 클립보드에서 텍스트를 읽습니다.

관련 가이드

• Recipes — 복사/붙여넣기 UX 패턴

외부 참조

• @apps-in-toss/web-framework — 상위 SDK 패키지. 실제 export는 내부적으로 @apps-in-toss/webview-bridge에서 가져옵니다.