partner.addAccessoryButton

상단 네비게이션 바에 아이콘 + 라벨을 가진 악세서리 버튼을 추가합니다. 버튼 클릭 이벤트는 tdsEvent.addEventListener("navigationAccessoryEvent", callback)로 수신합니다.

시그니처

addAccessoryButton은 partner 네임스페이스 객체의 멤버로 노출됩니다. 함수 자체를 단독으로 import하지 않습니다.

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

type AddAccessoryButtonOptions = {
  id: string;
  title: string;
  icon: {
    name: string;
  };
};

declare const partner: {
  addAccessoryButton(options: AddAccessoryButtonOptions): Promise<void>;
};

파라미터

이름	타입	필수	설명
options	AddAccessoryButtonOptions	✓	버튼 설정 객체.
options.id	string	✓	버튼의 고유 식별자. 이벤트 수신 시 어떤 버튼이 눌렸는지 구별하는 데 사용됩니다.
options.title	string	✓	버튼에 표시할 라벨 텍스트.
options.icon.name	string	✓	버튼 아이콘의 이름. 디자인 시스템 아이콘 토큰을 사용하세요.

반환값

• Promise<void> — 버튼이 추가되면 resolve.

권한

권한이 필요하지 않습니다 — partner.addAccessoryButton은 별도의 PermissionName에 바인딩되지 않습니다. 권한이 필요한 다른 네임스페이스의 일반적인 처리 흐름은 Guides — 권한 처리 패턴을 참고하세요.

예제

최소 예제

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

await partner.addAccessoryButton({
  id: 'btn-favorite',
  title: '즐겨찾기',
  icon: { name: 'icon-star-mono' },
});

실전 예제 — 클릭 이벤트 수신과 cleanup

import { partner, tdsEvent } from '@apps-in-toss/web-framework';
import { useEffect } from 'react';

function ProductDetailPage() {
  useEffect(() => {
    const BUTTON_ID = 'btn-favorite';

    partner.addAccessoryButton({
      id: BUTTON_ID,
      title: '즐겨찾기',
      icon: { name: 'icon-star-mono' },
    });

    const unsubscribe = tdsEvent.addEventListener(
      'navigationAccessoryEvent',
      (event) => {
        if (event.id === BUTTON_ID) {
          console.log('즐겨찾기 버튼이 눌렸습니다');
        }
      },
    );

    return () => {
      // 화면을 떠날 때 버튼과 이벤트 리스너를 정리합니다.
      partner.removeAccessoryButton();
      unsubscribe();
    };
  }, []);

  return <main>{/* 페이지 콘텐츠 */}</main>;
}

직접 실행해 보기

sdk-example의 Partner 페이지에서 partner.addAccessoryButton 카드를 실행해 결과를 확인할 수 있습니다.

→sdk-example에서 실행해 보기

관련 API

• partner.removeAccessoryButton — 추가한 악세서리 버튼을 제거합니다.

관련 가이드

• Guides — 악세서리 버튼 UX — addAccessoryButton/removeAccessoryButton과 navigationAccessoryEvent 구독의 라이프사이클·id 라우팅·멀티 버튼·상태 토글까지 한 곳에 정리한 가이드.

외부 참조

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