푸시 알림 (`push`)

🚀 추가된 버전 : v1.0.0 v1.0.0 v1.0.0
🔔 최신화 일자: 2025-07-28

개요

push 네임스페이스는 푸시 알림 관련 기능을 제공합니다.

푸시 토큰을 nachocode 서버에 등록 및 삭제
로컬 푸시 알림을 예약 및 취소
푸시 토픽 구독 및 취소
디바이스의 구독된 토픽 조회

푸시 알림 사용법을 더 자세히 알아보려면 아래 가이드를 참고해보세요.

푸시 알림 상세 가이드

➡️ 푸시 토큰 가이드 보러가기

➡️ 개인화 푸시 가이드 보러가기

➡️ 토픽 푸시 가이드 보러가기

필수 선행 작업

nachocode SDK로 푸시 알림 기능을 사용하기 위해서는 nachocode 대시보드의
[ 앱 기능 > 푸시 알림 > 설정 ] 탭에서 푸시 알림 설정이 모두 완료된 후 빌드된 경우에만 작동합니다.

푸시 알림 설정하기

➡️ 유저 가이드를 따라 nachocode 푸시 알림 설정을 완료하세요.

타입 정의

`PushTokenResult`

since : v1.6.3

export declare type PushTokenResult =
  | {
      status: 'success';
      statusCode: 201;
      message: string;
    }
  | {
      status: 'error';
      statusCode: number;
      message: string;
      desc: string;
      code: string;
    };

속성명	타입	필수 여부	설명
`status`	`'success' \| 'error'`	✅	푸시 토큰 요청 성공 여부
`statusCode`	`number`	✅	푸시 토큰 결과 상태 코드
`message`	`string`	✅	결과 상세 메시지. (에러 발생 시 사유 반환)
`desc`	`string`	❌	*(optional)* 오류 상세 내용 (에러 발생 시)
`code`	`string`	❌	*(optional)* 오류 코드 (에러 발생 시)

`PushTopicResult`

since : v1.6.0
lastupdated : v1.6.1

export declare type PushTopicResult =
  | {
      status: 'success';
      /**
       * 푸시 토픽 구독 결과 상태 코드
       * - `200` : 성공
       * - `201` : 이미 토픽 구독 중
       * - `202` : 이미 구독 취소된 토픽
       * - `203` : FCM 구독 성공, nachocode 서버 저장 실패
       */
      statusCode: 200 | 201 | 202 | 203;
      message: string;
    }
  | {
      status: 'error';
      /**
       * 푸시 토픽 구독 결과 상태 코드
       * - `400` : 잘못된 요청
       * - `401` : 구독 실패
       * - `402` : 구독 취소 실패
       * - `500` : 내부 오류
       */
      statusCode: 400 | 401 | 402 | 500;
      errorCode: string; // 실패 시 에러 반환
      message: string; // 실패 시 에러 상세 사유 반환
    };

속성명	타입	필수 여부	설명
`status`	`'success' \| 'error'`	✅	푸시 토픽 구독 요청 성공 여부
`statusCode`	`number`	✅	푸시 토픽 구독 결과 상태 코드
`errorCode`	`string`	❌	*(optional)* 오류 코드 (에러 발생 시)
`message`	`string`	✅	결과 상세 메시지. (에러 발생 시 사유 반환)

`LocalPushPayload`

since : v1.4.1

export declare type LocalPushPayload = {
  title: string;
  content?: string;
  link?: string; // link willing to move when clicked
  usingAppIcon?: boolean; // default : true
  scheduledTime?: Date; // sends instantly if not set
  id?: number; // generates if not set
};

속성명	타입	필수 여부	설명
`title`	`string`	✅	푸시 알림의 제목
`content`	`string`	❌	*(optional)* 푸시 알림의 본문 메시지 (지정하지 않으면 제목만 노출)
`link`	`string`	❌	*(optional)* 클릭 시 이동할 URL (지정하지 않으면 앱 열기)
`usingAppIcon`	`boolean`	❌	*(optional)* 앱 아이콘을 푸시 아이콘으로 사용할지 여부 (기본값: `true`)
`scheduledTime`	`Date`	❌	*(optional)* 예약된 발송 시각 (지정하지 않으면 즉시 발송됨)
`id`	`number`	❌	*(optional)* 예약된 푸시를 식별할 ID (지정하지 않으면 자동 생성)

`LocalPushResult`

since : v1.4.1

export declare type LocalPushResult = {
  status: 'success' | 'error';
  statusCode?: string; // error code when failed
  message?: string; // error message when failed
  id?: number; // push notification id
};

속성명	타입	필수 여부	설명
`status`	`'success' \| 'error'`	✅	푸시 알림 예약 성공 여부
`statusCode`	`string`	❌	*(optional)* 오류 발생 시 반환되는 코드
`message`	`string`	❌	*(optional)* 오류 발생 시 반환되는 메시지
`id`	`number`	❌	*(optional)* 예약된 푸시 알림의 ID (취소할 때 사용 가능)

메서드 목록

메서드	설명	추가된 버전
`subscribePushTopic(topic)`	푸시 토픽을 구독합니다.	v1.6.0
`unsubscribePushTopic(topic)`	푸시 토픽 구독을 취소합니다.	v1.6.0
`getSubscriptionList(callback)`	디바이스의 현재 구독 중인 푸시 토픽 목록을 조회합니다.	v1.6.0
`sendLocalPush(payload, callback?)`	로컬 푸시 알림을 예약합니다.	v1.4.1
`cancelLocalPush(id)`	예약된 로컬 푸시 알림을 취소합니다.	v1.4.1
`registerPushToken(userId)`	nachocode 서버에 푸시 토큰을 등록합니다.	v1.0.0
`deletePushToken(userId?)`	nachocode 서버에서 푸시 토큰을 삭제합니다.	v1.0.0

메서드 상세

since : v1.6.0
lastupdated : v1.6.1

주의

필수 선행 작업이 완료되어야 사용할 수 있습니다.

지정한 푸시 토픽을 구독합니다. 구독이 성공하면 nachocode 서버 API를 통해서 발송하거나 FCM에서 해당 토픽으로 직접 발송한 메시지를 수신할 수 있습니다.

이름	타입	필수 여부	설명
`topic`	`string`	✅	구독할 토픽 이름

타입	설명
`Promise<PushTopicResult>`	구독 성공 또는 실패 정보를 포함함

try {
  const result = await Nachocode.push.subscribePushTopic('event-promotion');
  if (result.status === 'success') {
    console.log('토픽 구독 성공');
  } else {
    console.error('토픽 구독 실패:', result.message);
  }
} catch (err) {
  console.error('토픽 구독 중 오류 발생:', err);
}

`unsubscribePushTopic(topic: string): Promise<PushTopicResult>`

since : v1.6.0
lastupdated : v1.6.1

주의

필수 선행 작업이 완료되어야 사용할 수 있습니다.

설명

지정한 푸시 토픽 구독을 해지합니다. 이후 해당 토픽으로 발송된 메시지를 더 이상 수신하지 않게 됩니다.

매개변수

이름	타입	필수 여부	설명
`topic`	`string`	✅	해지할 토픽 이름

반환 값

타입	설명
`Promise<PushTopicResult>`	구독 해지 성공 또는 실패 정보를 포함

사용 예제

try {
  const result = await Nachocode.push.unsubscribePushTopic('event-promotion');
  if (result.status === 'success') {
    console.log('토픽 구독 해지 성공');
  } else {
    console.error('토픽 구독 해지 실패:', result.message);
  }
} catch (err) {
  console.error('토픽 구독 해지 중 오류 발생:', err);
}

`getSubscriptionList(callback)`

since : v1.6.0

주의

필수 선행 작업이 완료되어야 사용할 수 있습니다.

설명

현재 디바이스에서 구독 중인 푸시 토픽 목록을 조회합니다.

매개변수

이름	타입	필수 여부	설명
`callback`	`(subscriptionList: string[]) => void`	✅	구독된 토픽 이름 목록을 콜백으로 수신

사용 예제

Nachocode.push.getSubscriptionList(list => {
  console.log('현재 구독 중인 토픽 목록:', list);
});

`sendLocalPush(payload, callback?)`

since : v1.4.1

설명

로컬 푸시 알림을 예약하고, 특정 시각(scheduledTime)에 디바이스에서 푸시 알림을 표시할 수 있습니다. 즉시 발송하거나 예약 발송이 가능하며, 예약된 알림은 id 값을 사용해 취소할 수도 있습니다.

매개변수

이름	타입	필수 여부	설명
`payload`	`LocalPushPayload`	✅	예약할 로컬 푸시 데이터
`callback`	`(result: LocalPushResult) => void`	❌	예약 성공 여부를 반환하는 콜백

반환 값

해당 메서드는 반환 값을 가지지 않으며, 결과는 callback을 통해 비동기적으로 제공됩니다.

사용 예제

// 1. 즉시 발송 (예약 시간 없이)
// `scheduledTime`을 지정하지 않으면 즉시 발송됩니다.
Nachocode.push.sendLocalPush(
  {
    title: '깜짝 쿠폰 발송!',
    content: '지금 바로 앱에서 확인해보세요!.',
    link: 'https://nachocode.io/pricing',
  },
  result => {
    if (result.status === 'success') {
      console.log(`푸시 알림이 즉시 발송되었습니다.`);
    } else {
      console.error(`푸시 알림 발송 실패: ${result.message}`);
    }
  }
);

// 2. 예약 발송
// `scheduledTime`을 지정하면 해당 시각에 알림이 표시됩니다.
Nachocode.push.sendLocalPush(
  {
    title: '미팅 알림',
    content: '회의 시작 10분 전입니다.',
    scheduledTime: new Date('2025-03-01T10:00:00Z'),
    id: 101,
  },
  result => {
    if (result.status === 'success') {
      console.log(`푸시 알림이 예약되었습니다. (ID: ${result.id})`);
    } else {
      console.error(`푸시 예약 실패: ${result.message}`);
    }
  }
);

`cancelLocalPush(id: number)`

since : v1.4.1

설명

예약된 로컬 푸시 알림을 취소합니다. 취소하려는 푸시 알림의 id 값을 전달해야 합니다.

sendLocalPush에서 반환된 id를 사용합니다.

매개변수

이름	타입	필수 여부	설명
`id`	`number`	✅	취소할 예약된 푸시 알림의 ID

반환 값

해당 메서드는 반환 값을 가지지 않습니다.

사용 예제

// 예약된 푸시 알림 취소
Nachocode.push.cancelLocalPush(101);
console.log('푸시 알림이 취소되었습니다.');

`registerPushToken(userId: string): Promise<PushTokenResult>`

since : v1.0.0
lastupdated : 반환 타입 변경, 내부 로직 최적화 v1.6.3

주의

필수 선행 작업이 완료되어야 사용할 수 있습니다.

설명

nachocode 서버에 현재 디바이스의 푸시 토큰을 등록합니다. 이때, 특정 사용자(userId)를 식별자로 사용하여 푸시 알림을 해당 사용자에게 전송할 수 있도록 설정합니다.

푸시 토큰이란?

푸시 토큰 가이드에서 상세 설명을 확인해보세요.

매개변수

이름	타입	필수 여부	설명
`userId`	`string`	✅	푸시 토큰을 연결할 사용자 ID

반환 값

타입	설명
`Promise<PushTokenResult>`	푸시 토큰 등록 요청의 처리 결과

사용 예제

// ex. 유저의 로그인 성공 시 호출되는 콜백함수
function onLoginSuccess(userId) {
  // ex. userId : "nacho123"
  // "nacho123" 사용자 식별자로 푸시토큰을 nachocode 서버에 등록합니다.
  Nachocode.push.registerPushToken(userId).then(result => {
    if (result.status === 'success') {
      console.log('푸시 토큰이 성공적으로 등록되었습니다.');
    } else {
      console.error(`푸시 토큰 등록 실패: ${result.message}`);
    }
  });
}

`deletePushToken(userId?: string): Promise<PushTokenResult>`

since : v1.0.0
lastupdated : 반환 타입 변경, 내부 로직 최적화 v1.6.3

주의

필수 선행 작업이 완료되어야 사용할 수 있습니다.

설명

nachocode 서버에서 해당 사용자(userId)와 연결된 푸시 토큰을 삭제합니다. 사용자가 로그아웃하거나 푸시 알림을 더 이상 사용하지 않도록 설정할 경우 이 메서드를 호출해야 합니다.

푸시 토큰이란?

푸시 토큰 가이드에서 상세 설명을 확인해보세요.

매개변수

이름	타입	필수 여부	설명
`userId`	`string`	❌	삭제할 푸시 토큰이 연결된 사용자 ID

반환 값

타입	설명
`Promise<PushTokenResult>`	푸시 토큰 삭제 요청의 처리 결과

사용 예제

// 현재 디바이스 토큰 삭제 (userId 생략 가능)
Nachocode.push.deletePushToken().then(result => {
  if (result.status === 'success') {
    console.log('현재 디바이스의 푸시 토큰이 삭제되었습니다.');
  } else {
    console.error(`푸시 토큰 삭제 실패: ${result.message}`);
  }
});

// ex. 유저의 로그아웃 시 호출되는 콜백함수
function onLogout(userId) {
  // ex. userId : "nacho123"
  // "nacho123" 사용자 식별자에 해당하는 푸시 토큰을 삭제합니다.
  Nachocode.push.deletePushToken(userId).then(() => {
    if (result.status === 'success') {
      console.log('유저 푸시 토큰이 성공적으로 삭제되었습니다.');
    } else {
      console.error(`푸시 토큰 삭제 실패: ${result.message}`);
    }
  });
}

개요​

필수 선행 작업​

타입 정의​

PushTokenResult​

PushTopicResult​

LocalPushPayload​

LocalPushResult​

메서드 목록​

메서드 상세​

subscribePushTopic(topic: string): Promise<PushTopicResult>​

설명​

매개변수​

반환 값​

사용 예제​

unsubscribePushTopic(topic: string): Promise<PushTopicResult>​

설명​

매개변수​

반환 값​

사용 예제​

getSubscriptionList(callback)​

설명​

매개변수​

사용 예제​

sendLocalPush(payload, callback?)​

설명​

매개변수​

반환 값​

사용 예제​

cancelLocalPush(id: number)​

설명​

매개변수​

반환 값​

사용 예제​

registerPushToken(userId: string): Promise<PushTokenResult>​

설명​

매개변수​

반환 값​

사용 예제​

deletePushToken(userId?: string): Promise<PushTokenResult>​

설명​

매개변수​

반환 값​

사용 예제​

개요

필수 선행 작업

타입 정의

`PushTokenResult`

`PushTopicResult`

`LocalPushPayload`

`LocalPushResult`

메서드 목록

메서드 상세

`subscribePushTopic(topic: string): Promise<PushTopicResult>`

설명

매개변수

반환 값

사용 예제

`unsubscribePushTopic(topic: string): Promise<PushTopicResult>`

설명

매개변수

반환 값

사용 예제

`getSubscriptionList(callback)`

설명

매개변수

사용 예제

`sendLocalPush(payload, callback?)`

설명

매개변수

반환 값

사용 예제

`cancelLocalPush(id: number)`

설명

매개변수

반환 값

사용 예제

`registerPushToken(userId: string): Promise<PushTokenResult>`

설명

매개변수

반환 값

사용 예제

`deletePushToken(userId?: string): Promise<PushTokenResult>`

설명

매개변수

반환 값

사용 예제